🤖 코딩 에이전트의 비밀, 6가지 구성 요소로 완전 해부

 

"같은 AI인데 왜 이렇게 다르지?"

Claude Code나 Cursor를 처음 써보셨을 때 이런 생각 해보셨나요? 그냥 채팅창에서 쓰는 AI랑 분명히 같은 모델인데, 코딩 도구로 쓰면 훨씬 더 똑똑하게 느껴지는 거 있잖아요.

"이 함수 고쳐줘"라고 말했을 뿐인데, AI가 저장소 구조를 파악하고, 관련 파일을 찾고, 테스트까지 돌려주는 경험을 해보셨다면 그게 정확히 그 차이점을 느낀 순간입니다.

그 답을 한마디로 정리하면, 모델 자체가 달라서가 아니에요. 모델을 감싸고 있는 시스템, 즉 에이전트 하네스(Agent Harness)가 다른 겁니다.

머신러닝 연구자 Sebastian Raschka 박사가 코딩 에이전트의 핵심 구성 요소 6가지를 정리했는데, 이 내용이 Claude Code를 비롯한 AI 코딩 도구를 이해하는 데 정말 좋은 프레임을 제공해서 풀어보려고 합니다.

LLM, 추론 모델, 에이전트, 뭐가 다른 거예요?

본론 전에 개념 정리를 먼저 해드릴게요. 이 세 가지가 혼용돼서 쓰이는 경우가 많거든요.

LLM은 다음 토큰을 예측하는 기반 모델 그 자체입니다. GPT, Claude, Gemini 같은 거죠. 추론 모델(Reasoning Model)은 이 LLM에다가 중간 추론 과정을 더 많이 거치도록 훈련한 버전이에요. o1이나 Claude Sonnet 같은 게 대표적이고요. 에이전트는 이 모델 위에 제어 루프(Control Loop)를 얹은 개념입니다. 목표가 주어지면 어떤 도구를 쓸지, 언제 멈출지를 스스로 결정하는 구조예요.

비유하자면 LLM은 엔진, 추론 모델은 터보 엔진, 에이전트 하네스는 그 엔진을 달고 달리는 자동차 전체예요. 엔진이 아무리 좋아도 차체 없이는 제대로 달릴 수 없잖아요.

코딩 하네스는 이 에이전트 하네스 중에서도 소프트웨어 작업에 최적화된 버전입니다. Claude Code, Codex CLI, Cursor가 바로 여기에 해당하죠.

코딩은 코드만 짜는 게 아니에요

많은 분들이 놓치는 게 있어요. 실제 개발 작업은 코드 한 줄 쓰는 것보다 훨씬 복잡하거든요.

개발을 해보셨다면 아실 거예요. 저장소 탐색, 함수 검색, 변경 사항 적용, 테스트 실행, 오류 검토, 관련 정보 유지까지, 실제 코딩 작업의 절반 이상은 코드 자체가 아니라 컨텍스트 관리에 쓰입니다.

AI도 마찬가지예요. 아무리 좋은 모델이라도 저장소 구조를 모르고, 어떤 테스트를 실행해야 하는지도 모르면서 "테스트 고쳐줘"라는 요청을 받으면 제대로 할 수가 없어요. 좋은 코딩 하네스는 이 맥락 관리를 AI 대신 처리해주는 시스템입니다.

이제 그 시스템을 구성하는 6가지 요소를 하나씩 살펴볼게요.

구성 요소 1: 실시간 저장소 맥락 (Live Repo Context)

코딩 에이전트가 제일 먼저 하는 일은 작업 공간의 전체 상황을 파악하는 겁니다.

"테스트를 고쳐줘"라는 요청은 그 자체로는 아무 정보도 없어요. 에이전트는 먼저 이런 것들을 파악해야 합니다. 지금 어떤 Git 저장소에 있는지, 현재 브랜치가 무엇인지, AGENTS.md나 README에 어떤 지침이 있는지, 어떤 테스트 명령어를 써야 하는지를요.

이 워크스페이스 요약을 미리 만들어 두면 에이전트는 매번 처음부터 헤매지 않아도 됩니다. 이 초기 맥락 수집이 코딩 에이전트의 기본 중의 기본이에요.

Claude Code에 CLAUDE.md 파일을 놓는 이유가 바로 이거예요. 에이전트가 저장소를 처음 열었을 때 참조할 워크스페이스 가이드를 미리 깔아두는 거죠.

