에이전트 하니스 엔지니어링 (Agent Harness Engineering)

코딩 에이전트는 모델과 그 주변에 구축된 모든 것을 합친 것입니다. 하네스 엔지니어링은 그 스캐폴딩을 살아있는 아티팩트로 취급하며, 에이전트가 실수를 할 때마다 이를 개선합니다.

간단히 말해: 에이전트가 실패할 때마다 영구적인 해결책을 엔지니어링하여 동일한 실수를 다시는 하지 않도록 만드는 것입니다.

지난 2년 동안 업계는 모델에 대해 논쟁해 왔습니다. 어떤 모델이 가장 똑똑한지, 어떤 모델이 가장 깔끔한 React 코드를 작성하는지, 또는 어떤 모델이 환각(hallucination)을 가장 적게 일으키는지에 대한 논쟁이었습니다. 그 논의가 중요하기는 하지만, 시스템의 나머지 절반을 놓치고 있습니다.

모델은 실행 중인 에이전트에 대한 하나의 입력에 불과합니다. 나머지는 하네스(harness)입니다. 즉, 모델이 실제로 작업을 완료할 수 있도록 모델을 감싸고 있는 프롬프트, 도구, 컨텍스트 정책, 훅, 샌드박스, 서브 에이전트, 피드백 루프, 복구 경로입니다.

훌륭한 하네스를 갖춘 평범한 모델은 형편없는 하네스를 가진 훌륭한 모델보다 지속적으로 더 나은 성능을 보입니다. 점점 더 흥미로운 엔지니어링 작업은 모델을 선택하는 것이 아니라, 그 주변의 스캐폴딩을 설계하는 데 있습니다.

이제 그 분야에는 이름이 생겼습니다. @Vtrivedy10이 하네스 엔지니어링(harness engineering)이라는 용어를 만들어냈고, 하네스가 실제로 무엇이며 각 요소가 왜 존재하는지에 대한 명확한 분석을 제공했습니다. @dexhorthy와 같은 업계 전문가들은 새로운 패턴을 추적하고 있고, HumanLayer는 에이전트 실패를 구성 "스킬 이슈(skill issue)"로 규정하고 있으며, Anthropic의 엔지니어링 팀은 장기 실행 앱 설계에 대한 가이드를 발행하고, Birgitta Böckeler는 사용자 측 경험을 탐구하고 있습니다. 이 모든 것은 대략 동일한 아이디어로 수렴되고 있습니다.

이 글은 이러한 여러 흐름을 하나로 엮습니다.

하네스란 정말 무엇인가?

Trivedy의 핵심 정의가 대부분의 무거운 설명을 담당합니다:

에이전트 = 모델 + 하네스. 당신이 모델이 아니라면, 당신은 하네스입니다.

하네스는 모델 자체가 아닌 모든 코드, 구성, 실행 로직을 포괄합니다. 원시 모델은 에이전트가 아닙니다. 하네스가 상태(state), 도구 실행, 피드백 루프, 그리고 강제 가능한 제약 조건을 제공할 때 비로소 에이전트가 됩니다.

구체적으로, 하네스는 다음을 포함합니다:

• 시스템 프롬프트, CLAUDE.md, AGENTS.md, 스킬 파일, 서브 에이전트 지침.
• 도구, 스킬, MCP 서버 및 이에 대한 기술적 설명.
• 번들된 인프라(파일 시스템, 샌드박스, 헤드리스 브라우저 등).
• 서브 에이전트 생성, 핸드오프 처리, 모델 라우팅을 위한 오케스트레이션 로직.
• 린트 검사나 컨텍스트 압축과 같은 결정론적 실행을 위한 훅 및 미들웨어.
• 로그, 트레이스, 비용, 지연 시간 측정을 위한 관찰 가능성 도구.

핵심적으로, 에이전트는 목표를 달성하기 위해 루프에서 도구를 실행하는 시스템입니다. 진정한 기술은 도구와 그 루프를 모두 설계하는 데 있습니다.

이는 방대한 표면 영역을 나타내지만, 모델 제공자의 영역이 아닌 여러분의 영역입니다. Claude Code, Cursor, Codex, Aider, Cline은 모두 하네스입니다. 기본 모델은 플랫폼 간에 동일할 수 있지만, 사용자가 경험하는 동작은 하네스에 의해 결정됩니다.

