에이전트 하네스: 모델을 일하는 시스템으로 만드는 설계 가이드

하네스란 무엇이고 왜 필요한가

LangChain 글글은 에이전트를 '모델 + 하네스'로 정의한다. 하네스는 모델 자체가 아닌 모든 코드, 설정, 실행 로직이다. 이 글은 "모델이 아니면 하네스다"라고 정리하며, 날것의 모델은 에이전트가 아니고 하네스가 상태 저장, 도구 실행, 피드백 고리, 강제할 수 있는 제약을 줄 때 비로소 에이전트가 된다고 설명한다.

이유는 단순하다. 모델은 텍스트·이미지 같은 입력을 받아 텍스트를 내놓을 뿐이다. 같은 글글에 따르면 모델은 기본 상태로는 대화를 넘어 상태를 유지하거나, 코드를 실행하거나, 실시간 정보에 접근하거나, 작업 환경을 꾸리고 패키지를 설치하지 못한다. 우리가 늘 쓰는 '채팅'도 사실 이전 메시지를 기억해 새 메시지를 덧붙이는 반복문으로 모델을 감싼 가장 단순한 하네스다.

하네스의 효과는 연구로도 확인됐다. SWE-agent논문는 모델 가중치를 바꾸지 않고, 모델이 컴퓨터를 다루는 인터페이스(저자들은 ACI, Agent-Computer Interface라고 부른다)만 설계해 성능을 끌어올렸다. GPT-4 Turbo 기반으로 SWE-bench 테스트 과제의 12.47%를 풀어, 이전 최고였던 비대화형 검색 증강 방식의 3.8%를 크게 넘어섰다. 하네스 설계가 모델 선택만큼 중요하다는 근거다.

코딩 에이전트에서는 두 겹을 구분하면 편하다. Martin Fowler 사이트 글글은 시스템 프롬프트나 코드 검색 방식처럼 제품에 이미 들어 있는 부분과, 사용자가 자기 저장소와 용도에 맞게 덧씌우는 '바깥 하네스(outer harness)'를 나눈다. 이 가이드의 적용 단계는 주로 이 바깥 하네스를 다룬다.

구성 요소: 하네스는 무엇으로 이뤄지나

LangChain 글글이 꼽는 하네스 구성은 다음과 같다. 시스템 프롬프트, 도구·스킬·MCP와 그 설명, 함께 제공되는 인프라(파일시스템, 샌드박스, 브라우저), 오케스트레이션 로직(서브에이전트 생성, 작업 넘기기, 모델 라우팅), 그리고 결정적으로 실행되는 훅·미들웨어(컨텍스트 압축, 작업 이어가기, 린트 검사)다. 여기에 이 가이드는 결과를 확인하는 검증 장치를 따로 떼어 본다.

실행 환경 쪽에서 같은 글글은 파일시스템을 가장 기초적인 요소로 본다. 에이전트가 데이터·코드·문서를 읽는 작업 공간이 되고, 컨텍스트에 다 담지 못하는 내용을 덜어 두며, 세션이 끝나도 남는 상태를 보관하기 때문이다. git을 더하면 작업 추적과 되돌리기가 가능해진다. 범용 도구로는 bash와 코드 실행을 주는 것이 기본 전략이 됐고, 생성된 코드를 안전하게 돌리기 위해 샌드박스(격리된 실행 환경)를 쓰며 명령 허용 목록과 네트워크 격리를 더할 수 있다.

컨텍스트 관리와 메모리도 하네스의 일이다. 컨텍스트 윈도가 차면 추론 능력이 떨어지는 현상을 Context Rot라고 부르는데, 하네스는 압축(compaction)으로 기존 내용을 요약·이동해 작업을 이어 가게 한다글. AGENTS.md 같은 메모리 파일은 에이전트 시작 시 컨텍스트에 주입되어 세션 사이에 지식을 이어 준다.

서브에이전트는 독립적인 하위 작업을 각자 분리된 컨텍스트에서 병렬로 처리하게 하는 장치다글. Anthropic 에이전트 구축 글글의 orchestrator-workers 패턴도 같은 구조로, 중앙 LLM이 작업을 나눠 작업자 LLM에 맡기고 결과를 합치며, 바꿀 파일 수를 미리 알 수 없는 코딩 작업에 맞는다고 설명한다.