구성 요소 2: 프롬프트 구조와 캐시 재활용 (Prompt Shape and Cache Reuse)

워크스페이스 정보를 파악했다면 이걸 어떻게 모델에게 전달하느냐가 문제입니다.

매번 대화할 때마다 모든 정보를 처음부터 다시 구성한다면 엄청난 낭비겠죠. 실제로 코딩 세션에서 자주 바뀌지 않는 부분이 있어요. 에이전트 사용 규칙, 도구 설명, 워크스페이스 요약 같은 것들은 대부분 세션 내내 거의 변하지 않습니다.

영리한 런타임은 이 안정적인 프롬프트 접두어(Stable Prompt Prefix)를 캐시로 재활용해요. 그리고 실제로 자주 바뀌는 것들, 최근 사용자 요청, 최근 대화 내역, 단기 메모리 정도만 매 턴마다 새로 업데이트합니다.

이게 성능과 비용 효율을 동시에 잡는 방법이에요. 같은 컨텍스트를 반복해서 토큰으로 처리하지 않아도 되니까요.

구성 요소 3: 구조화된 도구 접근 (Structured Tool Access)

에이전트처럼 느껴지는 순간이 언제냐고요? 바로 도구를 실제로 실행할 때입니다.

일반 채팅 AI는 "이런 명령어를 써보세요"라고 코드를 알려줘요. 그러면 우리가 직접 터미널에서 실행하고 결과를 다시 붙여넣어야 하죠. 코딩 에이전트는 달라요. 직접 실행하고 결과를 받아와요.

물론 무한정 다 실행하게 두면 위험하겠죠. 그래서 하네스는 허용된 도구 목록을 미리 정해두고, 파일 경로가 워크스페이스 안에 있는지 검사하고, 필요하면 사용자 승인을 요청합니다. 모델에게 자유를 조금 제한하는 대신 안전성과 신뢰도를 높이는 거예요.

Claude Code에서 처음 실행할 때 권한을 물어보는 이유가 여기 있습니다. 하네스가 도구 사용의 범위를 명확하게 통제하는 거예요.

구성 요소 4: 컨텍스트 팽창 방지 (Minimizing Context Bloat)

LLM의 컨텍스트 창이 점점 길어지고 있지만, 그렇다고 무한정 쌓아두는 게 좋은 건 아니에요.

긴 컨텍스트는 비용도 비싸고, 관련 없는 정보가 많으면 오히려 모델 성능이 떨어질 수 있거든요. 코딩 에이전트는 이 문제가 더 심각해요. 반복적인 파일 읽기, 긴 도구 출력, 로그 등이 계속 쌓이니까요.

그래서 좋은 코딩 하네스는 두 가지 전략을 씁니다. 하나는 클리핑(Clipping)으로, 긴 출력물을 잘라내서 한 항목이 너무 많은 컨텍스트를 차지하지 않도록 해요. 다른 하나는 대화 내역 압축(Transcript Reduction)으로, 세션 히스토리를 요약하는 거예요. 이때 최근 내용일수록 더 풍부하게 남기고, 오래된 내용은 더 공격적으로 압축합니다.

모델 품질의 상당 부분은 사실 컨텍스트 품질이에요. 아무리 좋은 모델도 쓰레기 컨텍스트를 받으면 쓰레기를 출력합니다. 이걸 시스템 레벨에서 관리해주는 게 하네스의 역할 중 하나예요.

구성 요소 5: 구조화된 세션 메모리 (Structured Session Memory)

에이전트는 대화가 길어져도 중요한 걸 잊으면 안 됩니다. 이를 위해 두 가지 레이어를 씁니다.

첫 번째는 작업 메모리(Working Memory)예요. 현재 작업, 중요 파일, 최근 메모 같은 핵심 정보를 작게 유지하는 레이어입니다. 두 번째는 전체 대화 기록(Full Transcript)으로, 모든 사용자 요청, 도구 출력, AI 응답을 기록하는 전체 히스토리예요.

이 두 가지는 보통 JSON 파일로 디스크에 저장됩니다. 덕분에 에이전트 세션을 닫았다가 다시 열어도 이어서 작업할 수 있어요. 인간으로 치면 메모장(전체 기록)과 포스트잇(핵심 메모)을 같이 쓰는 것과 비슷해요.