"스킬 이슈"를 다시 생각해 봅시다

에이전트가 무언가 터무니없는 행동을 했을 때 모델을 탓하고, "다음 버전을 기다리자"며 문제를 덮어두는 엔지니어들을 흔히 볼 수 있습니다.

하네스 엔지니어링 사고방식은 이러한 기본 반응을 거부합니다. 실패는 대개 어느 정도 해독 가능합니다. 에이전트가 규칙을 무시했다면 AGENTS.md에 추가하세요. 파괴적인 명령을 실행했다면 이를 차단하는 훅을 작성하세요. 40단계짜리 작업에서 길을 잃었다면 아키텍처를 플래너와 실행기로 분할하세요. 깨진 코드로 일관되게 마무리한다면 루프에 타입 검사 백프레셔 신호를 연결하세요.

HumanLayer가 말했듯이: "모델 문제가 아닙니다. 구성(configuration) 문제입니다." 성능 벤치마크를 생각해 보세요. 기성 프레임워크 내에서 실행되는 최고 수준의 모델은 종종 맞춤형으로 고도로 튜닝된 하네스에서 실행되는 동일한 모델보다 훨씬 낮은 점수를 기록합니다. 더 나은 코드베이스 도구, 더 정교한 프롬프트, 더 날카로운 백프레셔를 갖춘 환경으로 모델을 옮기면 원래 설정이 남겨둔 기능을 활용할 수 있습니다.

오늘날 모델이 이론적으로 할 수 있는 것과 실제로 수행하는 모습 사이의 격차는 대부분 하네스 격차입니다.

래칫(Ratchet): 모든 실수가 규칙이 된다

하네스 엔지니어링에서 가장 중요한 습관은 에이전트의 실수를 일회성 우연으로 취급하여 재시도하고 잊어버리는 것이 아니라, 영구적인 신호로 처리하는 것입니다.

