AI 에이전트 하네스 엔지니어링 6계층 가이드 — AGENTS.md 템플릿부터 프로덕션 체크리스트까지

데모까지는 누구나 간다. 문제는 그다음이다.

오늘 리뷰할 문서는 Harness Engineering — Agent = Model + Harness: The 6-Layer Production Playbook이다. 2026년 8월 "Production Agent Engineering Practice 2026" 시리즈로 독립 편찬된 기술 노트로, 논문 형식(IEEE 스타일 2단 조판, 표 17개, 참고문헌 15건)을 갖추고 있다. 학회에 실린 정식 논문은 아니고, 어느 회사의 공식 문서도 아니다. 대신 올해 실무 현장에서 쏟아진 1차 자료들을 하나의 아키텍처로 꿴 종합 정리다 — Mitchell Hashimoto(HashiCorp 공동창업자)의 에이전트 방법론, OpenAI의 Codex 필드 리포트, Martin Fowler 진영(Birgitta Böckeler)의 가이드-센서 분류법, LangChain·Cursor·Google Cloud의 벤치마크 기록이 출처다.

문서는 첫 문장부터 수치를 던진다. 기업 AI 에이전트의 95%는 프로덕션에 도달하지 못한다. 데모는 잘 되고, 예산 심사도 통과하는데, 프리프로덕션에서 조용히 죽는다. 보안 리뷰에서 떨어지고, 관찰가능성 요건을 못 채우고, 엣지 케이스에서 환각을 일으킨다. 저자의 진단은 간명하다. 그 격차는 모델의 문제가 아니라 모델을 감싸는 인프라의 부재이고, 그 인프라에는 이름이 있다 — 하네스(harness).

리뷰어로서 이 문서를 고른 이유는 두 가지다. 첫째, 흩어져 있던 실무 지식을 6계층이라는 하나의 구조로 정리했다. 둘째, 주장 대부분이 "모델을 고정하고 하네스만 바꿨을 때"의 측정치로 뒷받침된다. 아래에서는 6계층 전부와 근거 수치, 7일 구축 로드맵, 12항목 프로덕션 체크리스트를 정리하고, 끝에 오늘 바로 복사해 쓸 수 있는 가이드 프롬프트 4종을 붙였다.

공식 하나 — 에이전트 = 모델 + 하네스

2026년 2월 5일, Hashimoto가 자신의 AI 도입기에서 원칙 하나를 공개했다.

"에이전트가 실수를 할 때마다, 그 실수를 다시는 하지 않도록 만드는 해법을 엔지니어링한다."

며칠 뒤 OpenAI 엔지니어 Ryan Lopopolo가 필드 리포트를 냈다. 소규모 팀이 5개월간 약 1,500건의 자동화된 PR로 100만 줄짜리 프로덕션 코드베이스를 사람이 한 줄도 직접 쓰지 않고 만들었다는 기록이다. 사람은 코드를 쓰지 않았다. 신뢰할 수 있는 코드 생성이 가능한 환경을 설계했다. 그들의 구호가 "Humans steer. Agents build."다.

여기서 공식이 굳었다. 에이전트 = 모델 + 하네스. 모델은 추론을 제공한다. 나머지 전부 — 알려진 실패를 막는 가이드, 새 실패를 잡는 센서, 재시도가 제한된 실행 루프, 지속되는 메모리, 강제되는 권한, 완전한 관찰가능성 — 가 하네스다.

문서가 정리한 AI 엔지니어링의 세 시대는 이렇다.

각 시대는 이전 시대를 포함한다. 프롬프트는 모델이 말하는 것을, 컨텍스트는 모델이 보는 것을, 하네스는 모델이 할 수 있는 것을 결정한다.

증거 — 모델을 고정하고 하네스만 바꾸면

이 문서에서 가장 힘이 실린 부분이다. 모델을 그대로 두고 하네스만 교체한 사례들의 수치가 모여 있다.

44%p는 웬만한 모델 세대 교체보다 큰 폭이다. 16개 모델이 하네스 수정 하나로 동시에 좋아졌다는 것은, 우리가 "모델이 약해서"라고 결론 내린 실패 상당수가 사실 하네스 문제였다는 뜻이다.

6계층 아키텍처

① 가이드 — 실행 전에 조향한다

가이드는 에이전트가 일을 시작하기 전에 읽는 지시다. AGENTS.md, CLAUDE.md, .cursorrules 같은 파일이며, 각 줄은 과거의 실패 하나를 영구 예방책으로 변환한 것이어야 한다. 문서가 제시한 최소 템플릿:

PROJECT: [이름]
LANGUAGE: [주 언어]
BUILD: [정확한 빌드 명령]
TEST: [정확한 테스트 명령]
LINT: [정확한 린트 명령]

