한줄 요약
코딩 에이전트의 강점은 모델이 아니라 그것을 감싸는 시스템 설계에 있다.
어떤 상황에서 필요한가?
Claude Code나 Codex CLI를 쓰면서 "같은 모델인데 왜 채팅창보다 훨씬 잘하지?"라는 의문을 가진 적이 있다면, 이 글이 그 답을 준다. 단순히 모델을 API로 호출하는 것과 에이전트 하네스(agent harness)로 감싸는 것은 근본적으로 다른 접근이다. 실무에서 LLM 기반 코딩 도구를 만들거나 도입하려는 사람이라면 이 구조를 이해하는 것이 출발점이다.
핵심 구현 방법
1단계: 개념부터 분리하라, LLM, 추론 모델, 에이전트는 다르다
세 개념을 하나로 묶어서 생각하면 시스템 설계가 흐릿해진다.
- LLM: 다음 토큰을 예측하는 기본 모델. 엔진 그 자체다.
- 추론 모델(Reasoning Model): LLM의 일종이지만, 중간 추론 과정을 더 많이 생성하도록 훈련되거나 프롬프트된 모델이다. 더 강력하지만 그만큼 추론 비용도 높다.
- 에이전트: 모델을 감싸는 제어 루프다. 목표가 주어지면 무엇을 다음에 볼지, 어떤 툴을 호출할지, 언제 멈출지를 결정한다.
여기에 두 가지 개념이 추가된다.
- 에이전트 하네스(Agent Harness): 에이전트를 둘러싼 소프트웨어 스캐폴드. 컨텍스트, 툴 사용, 프롬프트, 상태, 제어 흐름을 관리한다.
- 코딩 하네스(Coding Harness): 에이전트 하네스의 특수한 형태로, 소프트웨어 엔지니어링에 특화되어 있다. Claude Code와 Codex CLI가 여기에 해당한다.
2단계: 코딩 하네스의 세 레이어를 이해하라
코딩 하네스는 크게 세 층으로 나뉜다.
- 모델 패밀리(Model Family): 엔진 역할. 기반이 되는 LLM 혹은 추론 모델이다.
- 에이전트 루프(Agent Loop): 반복적 문제 해결을 구동하는 핵심 제어 구조다. 모델이 한 번 생성하고 끝나는 게 아니라, 결과를 보고 다음 행동을 결정하며 계속 순환한다.
- 런타임 지원(Runtime Supports): 툴 실행, 메모리, 컨텍스트 관리 등 실제 동작을 가능하게 하는 배관(plumbing) 역할이다.
3단계: 코딩 작업이 왜 하네스를 필요로 하는지 인식하라
코딩은 단순히 텍스트를 생성하는 작업이 아니다. 실제 코딩 작업의 상당 부분은 다음을 포함한다.
- 저장소 탐색(repo navigation)
- 함수 검색(function lookup)
- diff 적용
- 테스트 실행 및 오류 검사
- 관련 정보를 컨텍스트 안에 유지하기
이런 작업들은 단순한 토큰 생성으로 해결되지 않는다. 하네스가 이 모든 과정을 조율해 주기 때문에, 동일한 모델이라도 하네스 유무에 따라 실전 성능 차이가 크게 느껴지는 것이다.
4단계: 주요 구성 요소 6가지를 파악하라
원문에서 코딩 에이전트의 주요 구성 요소로 여섯 가지를 제시한다. 각 요소는 독립적으로 작동하지 않고 서로 맞물려 전체 시스템을 구성한다.
- 툴 사용(Tool Use): 파일 읽기/쓰기, 터미널 실행, 검색 등 외부 환경과의 상호작용
- 메모리(Memory): 세션 내외에서 관련 정보를 유지하는 구조
- 저장소 컨텍스트(Repo Context): 현재 코드베이스의 구조와 내용을 모델에 전달하는 방식
- 프롬프트 캐시 안정성(Prompt-Cache Stability): 반복 호출 시 비용과 속도를 최적화하는 설계
- 긴 세션 연속성(Long-Session Continuity): 대화가 길어져도 작업 흐름을 유지하는 능력
- 에이전트 루프 제어(Agent Loop Control): 언제 멈추고, 무엇을 다음에 할지 결정하는 로직
