하네스 엔지니어링 - AI 에이전트 성능을 좌우하는 시스템 설계의 모든 것
목차
개요
AI 에이전트의 성능은 모델 자체의 능력만으로 결정되지 않는다. 동일한 모델이라도 어떤 시스템 환경에서 실행되느냐에 따라 성능이 극적으로 달라질 수 있다. 이 글에서는 AI 에이전트 시대의 핵심 경쟁력으로 부상한 하네스 엔지니어링(Harness Engineering)의 개념, 구성 요소, 실전 원칙, 그리고 미래 전망을 종합적으로 다룬다. WikiDocs의 jaehong747이 정리한 하네스 엔지니어링 종합 아티클과 Anthropic의 Justin Young이 발표한 장기 실행 에이전트 하네스 연구를 기반으로, 하네스가 왜 중요한지, 어떻게 설계해야 하는지를 상세히 살펴본다.
배경
하네스 개념 정의
하네스(Harness)라는 용어는 본래 말에게 씌우는 마구를 의미한다. AI 에이전트 맥락에서 하네스란, LLM 모델을 감싸고 있는 시스템 계층 전체를 가리킨다. 프롬프트, 도구 호출, 파일 시스템 접근, 실행 환경, 컨텍스트 관리, 서브 에이전트 조율 등 모델 외부의 모든 인프라가 하네스에 해당한다. 이 개념을 처음으로 명명한 사람은 Mitchell Hashimoto로, 그는 에이전트의 성능이 모델 자체보다 모델을 둘러싼 시스템 설계에 더 크게 좌우된다는 점을 강조했다.
Agent = Model + Harness
LangChain의 Vivek Trivedy는 에이전트의 본질을 간결한 공식으로 정리했다. Agent = Model + Harness라는 공식이다. 이 공식에서 Model은 LLM의 추론 능력을 뜻하고, Harness는 그 추론을 실제 작업으로 전환하는 데 필요한 모든 시스템 구성 요소를 뜻한다. 이 공식이 단순한 이론이 아니라는 것을 LangChain 스스로가 증명했다. LangChain 팀은 Terminal Bench 2.0 벤치마크에서 모델을 전혀 바꾸지 않고 하네스만 개선하여 30위에서 5위로 뛰어올랐다. 점수로 보면 52.8에서 66.5로 약 26% 향상된 수치다. 같은 모델이라도 하네스가 달라지면 결과가 이토록 극적으로 바뀔 수 있다는 점을 보여준 사례다.
핵심 내용
하네스의 5대 핵심 구성 요소
하네스를 구성하는 핵심 요소는 크게 다섯 가지로 나눌 수 있다. 각 요소는 독립적이면서도 서로 유기적으로 연결되어 에이전트의 전체 성능을 결정한다.
1. 파일시스템과 지속적 저장소
AI 에이전트가 장기 작업을 수행할 때 가장 큰 문제 중 하나는 컨텍스트 윈도우의 한계다. 컨텍스트 윈도우가 리셋되면 이전에 수행한 작업의 맥락이 사라진다. 이를 해결하기 위해 하네스는 파일시스템 기반의 지속적 저장소를 제공한다. 대표적인 예가 claude-progress.txt와 같은 진행 상황 파일이다. 에이전트는 작업 중간중간 자신의 진행 상황을 이 파일에 기록하고, 새로운 세션이 시작될 때 이 파일을 읽어 이전 맥락을 복원한다. 이는 마치 교대 근무하는 엔지니어들이 인수인계 노트를 작성하는 것과 같은 원리다. 파일시스템은 단순한 텍스트 저장을 넘어, Git 저장소와 결합하여 작업 이력 추적과 버전 관리까지 가능하게 한다.
2. 코드 실행과 샌드박스
에이전트가 실제로 유용한 작업을 수행하려면 코드를 실행할 수 있어야 한다. 하네스는 tool call, bash 명령 실행, 샌드박스 환경 등을 통해 에이전트에게 코드 실행 능력을 부여한다. 여기서 핵심은 샌드박스 처리다. 에이전트가 임의의 코드를 안전하게 실행할 수 있도록 격리된 환경을 제공해야 한다. 샌드박스 없이 에이전트에게 코드 실행 권한을 주면 시스템 전체에 위험을 초래할 수 있다. 잘 설계된 하네스는 에이전트가 필요한 도구에 접근하면서도 시스템의 안전성을 유지하는 균형을 달성한다.
3. 컨텍스트 관리와 컨텍스트 부패 방지
컨텍스트 관리는 하네스 엔지니어링에서 가장 정교한 영역이다. LLM의 컨텍스트 윈도우는 유한하므로, 긴 작업에서는 필연적으로 컨텍스트를 관리해야 한다. 하네스는 이를 위해 여러 기법을 사용한다. 첫째, 컴팩션(Compaction)은 이전 대화를 요약하여 핵심 정보만 남기는 기법이다. 둘째, 도구 호출 오프로딩(Tool Call Offloading)은 도구의 출력을 컨텍스트에서 분리하여 별도로 관리하는 방식이다. 셋째, 스킬과 점진적 공개(Skills/Progressive Disclosure)는 에이전트가 필요한 시점에만 관련 정보를 컨텍스트에 로드하는 전략이다. 여기서 컨텍스트 부패(Context Corruption)라는 개념이 중요하다. 컨텍스트에 잘못된 정보나 불필요한 정보가 누적되면 에이전트의 판단력이 저하된다. HumanLayer 팀은 이에 대한 교훈을 남겼다. “성공은 조용히, 실패만 시끄럽게”라는 원칙이다. 성공적인 도구 호출의 상세 출력은 컨텍스트에서 축약하고, 실패한 호출의 에러 메시지는 상세히 유지하는 것이다. 이렇게 하면 에이전트가 같은 실수를 반복하지 않으면서도 컨텍스트 공간을 절약할 수 있다.
4. 서브 에이전트와 컨텍스트 격리
복잡한 작업은 단일 에이전트로 처리하기 어렵다. 하네스는 서브 에이전트를 생성하여 작업을 분할할 수 있게 해준다. 여기서 핵심 원칙은 컨텍스트 방화벽(Context Firewall)이다. 서브 에이전트는 역할 기반 분할(role-based splitting)이 아니라 컨텍스트 격리(context isolation)를 기준으로 설계해야 한다. 즉, “프론트엔드 에이전트”와 “백엔드 에이전트”로 나누는 것이 아니라, 각 에이전트가 자신의 작업에 필요한 컨텍스트만 가지도록 격리하는 것이다. 이 접근법의 핵심 격언은 “더 긴 컨텍스트가 아니라, 더 나은 컨텍스트 격리”이다. 컨텍스트 윈도우를 무작정 늘리는 것보다, 각 에이전트가 정확히 필요한 정보만 가지고 작업하도록 설계하는 것이 더 효과적이다.
5. 훅과 백프레셔 메커니즘
하네스의 마지막 핵심 요소는 라이프사이클 훅(Lifecycle Hooks)과 자기 검증(Self-Verification) 메커니즘이다. 라이프사이클 훅은 에이전트의 작업 흐름에 특정 시점마다 개입할 수 있는 지점을 제공한다. 예를 들어 코드 생성 후 자동으로 린트를 실행하거나, 커밋 전에 테스트를 수행하는 것이 훅의 활용 사례다. 백프레셔 메커니즘은 에이전트가 너무 빠르게 진행하여 품질이 저하되는 것을 방지한다. 자기 검증은 에이전트가 작업 완료를 선언하기 전에 스스로 결과를 확인하도록 강제하는 메커니즘이다. 이러한 메커니즘이 없으면 에이전트는 작업을 성급하게 완료 처리하고 넘어가는 경향이 있다.
Anthropic의 장기 실행 에이전트 하네스 연구
Anthropic의 Justin Young은 2025년 11월에 장기 실행 에이전트를 위한 효과적인 하네스 설계에 대한 연구를 발표했다. 이 연구는 AI 에이전트가 여러 컨텍스트 윈도우에 걸친 장기 작업에서 겪는 근본적인 문제를 다루고 있다.
핵심 문제: 교대 근무 엔지니어의 딜레마
AI 에이전트가 장기 작업을 수행할 때의 문제는 마치 교대 근무하는 엔지니어들이 아무런 기억 공유 없이 일하는 것과 같다. 각 컨텍스트 윈도우가 새로 시작될 때마다 에이전트는 이전 작업의 맥락을 잃어버린다. 이전 세션에서 발견한 버그, 시도했던 접근법, 중간 결과물 등이 모두 사라진다. 이 문제를 해결하지 않으면 에이전트는 같은 실수를 반복하거나, 이미 완료된 작업을 다시 수행하게 된다.
2단계 에이전트 아키텍처
Anthropic은 이 문제를 해결하기 위해 2단계 에이전트 아키텍처를 제안했다.
첫 번째 단계는 초기화 에이전트(Initializer Agent)다. 초기화 에이전트는 프로젝트의 기반을 마련하는 역할을 한다. init.sh 스크립트를 생성하여 환경 설정을 자동화한다. claude-progress.txt 파일을 만들어 작업 진행 상황을 기록할 수 있는 구조를 마련한다. 초기 Git 커밋을 생성하여 작업의 시작점을 명확히 한다.
두 번째 단계는 코딩 에이전트(Coding Agent)다. 코딩 에이전트는 실제 개발 작업을 수행한다. 세션이 시작되면 먼저 진행 상황 파일과 Git 로그를 읽어 현재 상태를 파악한다. 한 번에 하나의 기능(feature)만 작업한다. 작업이 완료되면 의미 있는 커밋 메시지와 함께 커밋하고, 진행 상황 파일을 업데이트한다.
Feature List 접근법
Anthropic의 연구에서 가장 주목할 만한 전략은 Feature List 접근법이다. 이것은 200개 이상의 기능을 JSON 파일로 관리하는 방식이다. 각 기능은 “failing” 상태로 시작하여 에이전트가 구현하고 검증한 후에야 “passing”으로 표시된다. 이 접근법은 에이전트의 가장 흔한 실패 모드인 조기 완료 선언(premature completion)을 방지한다. 에이전트는 Feature List의 모든 항목이 완료되기 전까지 작업이 끝났다고 판단할 수 없다.
실패 모드와 해결 전략
Anthropic의 연구는 장기 실행 에이전트의 주요 실패 모드와 각각에 대한 해결 전략을 체계적으로 정리했다.
| 문제 | 초기화 에이전트의 대응 | 코딩 에이전트의 대응 |
|---|---|---|
| 조기 완료 선언 | Feature List JSON 파일 생성 | Feature List를 읽고 단일 기능씩 작업 |
| 문서화되지 않은 버그성 진행 | Git 저장소와 진행 노트 구성 | 검증 테스트로 시작 |
| 불완전한 기능 표시 | Feature List JSON 생성 | 완료 표시 전 자기 검증 수행 |
| 환경 설정 혼란 | init.sh 생성 | init.sh 읽기로 시작 |
세션 프로토콜
코딩 에이전트가 새 세션을 시작할 때 따르는 프로토콜이 있다. 먼저 pwd 명령으로 현재 작업 디렉토리를 확인한다. 그다음 Git 로그와 진행 상황 파일을 읽어 이전 세션의 상태를 파악한다. 마지막으로 가장 우선순위가 높은 미완료 기능을 선택하여 작업을 시작한다. 이 프로토콜은 단순하지만 매우 효과적이다. 에이전트가 매 세션마다 일관된 절차를 따르도록 강제함으로써 혼란과 중복 작업을 방지한다.
테스팅과 브라우저 자동화
Anthropic의 연구에서는 테스팅에 Puppeteer MCP를 활용한 브라우저 자동화를 적용했다. 에이전트가 인간처럼 브라우저를 조작하여 테스트를 수행하면, 단순 코드 리뷰로는 발견하기 어려운 버그를 더 많이 찾아낼 수 있었다. UI 렌더링 문제, 상호작용 버그, 시각적 결함 등을 브라우저 기반 테스트로 효과적으로 탐지할 수 있었다. 다만 한계점도 존재한다. Claude는 Puppeteer를 통해 브라우저 네이티브 alert 모달을 감지할 수 없다는 제한이 있다. 이는 브라우저 자동화 도구 자체의 한계로, 하네스 설계 시 이러한 도구의 제약사항도 함께 고려해야 함을 보여준다.
모델과 하네스의 공진화 역설
하네스 엔지니어링에서 주목해야 할 흥미로운 현상이 있다. 모델과 하네스가 함께 진화하면서 발생하는 공진화 역설(Co-evolution Paradox)이다.
현재 주요 AI 모델들은 자사의 하네스 환경 내에서 훈련되고 있다. Claude는 Claude Code 하네스 내에서, Codex는 Codex 하네스 내에서 훈련된다. 이는 모델이 특정 하네스에 최적화되는 결과를 낳는다.
이 현상의 구체적 사례가 있다. Opus 4.6 모델은 Claude Code 하네스에서 33위를 기록했지만, 다른 하네스에서는 5위를 기록했다. 이는 모델이 특정 하네스에 과적합(overfitting)될 수 있다는 위험을 보여준다. 자사 하네스에서의 성능이 범용 하네스에서의 성능을 보장하지 않는다는 뜻이다.
이 역설은 실무에 중요한 시사점을 준다. 자신의 작업 환경에 맞게 하네스를 커스터마이징하면 의미 있는 성능 향상을 얻을 수 있다. 범용 하네스보다 특정 도메인이나 워크플로우에 맞춘 하네스가 더 효과적일 수 있다. 다만 과도한 커스터마이징은 다른 모델이나 환경으로의 이식성을 떨어뜨릴 수 있으므로 균형이 필요하다.
하네스 엔지니어링 실전 원칙
하네스를 설계할 때 따라야 할 실전 원칙들이 있다. 이 원칙들은 실제 사례와 연구를 기반으로 정립된 것이다.
실패에서 시작하라
Mitchell Hashimoto가 제시한 핵심 원칙이다. 하네스를 설계할 때는 에이전트가 실패하는 지점을 먼저 파악하고, 그 실패를 방지하는 방향으로 하네스를 구축해야 한다. 성공 시나리오가 아닌 실패 시나리오에서 출발하는 것이 효과적인 하네스 설계의 시작점이다. 에이전트가 어디서, 왜, 어떻게 실패하는지를 분석하면 자연스럽게 필요한 하네스 구성 요소가 도출된다.
적게 넣어라
ETH Zurich의 연구는 흥미로운 결과를 보여주었다. LLM이 자동 생성한 설정(config)을 하네스에 추가하면 오히려 성능이 저하되었다. 비용은 20% 이상 증가했지만 성능은 개선되지 않았다. 이는 컨텍스트에 더 많은 정보를 넣는 것이 항상 좋은 것은 아니라는 점을 보여준다. 하네스는 최소한의 필수 정보만 제공하도록 설계해야 한다. 불필요한 정보는 에이전트의 주의를 분산시키고 컨텍스트 공간을 낭비한다.
도구를 과하게 연결하지 마라
MCP(Model Context Protocol) 서버를 통해 에이전트에 다양한 도구를 연결할 수 있다. 하지만 너무 많은 도구를 연결하면 에이전트의 성능이 오히려 저하된다. 에이전트가 수십 개의 도구 중에서 적절한 것을 선택해야 하면, 도구 선택 자체에 추론 비용이 소모된다. 실제로 MCP 서버 과부하(overload)는 에이전트 성능 저하의 주요 원인 중 하나다. 작업에 꼭 필요한 도구만 선별하여 제공하는 것이 핵심이다.
점진적 작업을 강제하라
에이전트에게 한 번에 거대한 작업을 맡기는 것은 위험하다. 하네스는 에이전트가 점진적으로 작업하도록 강제해야 한다. Anthropic의 Feature List 접근법이 이 원칙의 좋은 예다. 200개 이상의 기능을 한 번에 구현하라고 하는 것이 아니라, 한 번에 하나의 기능만 작업하고, 완료 후 다음으로 넘어가도록 구조화하는 것이다. 점진적 작업은 오류 누적을 방지하고, 중간 결과물의 품질을 보장한다.
미래 전망
하네스 엔지니어링의 미래에 대해 Thoughtworks의 Birgitta Boeckeler는 중요한 질문을 던졌다. 하네스가 서비스 템플릿(Service Template)로 진화할 것인가에 대한 질문이다.
현재 하네스는 각 팀이나 프로젝트에 맞게 개별적으로 설계되고 있다. 하지만 하네스 설계의 패턴이 축적되면서, 표준화된 하네스 템플릿이 등장할 가능성이 있다. 마치 웹 프레임워크가 웹 개발의 공통 패턴을 표준화한 것처럼, 하네스 프레임워크가 에이전트 운영의 공통 패턴을 표준화할 수 있다. 이미 LangChain, Claude Code, Codex 등에서 하네스 패턴의 표준화가 진행되고 있다. 앞으로는 “어떤 모델을 쓸 것인가”보다 “어떤 하네스를 구성할 것인가”가 AI 에이전트 활용의 핵심 질문이 될 것으로 전망된다.
의미와 시사점
하네스 엔지니어링의 부상은 AI 에이전트 생태계에 여러 가지 중요한 시사점을 제공한다.
첫째, 모델 성능만으로는 충분하지 않다는 점이 명확해졌다. LangChain이 모델 변경 없이 하네스 개선만으로 벤치마크 순위를 30위에서 5위로 끌어올린 사례는 이를 강력하게 입증한다. 모델 연구 못지않게 하네스 연구에 투자해야 하는 시대가 왔다.
둘째, 소프트웨어 엔지니어의 역할이 재정의되고 있다. AI 에이전트 시대의 소프트웨어 엔지니어는 코드를 직접 작성하는 것뿐만 아니라, 에이전트가 효과적으로 작업할 수 있는 환경을 설계하는 역할도 수행해야 한다. 하네스 엔지니어링은 시스템 설계, 인프라 구축, 워크플로우 최적화 등 전통적인 소프트웨어 엔지니어링 역량과 밀접하게 연결된다.
셋째, 에이전트의 장기 작업 능력이 하네스 품질에 의해 결정된다. Anthropic의 연구가 보여주듯, 에이전트가 여러 세션에 걸쳐 일관성 있게 작업하려면 진행 상황 관리, 컨텍스트 보존, 자기 검증 등의 하네스 메커니즘이 필수적이다.
넷째, 과적합의 위험을 인지해야 한다. Opus 4.6의 사례에서 보듯, 모델이 특정 하네스에 과적합되면 다른 환경에서의 성능이 오히려 저하될 수 있다. 범용성과 특수화 사이의 균형을 찾는 것이 중요하다.
다섯째, “적게 넣어라”는 원칙이 직관에 반하지만 중요하다. 더 많은 컨텍스트, 더 많은 도구, 더 많은 설정이 항상 좋은 결과를 가져오지는 않는다. ETH Zurich의 연구 결과가 보여주듯, 불필요한 정보는 오히려 성능을 저하시킨다. 하네스 설계의 핵심은 필요한 것만 정확히 제공하는 미니멀리즘에 있다.
결론
AI 에이전트 시대의 경쟁력은 모델이 아니라 하네스에서 나온다. Agent = Model + Harness라는 공식이 보여주듯, 아무리 뛰어난 모델이라도 적절한 하네스 없이는 진정한 능력을 발휘할 수 없다. 파일시스템과 지속적 저장소, 코드 실행과 샌드박스, 컨텍스트 관리, 서브 에이전트와 컨텍스트 격리, 훅과 백프레셔 메커니즘이라는 다섯 가지 핵심 요소를 이해하고 적절히 설계하는 것이 하네스 엔지니어링의 본질이다. Anthropic의 연구가 보여주듯, 장기 실행 에이전트를 위한 하네스는 초기화 에이전트와 코딩 에이전트의 2단계 구조, Feature List 기반 작업 관리, 체계적인 세션 프로토콜을 통해 에이전트의 장기 작업 능력을 극적으로 향상시킬 수 있다. 실패에서 시작하고, 적게 넣고, 점진적 작업을 강제하는 실전 원칙을 따르면서, 자신의 도메인에 맞는 하네스를 설계하는 것이 AI 에이전트를 효과적으로 활용하는 핵심 전략이 될 것이다.