하네스 엔지니어링: AI 에이전트 제어의 핵심 구조

AI 코딩 에이전트를 쓰다 보면 한 번쯤 이런 경험을 하게 된다. 분명히 프롬프트에 "이렇게 하지 말라"고 써놨는데, 다음 세션에서 또 똑같은 실수를 저지른다. 다시 설명하고, 또 실수하고, 또 설명하는 루프가 반복된다. 하네스 엔지니어링은 바로 이 반복을 구조적으로 끊어내는 기법이다. AI 에이전트가 실수할 때마다 그 실수가 다시 일어날 수 없도록 시스템 자체를 개선하는 것, 그게 핵심이다.

 

AI 에이전트는 왜 같은 실수를 반복할까

AI 에이전트의 반복 실수는 크게 두 가지 다른 문제에서 온다. 하나는 기억의 문제, 다른 하나는 규칙의 문제다.

 

첫 번째는 컨텍스트 부패(Context Decay)다. AI에게는 한 번에 볼 수 있는 정보의 양, 즉 컨텍스트 창이 있다. 작업이 길어질수록 이 창이 꽉 차면서 처음에 주었던 지침을 밀어내기 시작한다. 30분짜리 회의를 하다 보면 초반에 정한 원칙을 잊는 것과 비슷하다. 에이전트가 초기에 "절대 이렇게 하지 마"라는 규칙을 받았더라도, 대화가 길어지면 그 규칙은 컨텍스트 창 바깥으로 밀려난다.

 

Anthropic 연구팀이 Claude Opus에게 Claude.ai를 클론하도록 실험했을 때, 두 가지 실패 패턴이 반복됐다. 하나는 컨텍스트가 바닥나 절반만 구현하고 멈추는 것, 다른 하나는 아직 작업이 한참 남았는데 스스로 "다 됐다"고 조기 종료 선언을 해버리는 것이었다. 이 두 번째 현상은 컨텍스트 불안(Context Anxiety)이라고 따로 불린다. 컨텍스트 창 한계에 가까워지면 에이전트가 불안해져서 작업을 조기에 마무리하려는 경향이다. 컨텍스트 부패와는 다른 별개의 문제다.

 

두 번째는 규칙과 울타리의 부재다. 이건 기억의 문제가 아니다. AI가 결제 시스템을 만들라는 지시를 받았는데 갑자기 DB 테이블을 삭제한다면, 그건 결제 시스템이 뭔지 몰라서가 아니다. 그냥 해선 안 된다는 구조적 제약이 없기 때문이다. 프롬프트에 "하지 마"라고 써놓는 것은 부탁이지, 강제가 아니다. 에이전트는 그 부탁을 기억하지 못하거나 무시할 수 있다.

 

HumanLayer의 연구에서는 이를 "Dumb Zone"이라고 표현했다. 컨텍스트 창을 아무리 크게 늘려도 근본 문제는 해결되지 않는다. 더 큰 창은 더 큰 건초더미만 만들 뿐이고, 그 안에서 에이전트가 길을 잃는다. 하네스 엔지니어링은 이 두 가지 문제를 동시에 다루는 접근이다.

 

하네스 엔지니어링이란, 어원부터 정확한 정의까지

하네스(harness)는 마구(馬具)를 뜻한다. 곱비, 안장, 고삐처럼 말을 다룰 때 쓰는 도구들이다. 초원에서 자유롭게 달리던 야생마를 경마장에 풀어놓으면 어떻게 될까. 울타리를 넘고 관중석으로 뛰어들 것이다. 마구가 없으면 그 엄청난 힘은 아무 방향으로나 흩어진다. 그런데 마구를 채웠다고 말이 느려지지는 않는다. 오히려 그 힘을 원하는 방향으로 집중시켜서 더 빠르고 정확하게 달리게 된다.