에이전트가 주석 처리된 테스트가 포함된 PR을 실수로 병합하여 출시했다면, 그것은 입력입니다. AGENTS.md의 다음 버전에는 "절대 테스트를 주석 처리하지 말고, 삭제하거나 수정하라"고 명시해야 합니다. 다음 pre-commit 훅은 diff에서 .skip(을 자동으로 플래그 지정해야 합니다. 리뷰어 서브 에이전트는 주석 처리된 테스트를 차단하도록 업데이트되어야 합니다.

제약 조건은 실제 실패를 관찰했을 때만 추가되어야 하며, 유능한 모델이 이를 불필요하게 만들 때만 제거되어야 합니다. 좋은 시스템 프롬프트의 모든 줄은 구체적이고 역사적인 실패로 거슬러 올라갈 수 있어야 합니다.

이 때문에 하네스 엔지니어링은 만능 프레임워크가 아닌 하나의 학문 분야입니다. 특정 코드베이스에 적합한 하네스는 전적으로 고유한 실패 이력에 의해 형성됩니다.

동작으로부터 거꾸로 작업하기

하네스를 설계하는 가장 효과적인 방법은 원하는 동작에서 시작하여 이를 제공하는 구성 요소를 구축하는 것입니다: 우리가 원하는 동작 → 이를 달성하기 위한 하네스 설계.

하네스의 모든 부분은 뚜렷한 역할을 가져야 합니다. 구성 요소가 제공하는 특정 동작의 이름을 댈 수 없다면 제거해야 합니다.

파일 시스템 및 Git - 지속적인 상태

파일 시스템은 기본입니다. 모델은 컨텍스트 창에 맞는 것만 조작할 수 있습니다. 파일 시스템은 데이터를 읽을 작업 공간, 중간 작업을 오프로드할 장소, 여러 에이전트가 조정할 수 있는 표면을 제공합니다.

Git을 추가하면 무료 버전 관리가 제공되어 에이전트가 진행 상황을 추적하고, 실험을 브랜치로 나누고, 오류를 롤백할 수 있습니다.

Bash 및 코드 실행: 범용 도구

대부분의 에이전트는 ReAct 루프에서 작동합니다: 추론, 도구 호출을 통한 행동, 관찰, 반복. 가능한 모든 작업에 대해 미리 도구를 구축하는 대신, 에이전트에게 bash 액세스 권한을 부여하면 필요에 따라 즉석에서 도구를 구축할 수 있습니다.

에이전트는 일반적으로 셸 명령에 능숙하므로, bash와 코드 실행은 자율적인 문제 해결을 위한 기본 전략이 됩니다.

샌드박스 및 기본 도구

Bash는 안전하게 실행될 때만 유용합니다. 샌드박스는 에이전트에게 코드를 실행하고, 파일을 검사하고, 호스트 머신을 위험에 빠뜨리지 않고 작업을 확인할 수 있는 격리된 환경을 제공합니다.

좋은 샌드박스는 강력한 기본값과 함께 제공됩니다: 사전 설치된 언어 런타임, 테스트 CLI, 헤드리스 브라우저를 통해 에이전트가 자신의 작업을 관찰하고 자체 검증 루프를 닫을 수 있습니다.

메모리 및 검색: 지속적인 학습

모델은 훈련 가중치와 현재 컨텍스트 이상의 지식을 가지고 있지 않습니다. 하네스는 AGENTS.md와 같은 메모리 파일을 사용하여 이 격차를 메우며, 모든 세션에 지식을 주입합니다.

새로운 라이브러리 버전이나 실시간 데이터와 같은 실시간 정보의 경우, 웹 검색 및 MCP 도구가 하네스에 직접 통합됩니다.

컨텍스트 부패와의 싸움

모델은 컨텍스트 창이 가득 차면 추론 능력이 저하됩니다. 하네스는 세 가지 주요 기술을 사용하여 이러한 희소성을 관리합니다:

• 압축(Compaction): 이전 컨텍스트를 지능적으로 요약하고 오프로드하여 API 오류를 방지합니다.
• 도구 호출 오프로드: 방대한 도구 출력(예: 2,000줄 로그)을 파일 시스템에 저장하고, 필수 헤더와 푸터만 컨텍스트에 유지합니다.
• 점진적 공개(Progressive disclosure): 작업이 명시적으로 요구할 때만 지침과 도구를 공개하고, 시작 시 모든 것을 로드하지 않습니다.

장기 실행(Long-Horizon Execution)

자율적이고 장기간 실행되는 작업은 조기 중단과 빈약한 문제 분해로 어려움을 겪습니다. 하네스는 구조적 설계를 통해 이에 대응합니다:

• 루프: 모델의 종료 시도를 가로채고, 새로운 컨텍스트 창에서 완료 목표를 향해 계속하도록 강제합니다.
• 계획: 모델이 목표를 단계별 계획 파일로 분해하도록 강제하고, 각 단계 후 자체 검증 훅을 통해 작업을 확인합니다.
• 분할: 생성과 평가를 별도의 에이전트로 분리하여, 모델이 자신의 작업을 평가할 때 가지는 본질적인 긍정 편향을 방지합니다.

훅은 당신의 강제 계층(Enforcement Layer)입니다

훅은 작업을 요청하는 것과 강제하는 것 사이의 격차를 메웁니다. 훅은 특정 생명 주기에서 실행됩니다: 도구 호출 전, 파일 편집 후, 또는 커밋 전. 훅은 파괴적인 명령을 차단하고, 토큰을 절약하기 위해 자동 서식 지정을 강제하며, 테스트 스위트를 실행합니다.

이상적으로, 성공은 조용하고 실패는 장황해야 합니다. 타입 검사가 통과하면 에이전트는 아무 소리도 듣지 못합니다. 실패하면 오류가 자체 수정을 위해 루프에 직접 다시 주입됩니다.

규칙과 도구 선택

저장소 루트에 있는 평범한 마크다운 파일은 여전히 가장 영향력 있는 구성 지점입니다. 그러나 조종사 체크리스트처럼 취급되어야 하며, 스타일 가이드처럼 취급되어서는 안 됩니다. 짧게 유지하고, 모든 규칙이 과거 실패를 통해 얻어졌는지 확인하세요.

동일한 규율이 도구에도 적용됩니다. 잘 정의된 10개의 도구는 항상 겹치는 50개의 도구보다 성능이 뛰어납니다.

또한, 도구 설명이 프롬프트를 채우기 때문에, 악의적이거나 부주의한 외부 통합(예: 확인되지 않은 MCP 서버)은 에이전트가 작업을 시작하기도 전에 나쁜 프롬프트를 주입할 수 있습니다.

프로덕션에서의 실제 모습

제가 본 성숙한 하네스의 가장 명확한 공개 사례는 Fareed Khan의 Claude Code 아키텍처에 대한 (추정) 분석입니다.

이전 섹션의 거의 모든 개념이 이 다이어그램에서 명명된 구성 요소로 나타납니다. 컨텍스트 주입은 지식 계층입니다. 루프 상태는 메모리 저장소와 작업 트리 격리자에 있습니다. 파괴적 작업 훅은 권한 게이트 뒤에 있습니다. 서브 에이전트 컨텍스트 방화벽은 전체 멀티 에이전트 계층입니다. 도구 디스패치 레지스트리는 MCP 서버와 bash가 모두 연결되는 곳입니다. Claude Code의 궤적은 그 아래에 있는 모델만큼이나 하네스에 관한 것입니다.

하네스는 줄어들지 않고, 이동한다

모델이 개선됨에 따라 하네스의 필요성은 사라지지 않고, 이동합니다.

더 나은 모델이 스캐폴딩을 쓸모없게 만든다고 가정하기 쉽습니다. 예를 들어, 최근 모델 업그레이드는 "컨텍스트 불안" 완화의 필요성을 극적으로 줄였습니다. 그러나 바닥이 올라가면 천장도 올라갑니다. 이전에는 도달할 수 없었던 작업이 이제 가능해지면서 완전히 새로운 실패 모드가 발생합니다.

하네스의 모든 구성 요소는 모델이 스스로 할 수 없는 것에 대한 가정을 인코딩합니다. 모델이 개선되면, 구식 스캐폴딩은 제거되어야 하고, 다음 지평선에 도달하기 위해 새로운 스캐폴딩을 구축해야 합니다.

훈련 루프는 어떻습니까?

하네스 설계와 모델 훈련 사이에는 활발한 피드백 루프가 있습니다.

오늘날의 모델은 종종 특정 하네스가 루프에 포함된 상태에서 사후 훈련되어 어느 정도의 과적합(overfitting)을 만듭니다. 모델은 하네스 설계자가 우선시한 특정 작업(예: 파일 시스템 작업, bash, 서브 에이전트 디스패치)에 대해 매우 능숙해집니다.

이는 하네스를 정적 구성 파일이 아닌 살아있는 시스템으로 만들며, "최고의" 하네스는 특정 작업과 워크플로우에 맞게 특별히 최적화된 것임을 증명합니다.

서비스형 하네스 (HaaS)

업계는 LLM API(완성체를 제공) 위에 구축하는 것에서 하네스 API(런타임을 제공) 위에 구축하는 것으로 전환하고 있습니다. SDK는 이제 루프, 도구, 컨텍스트 관리, 훅, 샌드박스를 즉시 제공합니다.

처음부터 오케스트레이션을 구축하는 대신, 현대적인 기본값은 하네스 프레임워크를 선택하고, 핵심 기둥을 구성한 다음, 순수하게 도메인별 프롬프트 및 도구 설계에 집중하는 것입니다.

이것이 문제 해결을 확장 가능하게 만드는 이유입니다: 전체 에이전트 아키텍처를 재발명하는 대신, 잘 분해된 구성 표면을 튜닝하는 것입니다.

이것이 나아가는 방향

오늘날 최고의 코딩 에이전트들을 보면, 그들은 기본 모델보다 서로를 더 많이 닮아 있습니다. 모델은 다르지만, 하네스 패턴은 수렴하고 있습니다. 업계는 생성 텍스트를 출시 가능한 소프트웨어로 전환하는 데 필요한 핵심 스캐폴딩을 빠르게 식별하고 있습니다.

가장 흥미로운 미해결 문제들은 단일 에이전트를 넘어서고 있습니다: 여러 에이전트를 병렬로 오케스트레이션하고, 에이전트가 자신의 트레이스를 분석하여 하네스 수준의 실패를 수정할 수 있게 하며, 도구를 적시에 동적으로 조립하는 환경을 구축하는 것입니다.

궁극적으로, 이것은 하네스가 정적 구성 파일이 아니라 컴파일러처럼 작동하기 시작하는 단계입니다.

훌륭한 에이전트 하네스 프레임워크를 찾고 있다면, @FredKSchott가 Flue를 작성했습니다. 견고하며, 이 글의 이전 버전에서 영감을 받았다고 합니다!