RULES:
- /config는 묻지 않고 수정하지 않는다
- 코드 변경 후에는 반드시 테스트를 돌린다
- [케이스]에는 [패턴]을 쓴다

ANTI-PATTERNS:
- [실제로 있었던 실패, 날짜 포함]
- [관찰된 또 다른 실패 유형]

핵심 규칙: 가이드에는 실행 가능한 행동과 관찰 가능한 기준만 넣는다. "코드를 잘 짜라"는 가이드가 아니다. 린터 명령과 테스트 명령이 가이드다. 그리고 200줄짜리 날짜 없는 가이드 파일은 하네스가 아니라 기술 부채다 — 월 1회 검토하고, 센서가 대신 강제하게 된 규칙은 지운다.

② 센서 — 실행 후에 검증한다

센서는 출력을 검증하는 되먹임 제어다. 문서의 설계 원칙은 명확하다. 계산형 센서 먼저, 추론형 센서는 마지막.

경제성 계산도 실려 있다. 하루 50회 도는 작업에 1회 10달러짜리 LLM 판정을 붙이면 하루 500달러다. 같은 실수를 잡는 린터 규칙은 0원이다. LLM 판정은 "법률 요약의 정확성" 같은 결정적 규칙으로 못 쓰는 검사에만, 그것도 게이트가 아닌 자문 신호로 쓴다.

가장 강한 패턴은 자기 검증이다. 에이전트가 매 단계 후 스스로 테스트 스위트를 돌리고, 실패하면 에러 원문을 들고 되돌아간다. 모델이 자기 품질을 "판단"하는 것이 아니라, 외부의 결정적 검사를 실행하고 그 결과에 따라 움직이는 것이다.

③ 에이전틱 루프 — 한도가 있는 실행

루프는 단일 모델 호출이 아니다. 계획하고, 실행하고, 센서로 검증하고, 실패를 고치고, 전진하거나 에스컬레이션하는 한도 걸린 사이클이다. 문서가 요구하는 필수 한도:

예산이 소진되면 루프는 현재까지의 최선 결과물 + 완료 목록 + 미해결 이슈 + 멈춘 이유를 반환해야 한다. 부분 실패를 유창한 문장 뒤에 숨기면 안 된다. 그리고 문서는 강조한다 — 올바른 에스컬레이션은 실패가 아니다. 자신 있게 틀린 답을 내는 에이전트보다 제때 사람을 부르는 에이전트가 더 값지다.

④ 메모리 — 모델은 잊고, 하네스는 기억한다

모든 모델 호출은 빈 컨텍스트에서 시작한다. 연속성은 하네스가 명시적 상태 관리로 제공한다. 가장 단순하고 강한 답은 파일시스템이다. plan.md 하나, decisions.md 로그 하나, progress.json 체크포인트 하나. 대부분의 워크플로에서 벡터 DB보다 싸고 단순하고 신뢰할 수 있다.

메모리 계층이 제대로 됐는지 확인하는 테스트도 실용적이다. 복구 테스트 — 여러 단계 작업 중간에 세션을 끊고 다시 열었을 때, 에이전트가 체크포인트를 읽고 마지막 완료 지점을 파악해 다음 단계부터 이어가는가? 완료한 일을 반복하거나 사람에게 다시 설명해 달라고 하면 메모리 계층이 부족한 것이다.

구분 하나만 기억하면 된다. 메모리는 무슨 일이 있었는지를 기록하고, 가이드는 무엇을 해야 하는지를 정의한다. 오래된 대화 속 교정 하나에 의존하지 말고, 안정된 규칙은 가이드 파일로 승격시킨다.

⑤ 권한과 예산 — 모델은 안전을 강제하지 못한다

권한은 모델의 속성이 아니라 하네스의 속성이다. 문서의 역량 예산 템플릿:

ALLOW read:  src/**, tests/**, docs/**
ALLOW write: src/**, tests/**
ALLOW exec:  npm test, npm lint
ASK before:  git push, npm publish, deploy
DENY:        rm -rf, DROP TABLE, send_email
RATE:        작업당 쓰기 최대 20회
COST:        작업당 최대 $5
TIMEOUT:     30분

원칙은 최소 권한이다. 소스를 읽고 테스트를 돌리는 작업이면 딱 그 권한만 준다. 불필요한 권한 하나하나가 프롬프트 인젝션의 공격면이고 에이전트 실수의 폭발 반경이다. 특히 에이전트가 이메일·웹페이지·문서 같은 신뢰할 수 없는 콘텐츠를 읽는 순간, 그 안에 심어진 악성 지시가 권한을 확장하거나 비밀을 빼돌리려 시도할 수 있다 — 신뢰된 지시(가이드·시스템 프롬프트)와 비신뢰 데이터(입력·검색 결과)를 모든 작업에서 분리해야 한다.

⑥ 관찰가능성 — 전부 추적하고, 드리프트에 경보를 걸어라

프로덕션 하네스는 텔레메트리를 요구한다. 시작·종료 타임스탬프, 도구 호출과 결과, 사용된 가이드 버전과 센서, 시도 횟수와 비용, 산출물, 승인, 에스컬레이션. 여기에 트립와이어 — 집계 행동이 이상해지면 자동으로 울리는 경보를 건다.

측정 지표도 하나로 못 박는다. 모델 호출 수나 토큰 수를 세지 말 것. 사람의 개입 없이 완료되고, 수용 가능한 증거를 남긴 작업의 수를 셀 것. 이 지표 하나가 "겉보기에 인상적인 에이전트"와 "실제로 일하는 에이전트"를 가른다.

개선 루프 — 래칫

6계층을 관통하는 운영 원리가 하시모토의 **래칫(ratchet)**이다. 래칫은 한 방향으로만 도는 톱니바퀴다. 실패가 나올 때마다 시스템은 영구적으로 좋아지고, 뒤로는 돌지 않는다.

실패 유형별로 약한 수정과 강한 수정이 갈린다.

Cursor의 Lauren Tan이 제시한 전환 신호도 실려 있다. 사람 리뷰어가 같은 리뷰 코멘트를 세 번 넘게 쓰면, 그 코멘트는 구조적 제약이 되어야 한다. 첫 번째엔 가이드 규칙을 추가하고, 두 번째엔 그 규칙이 읽히는지 검증하고, 세 번째엔 위반을 차단하는 센서로 바꾼다. 네 번째는 없어야 한다.

7일 구축 로드맵

문서의 빌드 경로는 "한 계층이 증명된 뒤에만 다음 계층을 올린다"는 원칙으로 짜여 있다.

2주 차부터는 래칫으로 확장한다. 같은 실수가 두 번 나면 가이드 규칙이 빠진 것이고, 미묘하게 이상한 출력이 나오면 센서가 빠진 것이고, 범위를 벗어나면 권한이 넓은 것이다. 한 번에 한 계층만 바꾸고, 효과를 측정하고, 스코어카드가 나빠지면 되돌린다.

하네스를 만들지 말아야 할 때

모든 에이전트에 하네스가 필요한 것은 아니다. 문서의 판별 기준 세 가지.

• 에이전트가 조용히 잘못된 결과를 내면 알아챌 수 있어야 하는가? → 센서 필요
• 같은 컨텍스트를 다음 세션에서 또 설명해야 하는가? → 메모리 필요
• 실수 하나가 외부에 실제 결과를 만드는가? → 권한 필요

셋 다 아니라면 대화 자체가 하네스다. 일회성 질문, 창작 브레인스토밍, 개인 메모 정리에는 하네스가 필요 없다. 반대로 매일 도는 코드 리뷰, 고객 응대 분류, CI/CD 파이프라인 에이전트라면 필요하다. 과잉도 경계한다 — 가이드 규칙 500개, 추론형 센서 12개, LLM 리뷰 3겹, 승인 단계 40개짜리 하네스는 안전을 가장한 병목이다. 하네스는 에이전트를 신뢰할 수 있게 만드는 최소한의 인프라여야 한다.

바로 쓰는 가이드 프롬프트 4종

여기서부터가 실전이다. 문서의 템플릿들을 Claude Code·Codex 같은 코딩 에이전트에 바로 붙여 쓸 수 있는 프롬프트로 변환했다.

① AGENTS.md 최초 생성 — 1일차에 한 번.

이 저장소를 스캔해서 AGENTS.md를 만들어줘.

포함할 것:
- PROJECT: 프로젝트 이름과 한 줄 목적
- LANGUAGE: 주 언어와 버전
- BUILD / TEST / LINT: 실제로 동작하는 정확한 명령어 — 반드시 직접 실행해서 검증할 것
- RULES: 이 코드베이스에서 하면 안 되는 것 3가지 (코드 패턴과 설정에서 추론)
- ANTI-PATTERNS: 과거에 실제 있었던 실수 (git log의 fix·revert 커밋에서 찾아 날짜와 함께)

규칙:
- "코드를 잘 짜라" 같은 조언 금지. 모든 항목은 검증 가능한 행동으로 쓴다.
- 각 규칙은 린터나 테스트로 확인 가능한 형태여야 한다.
- 20줄 이내로 시작한다. 규칙은 실패가 나올 때마다 한 줄씩 늘린다.

② 래칫 프롬프트 — 에이전트가 실수할 때마다. 이 프롬프트가 이 글에서 가장 자주 쓰게 될 것이다.

방금 에이전트가 이런 실수를 했다: [실수 내용과 입력 붙여넣기]

래칫 원칙으로 처리해줘:
1. 같은 입력으로 실패를 재현한다.
2. 근본 원인을 분류한다 — 가이드 누락 / 센서 부재 / 권한 과다 / 상태 유실 / 관찰 공백.
3. 이 실수를 구조적으로 막는 가장 강한 계층을 고른다.
   (프롬프트 패치 < 가이드 규칙 < 린터·테스트 센서 < 권한 경계 < 환경 제약)
4. 그 계층에 수정을 넣는다. 프롬프트에 "주의하라"를 추가하는 것은 수정이 아니다.
5. 원래 실패 입력으로 수정을 검증한다.
6. 기존 테스트를 돌려 다른 기능이 깨지지 않았는지 확인한다.
어느 단계도 건너뛰지 마라. 1을 건너뛰면 유령을 고치는 것이고, 6을 건너뛰면 하나를 고치며 셋을 깨뜨리는 것이다.

③ 권한·예산 정책 생성 — 무인 실행을 켜기 전에.

이 에이전트 워크플로의 권한 정책을 만들어줘: [워크플로 설명]

네 가지 차원으로 작성한다:
- 범위: ALLOW / ASK / DENY로 읽기·쓰기·실행 경로와 명령을 명시 (최소 권한)
- 횟수: 작업당 최대 쓰기 횟수, 외부 호출 횟수
- 비용: 작업당 토큰·금액 상한, 최대 재시도, 타임아웃
- 가역성: 되돌릴 수 없는 행동(배포·삭제·외부 발송)은 전부 사람 승인(ASK)으로

기준은 하나다 — 이 작업에 그 권한이 정말 필요한가? 확신이 없으면 DENY가 기본값이다.

④ 월간 가이드 정리 — 가이드가 기술 부채가 되는 것을 막는다.

AGENTS.md를 감사해줘. 각 규칙에 대해 답할 것:
1. 에이전트가 주관적 판단 없이 이 규칙을 검증할 수 있는가?
2. 이 규칙은 실제 관찰된 실패에서 나왔는가?
3. 서로 모순되는 규칙 쌍이 있는가?
4. 이미 린터·테스트(센서)가 강제하고 있어서 지워도 되는 규칙은?
5. 마지막으로 검증된 지 가장 오래된 규칙은?
결과를 삭제 후보 / 센서 전환 후보 / 유지 세 그룹으로 나눠 보고해줘.

프로덕션 체크리스트

무인 실행을 켜기 전 12항목. 하나라도 비면 그 계층부터 채운다.

리뷰를 마치며 — 하네스가 유일한 변수였다

이 문서의 결론은 한 문장으로 줄일 수 있다. 모델은 지능을 제공하고, 그 지능이 제품이 되는지는 하네스가 결정한다. 44%p 벤치마크 스윙, 25계단 순위 상승, 수동 코드 0줄의 100만 줄 — 전부 모델은 그대로였고 하네스만 변수였다.

주의할 점도 문서 스스로 적고 있다. 하네스는 잘못된 목표를 고쳐 주지 않는다. 수용 기준이 틀렸으면 센서는 틀린 출력을 성실하게 통과시키고, 하네스는 그 오류의 규모를 키운다. 계층을 쌓기 전에 "무엇이 성공인가"부터 검증 가능한 문장으로 적어야 하는 이유다.

시작은 작다. 가이드 파일 하나, 센서 하나, 권한 경계 하나, 지표 하나, 트립와이어 하나. 그리고 실패가 나올 때마다 래칫을 한 칸 돌린다. 에이전트가 같은 실수를 두 번 하지 않는 조직과 매번 같은 실수를 교정하는 조직 — 격차는 거기서 벌어진다. AX Ops 방법론 →

참고

• 원문 — Harness Engineering: Agent = Model + Harness, The 6-Layer Production Playbook (Production Agent Engineering Practice 2026, 2026년 8월)
• Mitchell Hashimoto, "My AI Adoption Journey", 2026년 2월: https://mitchellh.com/writing/my-ai-adoption-journey
• Ryan Lopopolo (OpenAI), "Harness engineering: leveraging Codex in an agent-first world", 2026년 2월: https://openai.com/index/harness-engineering/
• Birgitta Böckeler (martinfowler.com), "Harness engineering for coding agent users" — 가이드·센서 분류법: https://martinfowler.com/articles/harness-engineering.html
• Birgitta Böckeler (martinfowler.com), "Maintainability sensors for coding agents": https://martinfowler.com/articles/sensors-for-coding-agents.html
• Anthropic, "Building Effective Agents", 2024년 12월: https://www.anthropic.com/research/building-effective-agents