이 구조 덕분에 "아까 말한 그 기능 추가해줘"라는 말이 통하는 거예요. 에이전트가 컨텍스트를 잃지 않고 이어서 작업할 수 있거든요.

구성 요소 6: 서브에이전트 위임 (Delegation with Bounded Subagents)

마지막으로, 복잡한 작업은 나눠서 처리하는 게 효율적이에요.

메인 에이전트가 한 작업을 하다가 "이 함수가 어느 파일에 정의되어 있지?", "이 설정 파일이 뭘 하는 거지?" 같은 곁가지 질문이 생길 수 있어요. 이걸 메인 루프에서 처리하면 흐름이 끊기죠.

서브에이전트는 이런 부분 작업을 위임받아 처리합니다. 핵심은 충분히 유용하되, 적절히 제한된 서브에이전트를 만드는 거예요. 메인 에이전트의 컨텍스트는 상속받되, 읽기 전용으로 제한하거나 재귀 깊이를 제한하는 식으로요.

Claude Code는 오래전부터 서브에이전트를 지원해왔고, Codex도 최근 추가했습니다. 복잡한 작업을 병렬로 처리하거나 역할을 분리해서 더 정확하게 수행할 수 있게 해주는 기능이에요.

6가지를 알면 도구가 달리 보입니다

이 6가지를 정리하면 맥락 수집, 캐시 재활용, 도구 구조화, 컨텍스트 압축, 세션 메모리, 서브에이전트 위임입니다.

코딩 에이전트가 단순 채팅 AI보다 훨씬 강력한 이유는 결국 이 시스템 레이어 때문이에요. 같은 모델을 쓰더라도 하네스 설계에 따라 성능 차이가 크게 날 수 있다는 점이 흥미롭죠.

2026년 현재, DORA Report 기준 전문 개발자의 90% 이상이 일상 워크플로우에서 AI 코딩 도구를 사용하고 있어요. 에이전틱 AI 시장은 2025년 약 2조 원에서 2030년 61조 원 규모로 연평균 175% 성장이 전망됩니다. GitHub 통계를 보면 2025년 한 해에만 월평균 풀 리퀘스트 수가 23%, 커밋 수가 25% 증가했고요. 이미 구글 내부에서도 신규 코드의 25% 이상을 AI가 작성하고 있다고 알려져 있습니다.

이제 AI 코딩 도구를 쓰느냐 마느냐가 아니라, 이 도구가 어떻게 작동하는지 이해하고 제대로 활용하는 능력이 개발자의 실력을 가르는 기준이 되고 있어요.

왜 CLAUDE.md를 잘 써야 하는지 이제 이해되시죠?

이 6가지 구성 요소를 이해하고 나면, 그동안 왜 그런 설정들이 중요하다고 하는지 맥락이 잡힙니다.

CLAUDE.md를 정성껏 쓰는 건 구성 요소 1번인 실시간 저장소 맥락을 잘 구성해주는 행위예요. 에이전트에게 워크스페이스의 지도를 그려주는 거죠. 긴 작업 중간에 요약을 요청하거나 핵심 결정 사항을 명시적으로 메모해두는 것도 구성 요소 5번인 세션 메모리를 보조하는 방법이고요.

"이 에이전트가 왜 이렇게 행동하지?"라는 궁금증도 이제 구성 요소 단위로 분석할 수 있게 됩니다. 컨텍스트가 너무 길어져서 중요한 정보가 희석된 건지, 도구 접근 권한이 없어서 못 하는 건지, 서브에이전트 위임이 필요한 복잡도인지를요.

AI 코딩 도구를 블랙박스로 쓰는 것과 내부 구조를 이해하고 쓰는 것 사이에는 생산성의 차이가 있어요. 같은 도구를 쓰더라도 이 프레임을 알고 있는 사람이 훨씬 더 효과적으로 활용할 수 있거든요.

마무리

코딩 에이전트의 핵심은 모델 자체보다 그것을 감싸는 하네스 시스템에 있습니다. 실시간 저장소 맥락, 캐시 최적화, 도구 구조화, 컨텍스트 관리, 세션 메모리, 서브에이전트라는 6가지 구성 요소가 모여 AI를 단순 채팅봇에서 진짜 개발 파트너로 바꿔줘요.

AI 코딩 도구를 쓰고 있다면, 이 구조를 이해하는 것만으로도 활용도가 크게 달라질 겁니다. 지금 쓰는 도구를 다시 한번 이 프레임으로 바라보시면 어떨까요?