원문: @LunarResearcher X 아티클 · 공개: 2026-09-06 · 수집일: 2026-10-04 · 조회 110만
개요
“Harness Engineering: The Complete Guide to Building AI Agents That Don’t Fall Apart”는 에이전트를 고칠 때 프롬프트를 다시 쓰고 모델을 바꾸는 것은 층을 잘못 짚은 것이라고 본다. 실패 대부분은 추론이 아니라 환경에서 난다. 어떤 파일이 중요한지 몰랐거나, 이전 세션의 결정을 잃었거나, 검사를 돌리지 않고 성공을 주장한 경우다. 글은 모델 주변 시스템인 harness를 설계 대상으로 보고 19개 절로 원칙을 정리한다. 요지는 “프롬프트는 한 번의 시도를 바꾸고, 하네스는 모든 시도를 바꾼다”는 문장이다.
핵심 원칙
| 영역 | 원칙 |
|---|---|
| 작업 계약 | 막연한 요청을 objective·scope·constraints·acceptance·approval_required로 구성한 계약으로 바꾼다. 계약이 없으면 에이전트는 그럴듯해 보이는 활동을 최적화한다 |
| 컨텍스트 | 매뉴얼 대신 지도를 준다. 프로젝트 맵 → 서브시스템 → 파일 순으로 점진적으로 공개하고, 목표는 최대 컨텍스트가 아니라 토큰당 최대 신호다 |
| 도구 | 도구를 쌓아 두지 말고 게이트웨이를 둔다. 각 도구에 전제조건·성공 증거·실패 동작·위험 등급을 계약으로 붙이고, 모델이 의도를 정하면 게이트웨이가 검증한다 |
| 구조 | 두뇌(계획)·손(샌드박스 실행)·이력(내구 상태)을 분리한다 |
| 메모리 | 대화 이력은 이벤트 스트림일 뿐이다. facts·decisions·progress·lessons로 상태를 컴파일한다 |
| 완료 | ”done”이라는 말은 증거가 아니다. 문법 → 타입 → 집중 테스트 → 통합 테스트 → 시각 검토 → 사람 승인처럼 싼 결정론적 검사부터 돌린다. 컴파일러나 테스트로 답할 수 있는 질문에 모델을 쓰지 않는다 |
| 검증 | 검증자는 결과를 반박하려고 시도해야 한다. 같은 컨텍스트에서 “다시 확인해”라고 하면 실수를 만든 가정이 그대로 남는다 |
| 정책 | 모델은 제안하고 정책이 허가한다. 위험도에 따라 자동 / 자동+추적 / 명시 승인 / 하드 게이트로 나누고, 정책은 추론 루프 밖에 둔다 |
| 복구 | 실패를 유형별로 분류해서 대응한다. 재시도할 때는 조건을 하나 이상 바꾸고, 같은 실패가 반복되면 멈춘다. 시도 횟수·시간·비용 예산을 둔다 |
| 지시의 인프라화 | 설명 → 체크리스트 → 템플릿 → 자동 검사 → 강제 정책. 반복되는 규칙은 사다리 아래로 내린다 |
| 관측·인계 | 실행을 재구성할 수 있는 트레이스를 남기고, 마지막에 CHANGED·VERIFIED·NOT VERIFIED·RISKS를 담은 변경 영수증을 낸다 |
| 학습·감쇠 | 실패할 때마다 하네스를 개선한다. 다만 모델이 좋아지면 예전 우회책이 짐이 되는 하네스 감쇠가 생기므로 “삭제를 전제로 만든다” |
실무 체크
- 최소 하네스 6단계: 경계 있는 작업 → 읽을 수 있는 환경 → 통제된 행동 → 내구 실행 → 증거 → 복구·학습. 실제로 겪은 실패를 없애는 가장 작은 층부터 쌓는다. 복잡성은 관측된 실패로 정당화돼야 한다.
- 글 말미에 계약·컨텍스트·도구·상태·정책·검증·복구·관측 8개 항목의 하네스 스펙 템플릿이 있다. 이 필드가 비어 있으면 그 에이전트는 자율적인 게 아니라 즉흥 연주를 하는 것이라고 쓴다.
- 지표는 토큰 수가 아니라
accepted outputs / (human review minutes + run cost)다. 첫 통과 수용률, 근거 없는 완료 주장 수, 작업당 사람 개입 수를 함께 본다. - 짧고, 검사하기 쉽고, 실패 비용이 낮고, 외부 부작용이 없는 작업에는 무거운 하네스가 필요 없다.
연결
같은 주제를 다룬 다른 정리는 2026-07-14-the-architect-s-guide-to-harness-engineering와 2026-08-23-walkinglabs-learn-harness-engineering에 있고, 하네스 관련 노트 전체는 moc-ai-agents-harness에 모여 있다. 개념 원칙 위주의 글이고 구체적인 구현이나 측정 데이터는 없다.