Harness Engineering - 모델을 바꾸지 않고 코딩 에이전트 성능을 52%에서 66%로 올렸다

LangChain이 Terminal Bench 2.0에서 재밌는 실험을 했다.

코딩 에이전트의 벤치마크 점수를 52.8%에서 66.5%로 끌어올렸다. 순위로 치면 Top 30에서 Top 5로 점프. 모델은 바꾸지 않았다. 프롬프트도 아니다.

바꾼 건 에이전트의 하네스(harness)다.

같은 모델. 다른 하네스. 극적으로 다른 결과

 

하네스가 뭔데

말의 마구(馬具)를 생각하면 된다. 고삐, 안장, 재갈. 강력하지만 방향을 모르는 동물을 원하는 곳으로 이끄는 장비 전체다.

AI 에이전트에서 하네스도 같은 개념이다.

Agent = Model + Harness

모델은 지능이다. 하네스는 그 지능을 쓸모있게 만드는 시스템 전체다.

구체적으로는 이런 것들이 포함된다.

• AGENTS.md, CLAUDE.md 같은 지시 파일
• 에이전트가 사용할 수 있는 도구(MCP 서버, 린터, 테스트 러너)
• 스킬과 서브 에이전트
• 훅과 피드백 루프
• 권한 관리와 안전장치

Harness Engineering은 이런 하네스를 설계하고 최적화하는 분야다.

 

어디서 나왔나

이 용어가 자리잡은 건 2025~2026년이다. 여러 곳에서 거의 동시에 비슷한 문제를 풀고 있었다.

HumanLayer의 Dex Horthy가 12-factor agents에서 context engineering이라는 개념을 제시했고, Viv가 하네스의 네 가지 커스터마이징 레버(시스템 프롬프트, 도구/MCP, 컨텍스트, 서브 에이전트)를 정리했다. Harness engineering은 이 context engineering의 하위 분야로, 코딩 에이전트의 설정 포인트를 체계적으로 관리하는 것에 집중한다.

그리고 2026년 2월, OpenAI가 Codex 팀의 사례를 공개하면서 이 개념이 업계에 본격적으로 퍼졌다.

 

OpenAI Codex 팀의 실험

OpenAI Codex 팀이 100만 줄 이상의 프로덕션 코드를 만들었다. 사람이 직접 작성한 코드는 0줄이다.

엔지니어들의 일은 코드를 쓰는 게 아니라, 에이전트가 코드를 잘 쓸 수 있는 환경을 설계하는 것이었다.

이 과정에서 발견한 핵심 원칙이 몇 가지 있다.

 

에이전트 관점에서 컨텍스트에 없으면 존재하지 않는다

이건 좀 생각해볼 만한 지점이다.

Google Docs에 있는 아키텍처 결정, Slack에서 나눈 기술 토론, 누군가의 머릿속에 있는 컨벤션. 에이전트는 이런 걸 모른다. 컨텍스트 윈도우에 없으면 없는 것이다.

그래서 Codex 팀은 모든 지식을 레포지토리 안으로 밀어넣었다. 구조화된 docs/ 디렉토리에 아키텍처 결정, 네이밍 컨벤션, 배포 프로세스를 전부 버전 관리했다.

AGENTS.md를 백과사전으로 만들면 안 된다. 컨텍스트가 비대해지면 에이전트가 핵심 제약을 놓치거나 엉뚱한 것에 최적화한다. 지시가 너무 많으면 지시가 없는 것과 같다. AGENTS.md는 목차 역할만 하고, 실제 지식은 구조화된 문서 디렉토리에 분산시킨다.

 

AI 슬롭(slop) 문제

AI가 생성한 코드는 기존 레포지토리의 패턴을 복제한다. 좋은 패턴이든, 나쁜 패턴이든. 시간이 지나면 드리프트가 쌓인다. 네이밍이 불일치하고, 데드 코드가 쌓이고, 문서가 현실과 어긋난다.

