에이전트 하네스 엔지니어링(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로 끌어올렸다.
하네스와 스캐폴딩을 구분할 때
현업에서는 모델 외부의 모든 것을 넓은 뜻의 하네스라고 부르기도 한다. Hugging Face가 정리한 보다 좁은 구분은 설계 책임을 나눌 때 유용하다.
| 용어 | 좁은 의미 | 예시 |
|---|---|---|
| 스캐폴딩(scaffolding) | 모델이 어떤 정보와 형식으로 행동할지 규정하는 계층 | 시스템 프롬프트, 도구 설명, 출력 파서, 컨텍스트 정책 |
| 하네스(harness) | 모델을 반복 호출하고 도구 요청을 실행하며 종료를 결정하는 실행 계층 | 에이전트 루프, 오류 처리, 승인 게이트 |
| 오케스트레이터(orchestrator) | 여러 하네스를 가진 에이전트를 작업 단위로 조율하는 상위 계층 | 리드 에이전트와 서브에이전트 배치 |
이 구분은 보편 표준이 아니다. Claude Code와 Codex 같은 제품 문맥에서는 프롬프트와 도구를 포함한 전체 실행계를 하네스라고 부를 수 있다. 다만 실패 원인이 지침 설계인지 실행 루프인지, 또는 멀티 에이전트 조율인지 분리해 진단할 때는 세 용어를 구분하는 편이 정확하다.
하네스의 구성 요소
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 자율 코딩 에이전트를 운영 환경에 안정적으로 배포해야 할 때
하네스 엔지니어링 연구 현황
LangChain은 deepagents 라이브러리를 통해 하네스 엔지니어링 도구를 제공하며, 다음 문제를 연구하고 있다.
- 수백 개의 에이전트가 공유 코드베이스에서 병렬 작업하는 오케스트레이션
- 에이전트가 자신의 실행 트레이스를 분석해 하네스 수준 실패 모드를 스스로 식별·수정
- 고정 설정 대신 태스크에 맞는 툴과 컨텍스트를 적시에 동적으로 조합하는 하네스
AHE: 관찰 가능성 기반 자동 하네스 진화 (arXiv 2604.25850)
복단대·마이크로소프트 연구팀이 제안한 에이전트 하네스 엔지니어링(Agentic Harness Engineering, AHE) 프레임워크는 하네스 엔지니어링을 수동 작업이 아닌 자동화된 폐루프로 전환한다 (2026-04-28).
핵심 문제: 하네스를 자동으로 개선하려면 세 가지 장벽을 넘어야 한다. ① 편집 가능한 컴포넌트의 이질적인 액션 스페이스, ② 유용한 신호가 묻히는 수백만 토큰의 실행 트레이스, ③ 편집 효과를 귀인하기 어려운 특성.
3가지 관찰 가능성 기둥:
| 기둥 | 설명 |
|---|---|
| 컴포넌트 관찰 가능성 | 편집 가능한 모든 하네스 컴포넌트에 파일 레벨 표현을 부여 → 액션 스페이스를 명시적·가역적으로 |
| 경험 관찰 가능성 | 수백만 토큰의 로우 트레이스를 계층적 증거 코퍼스로 요약 → 진화 에이전트가 실제로 소비 가능 |
| 결정 관찰 가능성 | 모든 편집에 자기 선언 예측을 페어링하고, 다음 라운드 태스크 수준 결과로 검증 |
세 기둥이 함께 작동하면 모든 편집이 반증 가능한 계약(falsifiable contract)이 되어 시행착오 없이 하네스가 자율 진화할 수 있다.
실험 결과:
- Terminal-Bench 2에서 10회 AHE 반복으로 pass@1 69.7% → 77.0% 향상 (인간 설계 Codex-CLI 71.9% 초과)
- SWE-bench-verified에서 시드 대비 12% 적은 토큰으로 최고 성공률 달성
- 다른 모델 패밀리 3종 적용 시 +5.1~+10.1pp 크로스 패밀리 성능 향상 (하네스가 벤치마크 특화 아닌 일반 엔지니어링 경험을 인코딩함을 시사)
- 성능 향상은 시스템 프롬프트가 아닌 툴·미들웨어·장기 메모리에서 발생
참고 자료
- Jiahang Lin et al., “Agentic Harness Engineering: Observability-Driven Automatic Evolution of Coding-Agent Harnesses” — arXiv 2604.25850 (2026-04-28)
- Viv Trivedy, “The Anatomy of an Agent Harness” — LangChain Blog (2026-03-10)
- Viv Trivedy, “Anatomy of an Agent Harness”
- HumanLayer, “Skill Issue: Harness Engineering for Coding Agents”
- Addy Osmani, “Agent Harness Engineering”
- Addy Osmani, “Agent Harness Engineering” — O’Reilly Radar 재게재본 (2026-05-15)
- Anthropic Engineering, “Harness Design for Long-Running Apps”
- walkinglabs, “Learn Harness Engineering” — OpenAI·Anthropic 공식 연구를 기반으로 한 하네스 엔지니어링 프로젝트 기반 강좌 (GitHub)
- Harness, Scaffold, and the AI Agent Terms Worth Getting Right — Hugging Face (2026-05-25)
관련 문서
- symphony — 하네스 엔지니어링의 다음 단계: 이슈 트래커를 에이전트 오케스트레이터로 변환하는 OpenAI 스펙
- claude-code — 하네스 엔지니어링의 대표적인 상용 구현체
- agent-governance — 에이전트 거버넌스와 하네스 보안 정책
- agent-skills — AGENTS.md에 담기는 에이전트 스킬 설계
- kimi — 하네스 엔지니어링에 최적화된 코딩 모델
- generic-agent — 3K 라인 시드 코드에서 스킬 트리를 자율 성장시키는 자기진화 에이전트
- browser-harness — LLM이 헬퍼 함수를 직접 작성해 브라우저 하네스를 자기치유하는 최소 구현체
- long-running-agents — 수시간~수주 장기 실행 에이전트 설계 원칙과 Ralph 루프·Brain/Hands/Session 패턴
- ai-agent-evaluation — 긴 작업과 도구 사용을 검증하는 에이전트 평가 하네스 설계
- codex-tips-goal-command —
/goal을 완료 조건과 검증 명령이 있는 작업 계약으로 쓰는 방법 - context-engineering — 컨텍스트 창을 유한 자원으로 관리하는 방법론
- halo — RLM으로 에이전트 트레이스를 분석해 하네스를 자동 최적화하는 루프
- flue — Astro 팀이 만든 TypeScript 에이전트 하네스 프레임워크 (Markdown 우선, 런타임 불가지론)
- lobehub — 에이전트를 업무 단위로 구성하는 협업형 AI 워크스페이스
- fusion — 작업 보드와 git worktree로 에이전트 실행을 조율하는 멀티 노드 오케스트레이터
- zerostack — Rust 기반 초경량 코딩 에이전트와 worktree/loop 하네스
- agentic-ai-tips-prompt-engineering — 챗봇 프롬프트와 다른 에이전트 프롬프트 설계법
- agent-friendly-websites — AI 에이전트가 읽고 조작하기 쉬운 웹 UX 설계
- pro-workflow — 교정에서 학습하는 Claude Code 자기교정 워크플로 스택
- multi-stream-llms — 단일 스트림 챗 모델 병목을 모델 아키텍처 차원에서 줄이는 병렬 스트림 연구
- ai-q-skill — 에이전트 하네스가 딥리서치 작업을 전문 백엔드에 위임하는 NVIDIA 스킬
- clawless — WebContainers 기반 브라우저 AI 에이전트 런타임
- skillopt — 모델을 고정한 채 스킬 문서를 검증 기반으로 개선하는 텍스트 공간 최적화기