Addy Osmani가 2026년 4월에 정리한 글입니다. 핵심 명제는 단순합니다 — 코딩 에이전트 = 모델 + 그 주변에 당신이 만든 모든 것이고, 그 “주변"을 진지하게 다루는 규율을 하네스 엔지니어링이라 부릅니다.
원문: Agent Harness Engineering — Addy Osmani (2026-04-19)
한 줄
A decent model with a great harness beats a great model with a bad harness.
평범한 모델 + 훌륭한 하네스가, 훌륭한 모델 + 나쁜 하네스를 이깁니다. Claude Code, Cursor, Codex, Aider, Cline이 종종 동일한 모델을 쓰면서 행동이 완전히 갈리는 이유는 모델이 아니라 하네스 차이에 있습니다.
하네스란 정확히 무엇인가
Viv Trivedy의 정의가 가장 간결합니다 — “모델이 아니면, 하네스다(If you’re not the model, you’re the harness).”
구체적으로 하네스에 들어가는 것:
- 시스템 프롬프트,
CLAUDE.md,AGENTS.md, 스킬 파일 - 도구·스킬·MCP 서버와 그 description
- 번들된 인프라 — 파일시스템, 샌드박스, 브라우저
- 오케스트레이션 로직 — 서브에이전트 스폰, 핸드오프, 라우팅
- 훅과 미들웨어 — compaction, continuation, lint 체크
- 관측성 — 로그·트레이스·비용·지연 측정
“Skill Issue” 리프레임 — 모델 문제가 아니라 설정 문제다
대부분의 에이전트 실패는 모델 한계가 아니라 설정 부재에서 온다는 시각.
| 실패 양상 | 진짜 원인 |
|---|---|
| 컨벤션을 모름 | AGENTS.md에 안 써둠 |
| 파괴적 명령 실행 | 예방 훅이 없음 |
| 긴 작업에서 길을 잃음 | planner/executor를 안 분리함 |
| 깨진 코드 머지 | typecheck 백프레셔 미연결 |
증거: Terminal Bench 2.0에서 동일한 Claude Opus 4.6이 Claude Code에서보다 커스텀 하네스에서 훨씬 높은 점수를 냈습니다. Viv의 팀은 모델은 그대로 두고 하네스만 바꿔서 Top 30 → Top 5로 올렸습니다.
“The gap between what today’s models can do and what you see them doing is largely a harness gap.”
The Ratchet — 모든 실수는 룰이 된다
하네스 엔지니어링의 핵심 규율은 래칫(ratchet) 입니다. 한 번 죈 나사는 풀리지 않습니다.
- 실패가 발생한다 → 엔지니어가 해결한다
- 재발을 막을 제약을 추가한다(훅, AGENTS.md 한 줄, 스킬, 도구 게이트)
- 그 제약은 모델이 충분히 강해져 불필요해질 때까지 유지된다
“좋은
AGENTS.md의 모든 줄은 잘못됐던 구체적 사건으로 추적 가능해야 한다.”
따라서 내 코드베이스에 맞는 하네스는 다운로드할 수 없습니다. 당신의 실패 이력이 만든 모양이 바로 그 하네스이기 때문입니다.
Working Backwards from Behaviour — 행동에서 거꾸로 설계하라
“어떤 컴포넌트가 어떤 행동을 위해 존재하는지 이름댈 수 없다면, 그건 거기 있어선 안 된다.”
이 원칙으로 하네스의 주요 부품들을 본다:
파일시스템과 Git — Durable State
가장 기초가 되는 프리미티브. 에이전트가 데이터를 읽고, 중간 작업을 오프로드하고, git으로 진행을 기록·롤백·실험할 수 있게 한다.
Bash와 코드 실행 — 범용 손
ReAct 루프의 가장 일반적인 행동. 대부분의 작업은 결국 CLI 호출로 환원된다.
샌드박스와 디폴트 툴링
allow-list, 네트워크 격리, 온디맨드 환경 구성. 모델이 환경을 설정하지 않는다 — 하네스가 결정한다.
메모리와 검색 — 임시 continual learning
모델은 가중치 또는 컨텍스트로만 지식을 얻는다. AGENTS.md 같은 메모리 파일이 매 세션 주입되고, 웹 검색과 MCP가 학습 cutoff를 메운다. 거칠지만 효과적인 임시 지속 학습이다.
컨텍스트 부패와의 싸움 — 3가지 무기
- Compaction — 윈도우가 차면 오래된 컨텍스트를 지능적으로 ·오프로드
- Tool-call offloading — 고가치 토큰만 컨텍스트에 두고, 큰 출력은 파일시스템으로
- Skills with progressive disclosure — 필요할 때만 지시·도구를 노출
Anthropic은 매우 긴 작업을 위해 풀 컨텍스트 리셋까지 추가했다 — 세션을 tear down하고, compact handoff 파일에서 다시 빌드.
Long-Horizon 실행 — Ralph Loops, Planning, Verification
- Ralph Loop: 종료 시도를 훅이 가로채 원래 프롬프트를 깨끗한 컨텍스트 윈도우에 다시 주입. 매 이터레이션은 새로 시작하지만 파일시스템으로 상태를 읽는다.
- Planning: 모델이 목표를 plan 파일의 단계 시퀀스로 분해.
- Self-verification: 훅이 테스트 스위트를 돌리고 실패를 모델에 다시 흘림.
- Planner / Generator / Evaluator 분리: 같은 에이전트가 자기 작업을 평가하면 점수를 후하게 주므로, 분리하면 성능이 좋아진다.
- Sprint contracts: 코딩 시작 전에 generator와 evaluator가 “완료” 정의를 협상.
Hooks — 시행 계층
라이프사이클 시점(도구 호출 전, 파일 편집 후, 커밋 전, 세션 시작)에 끼어드는 스크립트.
- 매 편집 후 typecheck/lint/test 실행
rm -rf,git push --force,DROP TABLE같은 파괴적 bash 차단- main으로의 PR/push 전 승인 요구
- 쓰기 시 자동 포맷
“Success is silent, failures are verbose.” typecheck 통과는 침묵, 실패는 에러 텍스트가 모델에게 자기교정용으로 주입된다.
AGENTS.md와 도구 선택
시스템 프롬프트에 매 턴 들어가는 가장 레버리지 높은 설정 지점. 두 가지 교훈:
- 짧게 유지하라 — HumanLayer는 60줄 이하로 유지한다. “파일럿 체크리스트지, 스타일 가이드가 아니다.”
- 모든 줄을 벌어와라 — 구체적 실패나 하드 제약으로 거슬러 올라갈 수 있어야 한다.
도구 디시플린: 겹치는 50개보다 집중된 10개. MCP 도구 description은 신뢰된 텍스트로 프롬프트에 들어가므로 보안 이슈도 된다.
하네스는 줄어들지 않는다 — 이동한다
“Every component in a harness encodes an assumption about what the model can’t do on its own.” — Anthropic
모델이 강해지면:
- 그 가정에 해당하는 컴포넌트는 죽는다(예: Opus 4.6이 등장하면서 Sonnet 4.5의 “context anxiety"를 막던 스캐폴딩이 사라짐)
- 새로운 능력이 풀리면 새 스캐폴딩이 등장한다(다중 일 메모리 정책, 다중 에이전트 조정, UI 디자인 평가자)
Model-Harness Training Loop
하네스에서 발견된 패턴 → 제품으로 표준화 → 다음 모델 학습에 사용 → 모델이 그 프리미티브에서 더 잘함 → 반복.
이 피드백 루프 때문에 오늘날 모델은 하네스를 염두에 두고 후속학습된다. 파일시스템 조작, bash, planning, 서브에이전트 디스패치 같은 하네스 설계자가 가치 있게 보는 행동에서 모델이 점점 더 강해진다.
실무적 함의
- 하네스는 정적 설정이 아니라 살아있는 시스템이다.
- “최고의” 하네스는 모델이 학습된 그 하네스가 아니라, 당신의 작업에 맞춰 설계된 하네스다.
Harness-as-a-Service (HaaS)
LLM 완성(completion) API 위에 내가 직접 루프를 짜던 시대 → 하네스 런타임 API 위에서 시스템 프롬프트·도구·컨텍스트·서브에이전트만 커스터마이즈하는 시대.
대표 제품: Claude Agent SDK, Codex SDK, OpenAI Agents SDK. 루프, 도구, 컨텍스트 관리, 훅, 샌드박스 프리미티브가 박스에서 나온다.
“Good agent building is an exercise in iteration. You can’t do iterations if you don’t have a v0.1.” — Viv Trivedy
어디로 가는가
상위권 코딩 에이전트들(Claude Code, Cursor, Codex, Aider, Cline)은 그 밑의 모델보다 서로가 더 닮았다. 하네스 패턴이 수렴하고 있다.
Viv가 꼽는 열린 문제 3가지:
- 같은 코드베이스에서 다수 에이전트를 어떻게 오케스트레이션할 것인가
- 에이전트가 자기 트레이스를 분석해 하네스 실패 모드를 스스로 고치게 만들 수 있는가
- 하네스가 just-in-time으로 도구·컨텍스트를 동적 조립할 수 있는가
“Harnesses stop being static config and start becoming something closer to a compiler.”
정리
- 에이전트 = 모델 + 하네스. 비행기와 항공교통관제처럼, 둘 다 있어야 작동한다.
- 실패는 거의 항상 설정 문제다. 매 실패는 룰이 되어 래칫처럼 되감기지 않는다.
- 컴포넌트는 행동에서 거꾸로 정당화되어야 한다. 이름댈 수 없는 컴포넌트는 빼라.
- 모델이 강해지면 하네스는 줄어드는 게 아니라 이동한다. 죽은 컴포넌트는 지우고, 새 능력에는 새 스캐폴딩을 붙인다.
- 직접 루프를 짜는 시대에서 HaaS 위에서 도메인을 설계하는 시대로 가고 있다.
다음에 에이전트가 실패하면, 모델 탓을 하기 전에 하네스를 봐라.