AI 에이전트가 딱 이 야생마와 같다. Claude, GPT, Gemini 같은 모델 자체는 혼자 풀어놓으면 어디로 달릴지 알 수 없다. 하네스 엔지니어링은 그 힘을 억누르는 게 아니라 올바른 방향으로 제어하면서 최대한 활용하기 위한 구조다.

 

이 개념을 처음 명명한 사람은 Mitchell Hashimoto다. HashiCorp 공동창업자이자 터미널 에뮬레이터 Ghostty의 개발자이기도 하다. 그가 2026년 2월 5일 자신의 블로그 "My AI Adoption Journey"에 쓴 글에서 처음 등장했다. 6단계로 구성된 AI 도입 여정의 5단계, "Step 5: Engineer the Harness"가 바로 그 섹션이다.

 

원문 정의는 이렇다.

 

"Anytime you find an agent makes a mistake, you take the time to engineer a solution such that the agent never makes that mistake again."

Mitchell Hashimoto, 2026년 2월 5일

 

에이전트가 실수할 때마다 그 실수가 다시는 반복되지 않도록 엔지니어링하는 것. Hashimoto 본인도 "이 용어가 업계 표준은 아닐 수 있다"고 밝혔지만, 이 정의가 공개되자마자 OpenAI, Anthropic, LangChain이 동조하면서 업계 공용어처럼 굳어졌다.

 

프롬프트 엔지니어링과의 차이는 명확하다. 프롬프트 엔지니어링은 AI에게 잘 부탁하는 방법이고, 하네스 엔지니어링은 그 실수 자체가 불가능한 구조를 만드는 것이다. 부탁은 어길 수 있지만, 구조는 어길 수 없다. 공장의 안전 시스템과 같다. 안전모를 안 쓰면 출입문 자체가 안 열리는 것처럼, 규칙이 시스템에 내장되어 자동으로 강제된다.

 

구분	프롬프트 엔지니어링	하네스 엔지니어링
방식	부탁 (요청 방식 최적화)	강제 (구조적 제약)
실수 재발	다음 세션에 반복 가능	구조적으로 반복 불가
지속성	세션마다 재작성 필요	한 번 설정 후 자동 적용
개선 방식	프롬프트 문구 수정	시스템 자체 업그레이드

 

하네스 엔지니어링의 3가지 핵심 구성 요소

하네스는 세 가지 기둥으로 구성된다. 이 세 가지가 각각 다른 문제를 해결하면서, 조합했을 때 에이전트를 제대로 통제하는 시스템이 만들어진다.

 

1. 컨텍스트 파일 (AGENTS.md / CLAUDE.md)

AI 에이전트가 새 세션을 시작할 때 가장 먼저 읽는 파일이다. 회사에 신입이 들어오면 첫날 반드시 읽어야 하는 온보딩 문서와 같다. 컨텍스트가 꽉 차서 앞 내용을 잊어버려도 이 파일만큼은 새 세션마다 항상 다시 읽는다. 에이전트의 리셋되는 기억을 이 파일이 잡아주는 역할이다.

 

Ghostty 프로젝트의 AGENTS.md에 대해 Mitchell Hashimoto는 이렇게 밝혔다. "그 파일의 각 줄은 에이전트가 저질렀던 나쁜 행동 하나하나에서 나온 것이다(each line in that file is based on a bad agent behavior)." 처음부터 완벽하게 설계한 게 아니라, 실패할 때마다 한 줄씩 추가되면서 점진적으로 만들어진 것이다.

 

작성 시 중요한 원칙이 있다. ETH Zurich 연구에서 자동 생성된 AGENTS.md를 사용한 팀은 벤치마크 성능이 20% 이상 저하되었던 반면, 개발자가 직접 신중하게 작성한 파일을 사용한 팀은 약 4% 성능 향상을 기록했다. 차이는 명확하다. OpenAI 팀이 "첫 페이지 설명서가 아니라 지도를 줘야 한다"고 말한 것도 이 맥락이다. 60줄 이하로 항상 적용되는 내용만 담고, 세부 내용은 docs/ 디렉토리에 분리하는 방식이 실전에서 더 잘 작동했다.

 