Codex 팀은 초기에 매주 금요일(전체 시간의 20%)을 AI 슬롭 정리에 썼다. 당연히 스케일이 안 됐다.

해결책은 "golden principles"를 레포지토리에 인코딩하고, 주기적인 정리 에이전트를 돌리는 것이었다. 에이전트가 크론으로 코드베이스를 스캔하고, 위반 사항을 찾아서 리팩토링 PR을 올린다. 대부분 1분 안에 자동 머지된다.

이전 글에서 다룬 Compound Engineering의 축적 단계(Compound phase)와 비슷하다. 차이점이 있다면, Compound Engineering은 학습을 문서로 축적하는 데 초점이 있고, Harness Engineering은 그 문서를 에이전트가 실제로 올바르게 소비하도록 환경을 설계하는 데 초점이 있다.

 

가이드와 센서

ThoughtWorks의 Birgitta Böckeler가 Martin Fowler 블로그에서 하네스를 두 가지 축으로 정리했다. 사이버네틱스에서 빌려온 개념이다.

 

가이드(Guides) = 피드포워드 제어. 에이전트가 작업을 시작하기 전에 올바른 방향으로 이끄는 것.

• CLAUDE.md, AGENTS.md 같은 지시 문서
• 타입 시스템과 스키마 정의
• 아키텍처 제약 (예: 이 레이어에서 저 레이어를 import하면 안 된다)
• 코드 템플릿과 패턴 예시

센서(Sensors) = 피드백 제어. 에이전트의 결과물이 기준을 충족하는지 확인하는 것.

• 린터, 타입 체커
• 유닛 테스트, 통합 테스트
• AI 코드 리뷰 에이전트
• 런타임 모니터링 (SLO 감시 등)

가이드와 센서 각각에 "계산적(computational)" 방식과 "추론적(inferential)" 방식이 있다.

린터는 계산적 센서다. 빠르고, 저렴하고, 결정적이다. 매 변경마다 돌려도 된다. AI 코드 리뷰는 추론적 센서다. 느리고, 비싸고, 비결정적이다. 하지만 "이 코드가 의도에 맞는가?" 같은 의미론적 판단이 가능하다.

프론트엔드 개발 관점에서 보면, TypeScript의 strict 모드는 강력한 계산적 가이드다. FSD의 레이어 의존성 규칙을 ESLint 플러그인으로 강제하면 계산적 센서가 된다. 이런 것들이 이미 하네스의 일부인 셈이다.

 

Anthropic의 장기 실행 에이전트 하네스

Anthropic도 하네스 설계에 대한 연구를 공개했다. 복잡한 작업에서 에이전트가 여러 컨텍스트 윈도우에 걸쳐 일관되게 작업하는 게 어렵다는 문제를 다뤘다.

해결 방식은 세 에이전트 구조다.

• Planner: 짧은 프롬프트를 전체 제품 스펙으로 확장한다. 의도적으로 구현 세부사항은 남겨둔다. 초기에 과잉 명세하면 하위 에러가 연쇄한다.
• Generator: 스프린트 단위로 기능을 구현한다. 코드를 쓰기 전에 Evaluator와 "스프린트 계약"을 맺는다. 완료의 정의를 합의하는 것이다.
• Evaluator: Playwright로 실제 사용자처럼 앱을 테스트한다. UI, API, 데이터베이스를 검증한다. 하나라도 실패하면 스프린트 실패

솔로 에이전트 vs 세 에이전트 하네스를 비교한 결과가 있다. 2D 레트로 게임 엔진을 만드는 과제였다.

	솔로 에이전트	세 에이전트 하네스
소요 시간	20분	6시간
비용	$9	$200
결과	실행은 되지만 핵심 기능 깨짐	완전히 작동하는 게임

비용이 20배. 하지만 결과물이 "사용 불가"에서 "사용 가능"으로 바뀌었다. 이게 하네스 엔지니어링이 만드는 트레이드오프다.

 