설계 원칙: 출처들이 공통으로 말하는 것

첫째, 단순하게 시작한다. Anthropic 에이전트 구축 글글은 가장 단순한 해법을 찾고 필요할 때만 복잡도를 높이라고 권한다. 프레임워크는 시작을 쉽게 하지만 실제 프롬프트와 응답을 가려 디버깅을 어렵게 할 수 있으니, LLM API를 직접 쓰는 것부터 시작하고 프레임워크를 쓴다면 내부 동작을 이해하라고 밝혔다.

둘째, 컨텍스트는 아껴 쓰는 자원이다. Anthropic 컨텍스트 엔지니어링 글글은 원하는 결과를 낼 가능성을 최대로 하는 '가장 작은 고신호 토큰 집합'을 찾으라고 한다. 시스템 프롬프트는 깨지기 쉬운 if-else식 하드코딩과 막연한 일반론 사이의 '적절한 고도'로 쓰고, 최소한의 프롬프트를 좋은 모델로 시험한 뒤 실패 사례를 보며 지시와 예시를 더하라고 권한다. 예외 사례를 빼곡히 나열하기보다 다양한 대표 예시를 고르라는 것도 같은 글의 권고다.

셋째, 도구는 모델을 위한 인터페이스로 설계한다. SWE-agent논문는 옵션이 수십 개인 bash 명령 대신 파일 보기·검색·편집 같은 단순한 명령 몇 개를 주고, 흔한 실수를 막는 가드레일과 매 턴 짧고 구체적인 피드백을 제공했다. 사람은 불필요한 정보를 무시할 수 있지만 모델에게는 모든 내용이 비용이라는 점도 지적한다. Anthropic 도구 작성 글글과 컨텍스트 글글도 기능이 겹치지 않는 최소한의 도구, 명확한 이름 구분(namespacing), 토큰 효율적인 응답, 잘 다듬은 도구 설명을 강조하며 "사람 엔지니어가 어떤 도구를 써야 할지 단정하지 못하면 에이전트도 못 한다"고 말한다.

넷째, 가이드와 센서를 함께 둔다. Martin Fowler 사이트 글글은 행동 전에 방향을 잡는 가이드(feedforward)와 행동 뒤 관찰해 스스로 고치게 하는 센서(feedback)를 구분한다. 피드백만 있으면 같은 실수를 반복하고, 가이드만 있으면 규칙이 통했는지 끝내 모른다. 또 테스트·린터·타입 검사 같은 계산적(computational) 장치는 빠르고 결정적이라 매 변경마다 돌리기 좋고, AI 코드 리뷰나 LLM-as-a-Judge 같은 추론적(inferential) 장치는 느리고 비결정적이지만 의미 판단을 더해 준다고 정리한다.

코딩 에이전트에 하네스를 적용하는 단계

1단계는 최소 구성으로 시작하는 것이다. 좋은 모델과 짧은 시스템 프롬프트, bash·파일 편집 같은 기본 도구로 실제 작업을 몇 개 맡겨 보고 어디서 막히는지 기록한다글글. 처음부터 규칙을 잔뜩 쓰지 않는다.

2단계는 저장소에 '지도'를 만드는 것이다. OpenAI 글글은 하나의 거대한 AGENTS.md가 실패했다고 밝혔다. 컨텍스트를 잠식하고, 모든 것이 중요하면 아무것도 중요하지 않게 되며, 금방 낡고, 기계적으로 검증하기 어려웠기 때문이다. 대신 약 100줄짜리 AGENTS.md를 목차로 두고, 설계 문서·실행 계획·제품 명세를 구조화된 docs/ 디렉터리에 두어 '기록의 원천'으로 삼았다. 에이전트가 작은 진입점에서 출발해 다음에 어디를 볼지 배우는 점진적 공개(progressive disclosure) 방식이다.

3단계는 검증 장치를 연결하는 것이다. 테스트·린터·타입 검사를 에이전트가 직접 돌릴 수 있게 하고, 커밋 전 훅으로 모듈 경계 위반을 검사하는 식의 계산적 센서를 먼저 깐다글. 린터 오류 메시지에 고치는 방법을 함께 적어 두면 모델이 바로 읽고 고칠 수 있다는 것도 같은 글의 제안이다. 웹 앱이라면 브라우저 자동화 도구로 사람처럼 끝까지 확인하게 한다글.

