에이전트 하네스 엔지니어링(Agent Harness Engineering)은 AI 에이전트를 구성하는 모델 외부의 모든 요소—프롬프트, 툴, 컨텍스트 정책, 훅, 샌드박스, 피드백 루프—를 체계적으로 설계하고 개선하는 방법론이다. Viv Trivedy가 제안한 개념으로, “좋은 하네스를 갖춘 평범한 모델이 나쁜 하네스의 뛰어난 모델을 이긴다”는 원칙에서 출발한다.
핵심 원칙
“Agent = Model + Harness. 모델이 아니라면, 당신은 하네스다.” — Viv Trivedy
코딩 에이전트(Claude Code, Cursor, Codex, Cline)는 동일한 모델을 쓰더라도 하네스 설계에 따라 결과가 크게 달라진다. Terminal Bench 2.0에서 같은 Claude Opus 4.6이 Claude Code 내에서보다 커스텀 하네스에서 훨씬 높은 점수를 기록한 사례가 이를 증명한다. 한 팀은 하네스만 바꿔 순위를 Top 30→Top 5로 끌어올렸다.
하네스의 구성 요소
1. 파일시스템 + Git
- 에이전트가 컨텍스트 창을 넘는 작업을 처리하게 해주는 가장 기본적인 기반
- 중간 결과 오프로드, 멀티 에이전트 협업, 버전 관리(롤백·브랜치)에 활용
2. Bash / 코드 실행
- ReAct 루프(추론→툴 호출→관찰→반복)의 일반 목적 엔진
- 미리 툴을 다 만들 필요 없이, 에이전트가 필요한 툴을 셸에서 즉시 생성
3. 샌드박스
에이전트가 생성한 코드를 안전하게 실행하는 격리 환경.
- 명령어 허용 목록, 네트워크 격리, 온디맨드 프로비저닝
- 기본 탑재 도구: 언어 런타임, Git, 테스트 CLI, 헤드리스 브라우저
4. 메모리 + 검색
AGENTS.md/CLAUDE.md등 파일에 세션 간 유지할 지식 저장- 훈련 데이터 이후 정보는 웹 검색·MCP 툴(Context7 등)로 보완
5. 컨텍스트 로트(Context Rot) 대응
컨텍스트 창이 채워질수록 추론 품질이 저하되는 현상을 막는 기법들:
| 기법 | 설명 |
|---|---|
| 컴팩션(Compaction) | 오래된 컨텍스트를 지능적으로 요약해 오프로드 |
| 툴 결과 오프로딩 | 대용량 로그는 파일로 저장, 필요 시 불러오기 |
| 스킬(Skills) | 지시사항·툴을 필요할 때만 점진적으로 공개 |
| 컨텍스트 초기화 | 장기 작업에선 세션을 새로 시작하고 요약 핸드오프 파일로 연속성 유지 |
6. 장기 실행: Ralph 루프 + 플래닝
- Ralph 루프: 훅이 에이전트의 종료 시도를 인터셉트해 원래 프롬프트를 새 컨텍스트 창에 재주입 → 멀티 세션 에이전트 구현
- 플래닝: 목표를 단계로 분해해 디스크의 플랜 파일에 저장, 각 단계마다 자가 검증
- 플래너/생성자/평가자 분리: 자기 평가 편향을 막기 위해 생성과 평가를 별도 에이전트로 분리
7. 훅(Hooks): 강제 실행 레이어
성공은 침묵, 실패는 상세히. 타입 체크 통과 시 에이전트는 아무것도 안 듣는다. 실패 시 에러 텍스트가 루프에 주입된다.
훅이 담당하는 대표 작업:
- 모든 편집 후 타입 체크·린트·테스트 실행
- 파괴적 명령(
rm -rf,git push --force,DROP TABLE) 차단 - PR 생성·
main푸시 전 승인 요구 - 저장 시 자동 포매팅
8. AGENTS.md / CLAUDE.md
하네스의 단일 최대 레버리지 지점. 시스템 프롬프트에 매 턴마다 주입된다.
- 짧게 유지: HumanLayer는 60줄 이하 권장. 규칙이 많을수록 각 규칙의 효과 감소
- 실패 기반으로 작성: 모든 줄은 실제 발생한 오류로 정당화되어야 함
래칫(Ratchet) 원칙
에이전트가 실수를 할 때마다 그 실수를 영구 신호로 취급하고 하네스에 반영하라.
- 주석 처리된 테스트 머지 →
AGENTS.md에 “테스트는 주석 처리 금지” 추가 + 훅에서.skip(탐지 - 파괴적 명령 실행 → 훅에서 해당 명령 차단
- 좋은
AGENTS.md의 모든 줄은 구체적 과거 실패로 추적 가능해야 한다
하네스는 축소되지 않고 이동한다
모델이 개선될수록 일부 스캐폴딩은 불필요해지지만, 동시에 새로운 실패 모드가 등장해 새 스캐폴딩이 필요해진다. 하네스는 “모델이 아직 못 하는 것”에 대한 가정의 집합이다. 모델이 향상되면 해당 컴포넌트를 제거하고, 새로운 한계에 맞는 컴포넌트를 추가한다.
사용 대상 및 케이스
- AI 코딩 에이전트 구축자: Claude Code·Cursor 같은 도구를 직접 만들거나 자사 코드베이스에 맞게 커스터마이징하는 팀
- ML 엔지니어: 에이전트 성능 벤치마크를 높이고 싶을 때 모델 교체보다 하네스 개선을 우선 고려
- DevOps/플랫폼 팀: 24/7 자율 코딩 에이전트를 운영 환경에 안정적으로 배포해야 할 때
참고 자료
- Viv Trivedy, “Anatomy of an Agent Harness”
- HumanLayer, “Skill Issue: Harness Engineering for Coding Agents”
- Addy Osmani, “Agent Harness Engineering”
- Anthropic Engineering, “Harness Design for Long-Running Apps”
관련 문서
- claude-code — 하네스 엔지니어링의 대표적인 상용 구현체
- agent-governance — 에이전트 거버넌스와 하네스 보안 정책
- agent-skills — AGENTS.md에 담기는 에이전트 스킬 설계
- kimi — 하네스 엔지니어링에 최적화된 코딩 모델