2. 자동 강제 시스템 (훅/린터)

에이전트에게 좋은 코드를 써달라고 부탁하는 게 아니라 기계적으로 강제하는 장치다. Martin Fowler는 이를 두 가지로 구분했다. 가이드(Feedforward)는 에이전트를 사전에 올바른 방향으로 유도하는 것이고(AGENTS.md, 툴 설계), 센서(Feedback)는 에이전트가 행동한 후 관찰하고 교정하는 것이다(린터, 테스트).

 

Claude Code의 훅은 4가지 타입이 있다. Command(셸 스크립트), HTTP(외부 엔드포인트 POST), Prompt(Claude 모델 단일 턴 평가), Agent(서브에이전트 스폰)다. 단순한 스크립트부터 도구를 사용하는 서브에이전트까지 다양한 수준의 검증 로직을 구현할 수 있다. 설정 위치도 용도에 따라 나뉜다. 프로젝트 전체에 팀이 공유할 규칙은 .claude/settings.json에, 개인 설정은 .claude/settings.local.json에 넣는다.

 

실전 예시로는 rm -rf 명령 자동 차단이나, TypeScript 파일 저장 시 타입 체크와 포매터 자동 실행 같은 것들이 있다. 이때 중요한 운영 원칙 하나가 "성공은 조용히, 실패만 시끄럽게"다. 테스트 4,000줄이 다 통과됐다는 결과를 에이전트에게 그대로 보여주면, 에이전트가 그걸 읽느라 정작 해야 할 일을 놓친다. 실패했을 때만 에이전트에게 알려주는 것이 핵심이다.

 

3. 컨텍스트 관리 (리셋 + 서브에이전트)

컨텍스트가 꽉 찼을 때 흔히 시도하는 방법이 컨텍스트 압축이다. 그런데 Anthropic 연구에 따르면 압축보다 컨텍스트 리셋이 더 효과적이다. 새 세션을 시작하고 AGENTS.md를 다시 읽는 방식이, 길어진 컨텍스트를 요약해서 이어가는 것보다 에이전트 성능이 더 일관되게 나온다.

 

서브에이전트는 컨텍스트 방화벽 역할을 한다. 독립적인 작업을 서브에이전트로 격리하면 부모 에이전트의 컨텍스트를 오염시키지 않는다. 비용 측면에서는 부모 오케스트레이터는 Opus, 서브에이전트는 Sonnet이나 Haiku를 쓰는 조합이 실용적이다. 에이전트가 실수를 할 때마다 그 실수는 새로운 규칙이 되어 린터와 테스트에 추가된다. 시간이 지날수록 하네스가 점점 더 정교해지는 구조다.

 

하네스 엔지니어링이 만든 실제 성과, 3가지 공식 사례

개념이 아닌 숫자로 봐야 실감이 난다. 하네스 엔지니어링이 실제로 어떤 결과를 만들었는지 세 곳의 공식 발표를 기반으로 정리한다.

 

LangChain: 모델 그대로, 순위만 바뀌다

LangChain은 ML, 디버깅, 생물학 도메인의 89개 태스크로 구성된 Terminal Bench 2.0 벤치마크에서 모델을 전혀 바꾸지 않고 하네스만 개선했다. 결과는 Top 30에서 Top 5권으로 진입, 점수는 52.8%에서 66.5%로 13.7점 상승이었다.

 

핵심 기법은 세 가지였다. 첫째, 완료 직전 자동으로 검증을 강제하는 자기검증 루프(PreCompletionChecklistMiddleware). 둘째, 디렉토리 구조와 툴링을 자동으로 파악하는 컨텍스트 엔지니어링(LocalContextMiddleware). 셋째, 같은 파일을 반복해서 수정하는 패턴을 감지해 접근법을 바꾸도록 유도하는 루프 감지(LoopDetectionMiddleware). 여기에 더해 "reasoning sandwich"라는 기법도 적용했다. 계획과 검증 단계는 최고 추론 수준으로, 구현 단계는 표준 추론 수준으로 돌리는 방식이다.

 