프롬프트 엔지니어링 → 컨텍스트 엔지니어링 → 하네스 엔지니어링

이 세 개념의 관계를 정리하면 이렇다.

프롬프트 엔지니어링: 모델에 뭘 말할지 최적화한다. 단일 턴의 품질을 높이는 데 초점

컨텍스트 엔지니어링: 모델이 볼 수 있는 전체 정보를 관리한다. 프롬프트만이 아니라, 도구 결과, 파일 내용, 이전 대화 등. 프롬프트 엔지니어링의 상위 개념

하네스 엔지니어링: 에이전트의 실행 환경 전체를 설계한다. 컨텍스트뿐 아니라, 도구, 권한, 피드백 루프, 생명주기 관리까지. 가장 넓은 범위

결국 레이어가 쌓이면서 단일 프롬프트의 품질에서 전체 시스템의 신뢰성으로 관심이 이동하는 것이다.

 

모델이 좋아지면 하네스는 불필요해질까

직관적으로는 그럴 것 같다. 모델이 충분히 똑똑하면 가드레일이 필요 없지 않을까

현실은 반대다. LangChain의 말을 빌리면, 모델이 좋아지면 하네스에서 최적화할 수 있는 영역이 사라지는 게 아니라 이동한다. 이전에 불가능했던 복잡한 작업을 시도할 수 있게 되면서, 새로운 실패 모드가 나타나고, 새로운 하네스가 필요해진다.

프롬프트 엔지니어링도 마찬가지 아닌가. GPT-4가 나오면 프롬프트 엔지니어링이 사라질 줄 알았는데, 오히려 더 정교한 프롬프트가 필요해졌다.

 

세 글을 관통하는 흐름

Ralph Loop → Compound Engineering → Harness Engineering.

 

Ralph Loop는 에이전트를 루프에 넣어 반복 실행하는 가장 단순한 패턴이다. 컨텍스트 리셋으로 rot을 방지하고, 한 번에 하나씩 처리한다.

Compound Engineering은 그 루프에서 나온 학습을 축적하는 방법론이다. 문서화된 컨벤션, 패턴, 실수 교훈이 쌓이면서 에이전트의 출발점이 매번 높아진다.

Harness Engineering은 에이전트가 그 학습을 효과적으로 소비하고, 안전하게 실행할 수 있는 환경을 설계하는 분야다. 가이드로 방향을 잡고, 센서로 결과를 검증한다.

 

셋 다 같은 방향을 가리키고 있다. 코드를 직접 쓰는 시대에서, 코드를 쓰는 시스템을 설계하는 시대로의 전환이다.

호불호가 갈릴 수 있다. "결국 프롬프트 잘 쓰는 거 아니냐"라고 할 수 있다. 맞는 면도 있다. 하지만 프롬프트 한 줄과, 린터·테스트·문서·스킬·서브에이전트·피드백 루프가 조립된 하네스 전체는 다른 차원의 이야기다.

개인적으로는 이 변화가 FSD 같은 아키텍처 패턴과 맞닿아 있다고 느낀다. 레이어별로 역할을 분리하고, 의존성 규칙을 강제하는 것 자체가 일종의 가이드이자 센서 역할을 한다. 사람을 위한 것이었던 아키텍처 규칙이 이제 에이전트를 위한 가드레일이 되는 것이다.

 

 

참고

• Martin Fowler / Birgitta Böckeler: https://martinfowler.com/articles/harness-engineering.html
• OpenAI Codex 팀 사례: https://openai.com/index/harness-engineering/
• Anthropic 장기 실행 에이전트: https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents
• LangChain 하네스 해부: https://blog.langchain.com/the-anatomy-of-an-agent-harness/
• HumanLayer 블로그: https://www.humanlayer.dev/blog/skill-issue-harness-engineering-for-coding-agents