Agent Harness Engineering: 모델보다 그 주변이 더 결정적이라는 Addy Osmani의 정리
목차
개요
Addy Osmani가 Agent Harness Engineering 글에서 정리한 핵심 명제는 한 줄이다. “코딩 에이전트는 모델 + 그 주변에 만든 모든 것이다.” 같은 Claude Opus 4.6 모델이 기본 환경에서는 Terminal Bench 2.0 같은 벤치마크에서 평범한 결과를 내지만, 잘 설계된 하네스 안에서는 30위권에서 5위권으로 도약한다. 이 격차의 대부분은 모델이 아니라 그 모델을 둘러싸는 시스템에서 나온다. Geek News 토론에서도 “AI Agent = Model + Harness”라는 공식이 핵심 키워드로 인용된다.
하네스란 무엇인가
핵심 등식
Osmani가 사용한 등식은 다음과 같다.
1
Coding agent = AI model(s) + harness
그리고 그가 강조하는 한 줄은 더 직관적이다. “괜찮은 모델 + 훌륭한 하네스가 훌륭한 모델 + 나쁜 하네스를 이긴다.” 모델 자체가 아니라 모델을 감싸는 비계 구조가 실제 성능을 결정한다는 주장이다.
하네스의 구성 요소
하네스는 다음의 모든 것을 포함한다.
| 분류 | 구성 요소 |
|---|---|
| 지시 계층 | 시스템 프롬프트, AGENTS.md, 스킬 파일 |
| 능력 계층 | 도구, 스킬, MCP 서버와 그 설명 |
| 실행 계층 | 파일시스템, 샌드박스, 브라우저 |
| 오케스트레이션 | 서브에이전트 스폰, 모델 라우팅 |
| 미들웨어 | 컴팩션, 컨티뉴에이션 체크 같은 결정적 실행 보조 |
| 관측 계층 | 로깅, 트레이싱, 비용 미터링 |
이 모든 층이 합쳐진 결과물이 “에이전트”이며, 이 중 어느 하나라도 흔들리면 모델 능력이 그대로 발휘되지 못한다.
핵심 아키텍처 컴포넌트
파일시스템 Git Bash 샌드박스
Osmani는 파일시스템을 “오래 가는 상태(durable state)”의 토대로 본다. 중간 작업물을 컨텍스트 윈도우 대신 디스크에 떠넘기는 것이 컨텍스트 부담을 줄이는 가장 단순한 길이다. Git 계층을 함께 두면 버전 관리와 롤백이 자연스럽게 따라온다.
도구 측면에서는 모든 가능한 도구를 사전에 만들어 두는 대신, 샌드박스 안에서 범용 bash 접근을 허용한다. 미리 정의되지 않은 문제도 그 자리에서 명령을 조합해 풀 수 있다. 사전 설치된 런타임, 패키지 매니저, 브라우저, 테스트 러너가 들어 있는 격리 환경은 위험을 차단하면서도 에이전트가 자율적으로 코드를 만들고 검증할 여지를 남긴다.
컨텍스트 관리 기법
| 기법 | 설명 |
|---|---|
| Compaction | 컨텍스트 윈도우 고갈 직전에 지능적 요약으로 토큰 회수 |
| Tool-call offloading | 큰 출력은 파일시스템으로 옮기고 필요할 때만 다시 읽기 |
| Skills + progressive disclosure | 도구를 필요한 시점에만 노출해 초기 컨텍스트 보존 |
| Context resets | 장기 작업은 핸드오프 파일을 거쳐 새로운 컨텍스트로 재시작 |
이 네 기법은 모두 “에이전트의 머리에 무엇이 들어 있는가”를 통제하기 위한 장치다. 모델 능력이 같아도 컨텍스트가 흐트러지면 결과는 무너진다.
장기 실행과 Hook 강제 계층
장기간 실행은 별도의 패턴이 필요하다.
| 패턴 | 동작 |
|---|---|
| Ralph Loop | 완료 시도를 훅이 가로채 원래 프롬프트를 새 컨텍스트로 재주입 |
| Planning | 모델이 목표를 단계로 분해해 디스크에 저장 |
| Planner / generator / evaluator 분리 | 생성과 평가를 다른 에이전트에 분리해 자기 채점의 낙관 편향 회피 |
| Sprint contracts | 실행 전에 “성공 기준”을 정의해 스코프 드리프트 방지 |
훅은 강제 계층이다. 편집 후 타입체크를 강제하거나, rm -rf 같은 파괴적 명령을 차단하거나, 승인 게이트를 요구하는 식이다. Osmani가 인용한 원칙은 강력하다. “성공은 조용하고 실패는 시끄럽게.” 에러가 발생하면 그 메시지가 곧바로 추론 루프 안으로 다시 주입되어 다음 행동을 교정한다.
“Skill Issue” 리프레임
이 글의 가장 도발적인 주장은 마인드셋 전환이다. 모델 한계를 탓하기 전에, 동일 모델이 다른 하네스에서 전혀 다른 결과를 낸다는 사실을 떠올려야 한다. HumanLayer가 정리한 표현이 이를 압축한다. “모델 문제가 아니라 설정 문제다.”
이 관점에서 모든 실수는 영구 신호가 된다. 한 번 발생한 에러는 새 규칙, 새 훅, 새 도구 추가로 박제된다. Osmani는 다음과 같이 말한다. “좋은 AGENTS.md의 모든 줄은 과거에 잘못된 특정 사건으로 거슬러 올라갈 수 있어야 한다.” 이른바 ratchet 원칙이다. 한 번 굳어진 교훈은 다시 풀리지 않고 그대로 시스템 안으로 통합된다.
모델-하네스 공동 학습과 HaaS
Osmani는 또 한 가지 중요한 관찰을 덧붙인다. 최신 모델들은 하네스를 “옆에 두고” 사후 학습된다. Claude Opus 4.6이 파일시스템 조작, bash 사용, 계획 수립을 일반 모델과 다르게 다루는 이유는 학습 과정에서 이런 하네스 프리미티브가 함께 들어갔기 때문이다.
이 관찰의 실용적 함의는 분명하다. 당신의 코드베이스에 최적인 하네스는 모델이 학습한 그 하네스와 다를 수 있다. 실제 작업과 실패 이력이 당신만의 설정을 결정해야 한다.
산업 흐름은 LLM API에서 Harness API로 이동 중이다.
| 카테고리 | 제공 내용 |
|---|---|
| LLM API | 단순 completion |
| Harness API | 루프, 도구 디스패치, 컨텍스트 관리, 샌드박스 프리미티브 |
Claude Agent SDK, Codex SDK, OpenAI Agents SDK가 모두 후자에 해당한다. 직접 만들 인프라 부담을 줄여 주는 대신, 이 SDK들이 제공하는 패턴이 곧 업계 표준이 된다. Osmani가 짚은 또 다른 관찰은 시각적이다. “리딩 코딩 에이전트들은 그 안의 모델보다 서로 더 닮아 있다.” Claude Code, Cursor, Codex, Aider, Cline이 비슷한 모양으로 수렴하는 현상은 부담 분산 패턴이 산업 차원에서 합의되고 있다는 신호다.
구성 베스트 프랙티스
Osmani가 추천하는 실무 가이드라인은 의외로 보수적이다.
| 항목 | 가이드 |
|---|---|
| AGENTS.md 길이 | 약 60줄 이내, 파일럿 체크리스트 밀도 |
| 규칙의 출처 | 각 규칙은 과거 실패나 외부 제약으로 추적 가능 |
| 도구 개수 | 약 10개로 제한해 주의 분산 방지 |
| 도구 설명 | 프롬프트로 들어가므로 신뢰 안 되는 MCP는 인젝션 리스크 |
| 컴포넌트 설계 | 행동 단위로 정의 (“이 컴포넌트가 전달하려는 행동을 못 말하면 그건 거기 있을 이유가 없다”) |
도구 풀이 커질수록 모델의 주의력이 분산된다는 관찰은 단순하지만 자주 무시된다. 하네스는 “더 많이 넣을수록 좋아진다”가 아니라 “행동에 직결되지 않는 것은 빼는 쪽이 좋다”는 방향으로 운영된다.
향후 과제로 Osmani가 짚은 세 가지는 다음과 같다.
| 영역 | 미해결 과제 |
|---|---|
| 병렬 에이전트 | 같은 코드베이스에서 다수 에이전트를 동시에 오케스트레이션하는 방식 |
| 자기 진단 | 트레이스를 분석해 하네스 수준의 실패를 스스로 식별하고 교정 |
| 동적 어셈블리 | 정적 사전 설정이 아닌, JIT 컴파일에 가까운 도구·컨텍스트 동적 결합 |
마지막 항목에서 Osmani는 하네스를 점차 “컴파일러에 가까운 무언가”로 비유한다. 정적 설정에서 동적 어셈블리로 가는 흐름이다.
Geek News 토론에서는 비판적 시선도 함께 등장했다. 한 댓글은 “마케팅 용어처럼 들린다”고 말하고, 다른 댓글은 “실제 코딩 작업엔 별 도움이 안 된다”고 회의한다. 명확한 지시가 있어도 결과가 확률적이라는 점에 대한 의문도 거론된다. 한편 Osmani가 개념을 말하지만 실제 구글 제품에 적용했는지에 대한 지적도 나온다. 긍정 진영은 모델-하네스 호환성이 두 요소만큼 중요하다는 점, 그리고 서로 다른 모델들이 비슷한 하네스로 수렴하는 흐름을 강조한다.
결론
Agent Harness Engineering은 모델 능력 자체보다 그것을 둘러싸는 시스템의 설계 원칙을 본다. 같은 Opus 4.6이 기본 환경에서 30위였다가 잘 설계된 하네스에서 5위가 되는 격차, AGENTS.md 한 줄이 과거 실패 한 건과 직결되어야 한다는 ratchet 원칙, 도구 10개·60줄 가이드라인 같은 보수적 운영 원칙이 이 분야를 떠받친다. LLM API에서 Harness API로의 이동, 코딩 에이전트들이 모델보다 서로 더 닮아 가는 수렴 현상, 그리고 정적 설정에서 동적 컴파일로 향하는 미래상은 모두 같은 방향을 가리킨다. 모델 격차보다 하네스 격차가 더 크다.