4단계는 실행 환경을 격리하고 관찰 가능하게 만드는 것이다. OpenAI 글글은 git worktree마다 앱을 띄울 수 있게 하고, Chrome DevTools Protocol과 로그·지표·트레이스를 에이전트가 직접 질의하게 만들어 버그 재현과 수정 검증을 맡겼다. 5단계는 도구를 평가하며 다듬는 것이다. Anthropic 도구 작성 글글은 실제 사용에 가까운 다단계 평가 과제를 만들고, 정확도와 함께 도구 호출 수, 토큰 사용량, 도구 오류를 모아 개선하라고 권한다.

6단계는 반복되는 실수를 하네스로 되돌려 보내는 것이다. Martin Fowler 사이트 글글은 같은 문제가 여러 번 생기면 가이드와 센서를 고쳐 다시 일어나기 어렵게 만드는 '조종 고리(steering loop)'를 사람의 일로 본다. OpenAI 글글도 실패했을 때 해법은 거의 '더 열심히 해 봐'가 아니었고, "어떤 능력이 빠졌고 어떻게 에이전트가 읽을 수 있고 강제할 수 있게 만들까"를 물었다고 밝혔다.

긴 작업을 위한 하네스

몇 시간에서 며칠 걸리는 작업은 여러 컨텍스트 윈도에 걸쳐야 하고, 새 세션은 이전 기억 없이 시작한다. Anthropic 장기 실행 하네스 글글은 이를 교대 근무하는 엔지니어가 앞 교대의 일을 전혀 기억하지 못하는 상황에 빗댄다. 이 글은 압축 기능이 있어도 부족했다고 밝혔다. 실패는 두 가지 꼴로 나타났다. 한 번에 너무 많이 하려다 구현 도중 컨텍스트가 바닥나 반쯤 된 기능을 남기는 것, 그리고 나중 세션이 진척을 보고 일이 끝났다고 성급히 선언하는 것이다.

해법은 역할이 다른 두 프롬프트다. 첫 세션의 초기화 에이전트(initializer agent)는 개발 서버를 띄우는 init.sh, 작업 기록을 남기는 진행 파일(claude-progress.txt), 첫 git 커밋을 만든다. 또 사용자 요청을 풀어 쓴 기능 목록을 작성하는데, claude.ai 복제 예시에서는 200개가 넘는 기능을 모두 '실패' 상태로 적었다. 이후 에이전트는 통과 여부 필드만 바꾸게 했고, Markdown보다 JSON을 모델이 덜 함부로 고쳐서 JSON을 택했다고 한다글.

이후 세션의 코딩 에이전트는 정해진 순서로 상황을 파악한다. 작업 디렉터리를 확인하고, git 로그와 진행 파일을 읽고, 기능 목록에서 아직 안 된 가장 우선순위 높은 기능 하나를 고른다. init.sh로 서버를 띄워 기본 종단 간(E2E) 테스트를 먼저 돌린 뒤 구현하고, 끝나면 설명이 담긴 커밋 메시지와 진행 요약을 남겨 '깨끗한 상태'로 넘긴다글. git이 있으니 잘못된 변경을 되돌릴 수도 있다.

OpenAI 글글도 같은 방향이다. 복잡한 작업은 진행 상황과 결정 기록이 담긴 실행 계획 파일로 저장소에 남기고, 진행 중·완료된 계획과 기술 부채를 함께 버전 관리해 외부 맥락 없이도 에이전트가 일하게 했다. 이 글은 한 번의 Codex 실행이 6시간 넘게 한 작업을 붙잡는 경우가 흔하다고 밝혔다.

점검 목록

구성 점검: 시스템 프롬프트가 지나친 하드코딩과 막연한 일반론 사이에 있는가글. 도구 수가 최소이고 기능이 겹치지 않으며, 어떤 상황에 어떤 도구를 쓸지 사람이 단정할 수 있는가글글. 도구 응답이 토큰을 아끼면서도 의미 있는 정보를 돌려주는가글. 에이전트 코드가 샌드박스 안에서 돌고, 필요하면 명령 허용 목록과 네트워크 격리가 걸려 있는가글.

