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