OpenAI: 엔지니어 3명이 5개월간 코드를 쓰지 않은 이유

OpenAI 공식 블로그에 공개된 사례다. 초기 3명으로 시작해 7명으로 확장된 팀이 5개월 동안 수동 코드 작성 없이 약 100만 줄 코드를 생성하고 약 1,500개 PR을 병합했다. 엔지니어 한 명당 하루 평균 3.5개 PR, 일반 개발 대비 3~10배의 생산성이었다.

 

팀이 한 것을 요약하면 네 가지다. AGENTS.md로 AI에게 업무 지침서를 주고, CI Gate로 코드 저장 시 자동 테스트를 돌리고, 에이전트의 접근 범위와 권한을 사전에 설정하고, AI가 코딩-검토-규칙 보강을 반복하는 피드백 루프를 만들었다. 이 과정에서 중요한 실패 교훈도 나왔다. 처음에는 하나의 큰 AGENTS.md에 모든 규칙을 몰아넣었는데 효과가 없었다. 결국 AGENTS.md를 목차(table of contents)로만 쓰고 세부 내용은 docs/ 디렉토리에 분리하는 방식으로 전환했다.

 

이 실험에서 OpenAI가 남긴 말이다. "엔지니어들은 코드를 쓰지 않았다. 그들은 AI가 코드를 신뢰할 수 있게 쓸 수 있는 시스템을 설계했다(The engineers didn't write code. They designed the system that let AI write code reliably.)."

 

Anthropic: 단일 에이전트 vs 멀티 에이전트 하네스

Anthropic이 2026년 4월 공개한 멀티 에이전트 하네스 아키텍처는 Planner(기획), Generator(구현), Evaluator(검증)의 3-에이전트 구조다. 에이전트가 자신의 작업을 과대평가하는 자기 평가 편향 문제를 생성과 평가 역할을 분리해서 해결한 것이다.

 

레트로 게임 메이커 제작 실험에서 결과 차이가 극명하게 드러났다. 단일 에이전트는 20분에 9달러를 써서 엔티티가 제대로 동작하지 않는 불완전한 게임을 만들었다. 반면 멀티 에이전트 하네스로는 6시간에 200달러를 들여 물리 엔진과 AI 지원까지 포함된 16개 피처의 완성본을 만들었다. 시간과 비용은 더 들었지만, 단일 에이전트가 끝내지 못한 작업을 완성했다는 점에서 의미 있다. Generator와 Evaluator가 구현 전에 테스트 가능한 완료 기준을 협의하는 Sprint Contract 패턴도 이 사례에서 나왔다.

 

지금 시작하는 하네스 엔지니어링 실전 적용법

처음부터 완벽한 하네스를 설계하려다가 막히는 경우가 많다. 실전에서 통하는 원칙은 간단하다. 실패가 발생했을 때만 하나씩 추가하는 것이다.

 

Step 1. 첫 번째 실수가 생겼을 때 시작하라

아직 실수가 없다면 하네스를 구축할 필요가 없다. 에이전트가 실제로 실패한 순간이 AGENTS.md에 한 줄을 추가할 때다. 처음부터 모든 경우의 수를 상정해서 길게 작성하면 ETH Zurich 연구에서 확인된 것처럼 오히려 성능이 떨어진다.

Step 2. AGENTS.md / CLAUDE.md 작성 원칙

• 60줄 이하로 유지, 항상 적용되는 규칙만 담는다
• 직접 작성한다. 자동 생성은 성능을 오히려 떨어뜨린다
• 이 프로젝트의 규칙, 사용 도구, 금지 행동, 참조 파일 경로를 담는다
• 규모가 커지면 AGENTS.md는 목차 역할만, 세부 내용은 docs/에 분리한다