컨텍스트 점검: AGENTS.md가 백과사전이 아니라 목차 역할을 하는가, 그리고 낡은 문서를 린터·CI로 잡아내는가글. 컨텍스트가 찰 때 압축이나 파일로 덜어 내는 전략이 있는가글. 서브에이전트에 맡길 독립 작업은 분리된 컨텍스트에서 돌고 있는가글.

검증 점검: 에이전트가 테스트·린터·타입 검사를 스스로 돌리고 결과를 읽을 수 있는가글글. 빠른 검사는 커밋 전에, 비싼 검사는 통합 뒤에 배치했는가글. 웹 기능이라면 브라우저 자동화로 끝까지 확인하는가글. 오류 메시지가 고치는 방법까지 알려 주는가글.

긴 작업 점검: 다음 세션이 읽을 진행 기록·기능 목록·커밋 이력이 남는가, 한 세션에 기능 하나씩만 다루는가, 테스트 없이 완료 표시를 하지 못하게 막았는가글. 마지막으로, 반복된 실수가 하네스 개선으로 이어지는 고리가 있는가글.

흔한 실수와 한계

가장 흔한 실수는 지침과 도구를 너무 많이 넣는 것이다. 거대한 지침 파일은 작업에 필요한 컨텍스트를 밀어내고 금방 낡는다글. 기능이 넓고 경계가 모호한 도구 묶음은 Anthropic 컨텍스트 글글이 꼽는 대표 실패다. 반대로 하네스 프레임워크를 이해 없이 쌓아 올리면 내부에서 무슨 일이 일어나는지 놓치기 쉽다는 경고도 있다글.

두 번째 실수는 검증을 모델의 자기 판단에 맡기는 것이다. Anthropic 장기 실행 하네스 글글에서 Claude는 명시적 지시가 없으면 단위 테스트나 curl 확인만 하고 종단 간으로는 기능이 동작하지 않는다는 것을 놓쳤다. 브라우저 자동화 도구를 주자 크게 나아졌지만, 브라우저 기본 알림창처럼 도구로 보이지 않는 부분은 여전히 버그가 많았다.

하네스에도 한계가 있다. Martin Fowler 사이트 글글은 계산적 센서가 중복 코드, 복잡도, 테스트 커버리지, 구조 이탈 같은 구조적 문제는 안정적으로 잡지만, 문제 오진단, 과잉 설계와 불필요한 기능, 지시 오해 같은 더 큰 문제는 계산적·추론적 장치 모두 감독을 줄일 만큼 안정적으로 잡지 못한다고 지적한다. 결국 하네스는 사람의 검토 부담을 줄일 뿐 없애지는 못한다.

또 하나의 쟁점은 평가 설계다. Anthropic 도구 작성 글글은 지나치게 단순한 평가 환경을 피하고, 서식 차이 같은 사소한 이유로 정답을 거부하는 엄격한 검증기도 피하라고 권한다. 정답에 이르는 길이 여럿일 수 있으니 특정 도구 호출 순서에 과적합하지 말라는 것이다.

더 공부하려면

개념을 먼저 잡으려면 LangChain 글글부터 읽는다. 모델이 못 하는 것에서 거꾸로 출발해 파일시스템, bash, 샌드박스, 메모리, 압축이 왜 필요한지 하나씩 이끌어 낸다. 이어 Anthropic 에이전트 구축 글글로 워크플로와 에이전트의 차이, prompt chaining·routing·orchestrator-workers 같은 기본 패턴을 익히면 좋다.

설계 원칙을 깊게 보려면 Anthropic 컨텍스트 엔지니어링 글글과 도구 작성 글글을 함께 읽는다. 앞의 글은 시스템 프롬프트·도구·예시를 컨텍스트 예산 관점에서 다루고, 뒤의 글은 도구를 시제품으로 만들고 평가로 다듬는 절차를 보여 준다. 연구 근거가 필요하면 SWE-agent논문에서 인터페이스 설계가 성능에 미치는 영향을 확인할 수 있다.

실무 적용은 세 글이 서로 보완한다. Martin Fowler 사이트 글글은 가이드·센서와 계산적·추론적 장치라는 사고 틀을, OpenAI 글글은 저장소 지식 구조와 관찰 가능한 실행 환경 사례를, Anthropic 장기 실행 하네스 글글은 여러 세션에 걸친 작업의 구체적 파일 구성과 세션 시작 절차를 준다.