Step 3. 자동 강제 도구 설정

Claude Code를 쓴다면 .claude/settings.json에 훅을 추가한다. 팀 공유 규칙은 .claude/settings.json에, 개인 설정은 .claude/settings.local.json에 넣는다. MCP 서버는 CLI로 대체 가능한 경우 CLI를 쓰는 게 낫다. MCP 툴 설명이 시스템 프롬프트를 비대하게 만들어 수천 토큰이 낭비될 수 있다.

Step 4. 컨텍스트를 주기적으로 정리하라

장시간 작업 후 에이전트가 이상한 행동을 보이기 시작한다면 컨텍스트 압축보다 리셋을 시도해 본다. 독립적인 작업은 서브에이전트로 격리해서 부모 에이전트의 컨텍스트를 오염시키지 않도록 한다.

 

모델이 발전하면 하네스는 어떻게 될까

"모델이 더 좋아지면 하네스가 필요 없어지지 않을까"라는 질문이 나올 법하다. 그런데 이미 하네스가 단순해지는 패턴은 현재 진행 중이다. 미래 전망이 아니라 지금 일어나고 있는 일이다.

 

Manus 팀은 6개월 동안 하네스를 다섯 번 리팩토링했다. 모델이 개선될 때마다 구조 일부가 필요 없어졌기 때문이다. LangChain은 Open Deep Research 에이전트를 1년 동안 세 번 재설계했다. Vercel은 툴의 80%를 제거해서 더 적은 단계, 더 빠른 응답, 더 적은 토큰을 달성했다. 강화학습 연구의 리처드 서튼이 말한 "쓴 교훈(Bitter Lesson)"의 맥락과 일치한다. 범용적 접근이 장기적으로 도메인 특화 접근을 이긴다. 오늘 설계한 아키텍처 가정은 새 모델이 나오면 6개월 후 구식이 될 수 있다.

 

Martin Fowler는 하네스의 미래를 템플릿화로 전망한다. 지금 팀들이 새 프로젝트를 시작할 때 서비스 템플릿을 가져다 쓰는 것처럼, 앞으로는 "이 기술 스택용 하네스" 형태로 가이드와 센서가 묶여 제공될 것이라고 본다. 기술 스택을 고르는 기준이 개발자 경험이 좋은 프레임워크에서 하네스가 잘 갖춰진 프레임워크로 바뀔 수 있다는 이야기다.

 

Fowler의 표현을 빌리면 하네스의 본질은 "사람의 개입을 없애는 것이 아니라 가장 중요한 곳으로 방향을 돌리는 것"이다. 모델이 판단할 수 있는 부분은 모델에게 맡기고, 엔지니어의 엄밀함은 그 시스템이 올바르게 작동하는지 검증하는 쪽으로 옮겨간다. 코드를 쓰는 선수에서 전술을 짜는 감독으로 역할이 바뀌는 것이다.

 

 

결국 하네스 엔지니어링은 간단하다. 컨텍스트 파일로 에이전트에게 규칙을 주입하고, 자동 강제 시스템으로 그 규칙을 어길 수 없게 만들고, 컨텍스트 관리로 에이전트가 최고의 성능을 유지하게 한다. 세 가지 기둥이 함께 작동할 때, 에이전트는 비로소 진정한 도구가 된다.

 

흥미로운 건 이거다. 모델이 더 똑똑해질수록 필요한 하네스는 점점 단순해진다. 그럼에도 불구하고 하네스 자체는 절대 없어지지 않는다. 마치 보조 바퀴가 없어져도 자전거는 남아있는 것처럼.

 

AI 에이전트가 오늘 같은 실수를 반복한다면 이렇게 해보자. AGENTS.md를 열고 그 실수가 다시 일어나지 않을 한 줄을 추가하자. 그 한 줄이 바로 하네스 엔지니어링의 시작이다.