하네스 엔지니어링 북 심층 분석

파트 3(실전 설계), 5(운영/최적화), 6(실전 프로젝트)에서 추출한 핵심 기법과 패턴 정리.

PART 3: 실전 하네스 설계

AGENTS.md 작성법

실패 1건 = 방지책 1줄 원칙 Ghostty 프로젝트(Mitchell Hashimoto)에서 검증된 접근법. 에이전트가 실수할 때마다 해당 실수를 방지하는 지시 한 줄을 AGENTS.md에 추가. 시간이 지나면서 프로젝트의 암묵지가 명시지로 전환됨.

6대 핵심 영역 (GitHub 2,500+ 리포 분석) 1. 프로젝트 개요 (기술 스택, 디렉토리 맵) 2. 코딩 규약 (네이밍, 포맷, 린터, import 순서) 3. 빌드/테스트 (명령어, CI 연동) 4. 금지 사항 (보안/성능/호환성 제약) 5. 도구 사용법 (프로젝트 전용 스크립트, 환경변수) 6. 알려진 함정 (과거 실패 사례, 버전 호환성)

60줄 황금률 - 60줄 = 800~1,200 토큰, 시스템 프롬프트 5% 미만 - 프론티어 LLM이 안정적으로 따를 수 있는 지시 수: 150~200개 - 100줄 넘으면 분할: 디렉토리별 하위 AGENTS.md 또는 Skills로 이관 - 300줄 넘으면 에이전트가 규칙을 선택적으로 무시하기 시작

LLM이 쓴 지시는 역효과 (ETH Zurich 연구) - LLM 자동 생성 지시: 태스크 성공률 3% 하락 - 인간 작성 지시: 성공률 8~15% 향상 - 원인: LLM 생성 지시는 일반론 반복(신호 대 잡음 비율 저하), 인간 지시는 프로젝트 고유 맥락 포함

좋은 지시의 조건 - "~하지 마라" + "대신 ~해라" 쌍으로 작성 - 측정 가능한 기준 포함 (숫자, 도구 이름, 파일 형식) - "에이전트가 모르는 것"만 담기 (사전 학습으로 아는 일반 지식 배제)

반복 주기 설계 | 주기 | 행동 | 기대 결과 | |------|------|-----------| | 일간 | 에이전트 실수 시 규칙 1줄 추가 | 즉각 오류 감소 | | 주간 | 전체 검토, 중복/충돌 규칙 정리 | 간결성 유지 | | 월간 | 재발률 측정, 구조 변경 검토 | 장기 품질 개선 |

자가 품질 진단 10항목 (7개 이상 통과 시 실전 투입 가능) 1. 60줄 이내인가 2. 모든 지시가 측정 가능한가 3. 금지와 대안이 쌍으로 있는가 4. 빌드/테스트 명령어가 복사 실행 가능한가 5. LLM이 이미 아는 일반론 없는가 6. 최근 3개월 내 업데이트됐는가 7. 디렉토리 구조 명시돼 있는가 8. 알려진 함정 기록돼 있는가 9. 환경 변수 설정법 있는가 10. git으로 버전 관리되는가

도구 설계 패턴

Anthropic 7대 도구 설계 원칙 (Ken Aizawa) 1. 고영향 워크플로우만 도구로 만든다 (모든 API 엔드포인트 감싸지 않음) 2. 네임스페이스로 정리 (service_action 형식: asana_search, asana_create) 3. 의미 있는 컨텍스트 반환 (UUID 대신 자연어 이름) 4. 토큰 효율 극대화 (응답 25,000 토큰 이내, 페이지네이션/필터링 기본 제공) 5. 설명문이 행동을 결정 (사용 시점, 반환 형식, 제약 조건 포함) 6. 액셔너블 에러 반환 ("404" 대신 복구 절차 포함 메시지) 7. 프로토타입에서 시작 (eval 실행 -> 설명문 개선 반복)

설명문 한 줄 수정으로 올바른 도구 선택률 40% -> 78% (실제 사례)
가장 과소평가되는 원칙: 5번(설명문). 도구 호출 전 결정 재료가 설명문이기 때문

5대 오케스트레이션 패턴

패턴	핵심 원리	최적 시점	복잡도
Router	입력 분류 -> 경로 분배	입력 유형 명확 구분 시	낮음
Chain	A->B->C 순차 처리	단계적 품질 게이트 필요 시	낮음
Parallel	A+B+C 동시 처리	독립 태스크 빠르게 처리 시	중간
Orchestrator-SubAgent	상위 위임->하위 실행->요약	복잡한 멀티 영역 태스크	높음
Evaluator-Optimizer	생성->평가->개선 반복	자동 품질 검증 가능 시	중간

패턴 선택 의사결정 트리 - Q1: 입력 유형 2개 이상? YES -> Router - Q2: 태스크 간 순서 의존성? YES -> Chain - Q3: 독립 병렬 실행 가능? YES -> Parallel, NO -> Orchestrator - 추가: 결과 품질 자동 검증 가능? -> Evaluator-Optimizer 결합

핵심 원칙: 간단한 패턴에서 시작, 측정된 근거가 있을 때만 복잡도 상승

MCP 통합 패턴 - Lazy Discovery: 도구 스키마 전부 로드 안 함. 이름+한줄설명만 경량 인덱스 유지, 필요 시 스키마 로드 - Progressive Disclosure: 작업 맥락에 따라 노출 도구 자체가 달라짐 (코드 작성 중 = 파일 도구, 배포 중 = CI/CD 도구) - 동시 노출 도구 적정선: 15~20개 이내

컨텍스트 엔지니어링

프롬프트 엔지니어링 vs 컨텍스트 엔지니어링 - 프롬프트: "내가 쓰는 문장" / 컨텍스트: "에이전트가 참조하는 모든 정보" - 프롬프트 엔지니어링은 컨텍스트 엔지니어링의 부분집합 - 핵심 정의: "최소한의 고신호 토큰 셋으로 원하는 결과의 가능성을 최대화" (Anthropic)

컨텍스트 관리 4대 전략

JIT(Just-in-Time) 검색: 파일 100개 내용 대신 경로 100개를 경량 인덱스로 유지. 필요 시 상위 2~3개만 로드. 사전 로딩 대비 70%+ 토큰 절약
하이브리드 전략: 사전 로딩(프로젝트 구조, AGENTS.md) + 자율 탐색(grep, glob으로 필요 시 검색). 기준: "첫 도구 호출 전에 알아야 하는 것"만 사전 로딩
컴팩션 (대화 이력 압축): 5단계 점진적 컴팩션 (OpenDev 논문)
1단계: 요약 (오래된 턴을 요약문으로 대체)
2단계: 트렁케이션 (장황한 도구 출력 핵심만 남기기)
3단계: 버킷팅 (주제별 묶어 중복 제거)
4단계: 메모리 병합 (여러 요약을 상위 요약으로)
5단계: 퇴거 (우선순위 낮은 콘텐츠 삭제)
서브에이전트 아키텍처 (컨텍스트 방화벽): 탐색 서브에이전트가 자체 컨텍스트에서 20개 파일 읽기 -> 메인에이전트에 200 토큰 요약만 반환. 원시 출력 대비 99.6% 절감

Context Rot 현상 - 토큰 볼륨 증가 -> 에이전트 리콜 정확도 감소 - 100개 토큰에서 핵심 10개 찾기 vs 100,000개에서 찾기는 난이도가 다름 - 대응: JIT + 컴팩션 + 서브에이전트 = "덜 넣되 정확히 넣기"

스킬 기반 지식 아키텍처 - 500줄 AGENTS.md = 백과사전 (탐색 어려움, Context Rot 유발) - Skills 기반 = 지도 (전체 구조 보여주고, 필요한 곳으로 안내) - 핵심 40줄 + 필요 시 스킬 로드 = 토큰 절약 + 맞춤 정보

듀얼 메모리 아키텍처 | 유형 | 설명 | 수명 | |------|------|------| | 에피소딕 메모리 | 현재 대화 이력 | 세션 내 | | 워킹 메모리 | 관찰 요약 | 세션 내 (컴팩션 대상) | | 장기 메모리 | AGENTS.md, 진행 파일, git | 세션 간 | | 외부 메모리 | 파일시스템, DB | 영구적 |

핵심: 파일시스템이 세션 간 메모리 역할. 컨텍스트 윈도우의 휘발성을 파일시스템의 영속성으로 보완

PART 5: Eval 주도 개발 + 멀티에이전트 + 비용 최적화

EDD (Eval Driven Development)

EDD = AI 시대의 TDD - TDD: 테스트 먼저 쓰고 코드 구현 - EDD: Eval 먼저 만들고 하네스 개선 - 차이: 단일 결과의 정답 여부가 아닌 반복 실행의 성공률이 기준 ("10번 중 8번 이상 올바른가?")

Eval 파이프라인 6단계 구축법

실패 수집: 20~50개 실패 기반 태스크로 시작. 이상적 결과 상상이 아닌 실제 실패 복기
평가 기준 정의: 확률적 임계값 사용. 예: "타입 안전성 10회 중 9회 통과"
자동 실행 환경: 태스크마다 클린 Git 브랜치, 에이전트 출력 기록, 자동 채점
채점 함수: 코드 기반(AST/린터/테스트), LLM 기반(정성적 판단), 혼합 방식
기준선 측정: 현재 하네스 상태에서의 baseline. 이것이 개선 출발점
반복 개선: 가장 통과율 낮은 카테고리부터 하네스 수정 -> 재측정

점수 가중치 설계 사례 - 테스트 통과: 60점, 패턴 일치: 25점, 코드 길이 제한: 15점 - 테스트 통과에 가장 큰 비중, 코드 품질도 무시하지 않는 균형

CI/CD 통합 - 트리거: CLAUDE.md, .claude/, eval/ 변경 시에만 실행 (불필요한 API 비용 방지) - regression-tolerance 0.05: 기준선 대비 5%p 이상 하락 시 PR 실패 처리 - 실제 사례: CLAUDE.md 3줄 추가로 통과율 60% -> 80%

자동 개선 루프 - 테스트 실패율 50%+ -> 프롬프트 문제, 함수 시그니처 규칙 추가 필요 - 코드 길이 초과 30%+ -> "간결한 구현 우선" 규칙 추가 필요 - 회귀 감지 -> 최근 하네스 변경 검토 - 생성 시간 30초+ -> 프롬프트 모호함 또는 과도한 컨텍스트

멀티에이전트 하네스

4가지 오케스트레이션 패턴

패턴	에이전트 수	복잡도	비용	적합 작업
싱글	1	낮음	낮음	단일 기능, 버그 수정
서브에이전트	2~5	중간	중간	복합 기능, 탐색+구현
멀티에이전트	2~N	높음	높음	병렬 개발, 대규모 마이그레이션
Plan-and-Execute	2~3	중간~높음	중간	장기 프로젝트

Anthropic 3-에이전트 시스템 - Initializer: 프로젝트 뼈대 설정, 진행 추적 파일 생성 (1회 실행) - Generator: 세션별 구현. progress.md 읽고 미완료 기능 선택 (반복 실행) - Evaluator: Playwright 기반 E2E 검증, Sprint 계약 대비 채점 - 핵심: 테스트 가능한 성공 기준을 구현 전에 합의 = Sprint 계약

3가지 충돌 유형과 해결책

충돌	원인	해결책
동시 파일 편집	같은 파일 수정	Git 워크트리 분리 + 순차 머지
의사결정 전파 누락	인터페이스 불일치	공유 상태 파일 (.claude/shared-contracts.md)
비용 폭주	무한 루프/비효율	에이전트별 예산 할당 (토큰/도구호출/시간/재시도 상한)

Stripe 1,000 PR/주 시스템 핵심 - 작은 에이전트 팀: 태스크를 컨텍스트 윈도우가 감당 가능한 크기로 제한 (파일 5개 이내) - 3단계 자동 검증: 컴파일 -> 테스트 -> 스키마 체크 - 스키마 변경은 사람에게 에스컬레이션 (에이전트 판단 어려운 영역) - 컨텍스트 정밀 관리: 태스크 관련 파일 1~3개만 로드, 무관 파일 차단

비용 최적화

토큰 경제학 핵심 - 출력 토큰이 입력 토큰보다 5배 비쌈 -> "간결하게 응답하라" 지시 = 직접적 비용 절감 - 캐시 읽기 비용 = 일반 입력의 10% -> 시스템 프롬프트 캐싱 효과 큼

모델 라우팅 (3단계) | 작업 유형 | 모델 | 비용 배수 | |-----------|------|-----------| | 아키텍처 설계, 복잡한 버그 | Opus | 1x | | 기능 구현, 테스트 작성 | Sonnet | 0.2x | | 포맷팅, 단순 변환 | Haiku | 0.05x |

전체 작업의 70%는 Sonnet/Haiku로 처리 가능
Opus를 30% 핵심 작업에만 집중 -> 전체 비용 40~60% 감소

Reasoning Sandwich - 계획(고추론) -> 구현(표준 추론) -> 검증(고추론) - 양 끝에 비싼 추론 배치, 가운데 경량화

비용 절감 5가지 기법 1. 성공 출력 억제: 성공 시 "Build succeeded"만, 실패 시에만 상세 출력 2. Lazy Discovery: MCP 도구 스키마 전부 로딩 안 함 3. 반복 속도 최적화: 완벽한 프롬프트 1번보다 짧은 피드백 루프 여러 번 4. 태스크별 토큰 예산: 버그 50K, 기능 200K, 리팩토링 500K 5. 이터레이션 캡: 둠 루프 방지, 파일 수정 횟수 추적

비용 모니터링 4대 지표 - 태스크당 평균 비용 - 태스크당 평균 도구 호출 횟수 - 성공률 (비용 대비 완료율) - 모델별 비용 분포

실패하는 하네스 7가지 징후 - 설계 안티패턴: 과도한 제약, 규칙 폭발(500줄), Eval 부재, 모델 의존 착각 - 운영 안티패턴: 하네스 부패(문서-코드 괴리), 비용 블랙홀, 거버넌스 부재 - 최우선 해결: Eval 구축 -> 하네스 부패 해소 -> 나머지

PART 6: 실전 프로젝트

AGENTS.md 워크숍 (19장)

Step 1 - 프로젝트 분석 (15분): 5개 질문 답변이 AGENTS.md 뼈대 - 빌드 명령어, 테스트 실행법, 코드 스타일, 금지 패턴, 에이전트 반복 실수

Step 2 - 빈 템플릿 작성 (20분): 약 30줄 범용 템플릿 - 프로젝트 개요 / 빌드&실행 / 테스트 / 코드 스타일 / 금지 패턴 / Git / 과거 실수

Step 3 - 테스트와 반복 개선 (지속): 에이전트에게 이전 실수 유형 재시도 -> 같은 실수 나오면 규칙 강화

실전 템플릿 3종: 웹 프론트엔드 / 백엔드 API / 데이터 파이프라인 - 공통 골격 + 도메인별 특수 섹션 (웹: 접근성, 백엔드: 보안, 데이터: 거버넌스)

Eval 파이프라인 구축 실습 (20장)

4단계 구조: 입력(프롬프트) -> 에이전트 실행(코드 생성) -> 검증(테스트+정적분석) -> 기록(점수+트레이스)

핵심 구현 요소 - EvalRunner: 태스크별 코드 생성 -> 테스트 실행 -> 점수 산출 - ScoreTracker: 실행 이력 관리, 회귀 감지 (5점 이상 하락 케이스 자동 탐지) - 자동 개선 제안: 실패 패턴 분류 -> AGENTS.md 업데이트 후보 생성

배포/운영 패턴 (21장)

하네스 4기둥 최종 조립

기둥	구현	핵심 파일
Inform	AGENTS.md + Skills + MCP	AGENTS.md, .claude/skills/, mcp.json
Constrain	Hooks(PreToolUse/PostToolUse/PostResponse) + 퍼미션	hooks.json
Verify	Eval 파이프라인 + Self-check 스킬 + 서브에이전트	eval/, self-check.md
Correct	루프 탐지 + 컨텍스트 컴팩션	loop_detector.py

자가 검증 체크리스트 (PreCompletionChecklistMiddleware) - "완료/done/finish" 트리거 시 자동 로딩 - TerminalBench 2.0에서 이 패턴 하나로 13.7%p 점수 향상

루프 탐지: 같은 파일 5회 이상 편집 -> "현재 접근법 재고" 시그널

5계층 보안 모델 (OpenDev) 1. Prompt: 시스템 프롬프트에 해로운 행동 금지 2. Schema: 도구 스키마로 가능 작업 제한 3. Runtime: 퍼미션 시스템 (Manual -> Semi-Auto -> Auto) 4. Tool: 위험 패턴 차단, 변경 감지 5. Hooks: 사용자 정의 라이프사이클 개입

OpenClaw 적용 가능 항목

기법	현재 상태	적용 방법	우선순위
60줄 황금률	CLAUDE.md가 이미 간결하게 유지 중	주간 검토 주기 추가로 규칙 폭발 예방	중간
실패 1건=방지 1줄	CLAUDE.md에 feedback_ 패턴으로 일부 적용 중	에이전트 실수 시 즉시 CLAUDE.md 업데이트 체계화	높음
Skills 기반 지식 아키텍처	이미 Skills 다수 구현 (company-research, infra-ops 등)	조건부 규칙을 CLAUDE.md에서 Skills로 추가 이관	중간
서브에이전트 컨텍스트 방화벽	dispatching-parallel-agents 스킬로 적용 중	Opus(계획)+Sonnet(실행)+Haiku(탐색) 모델 티어링 강화	높음
EDD (Eval 파이프라인)	미구현	파이프라인 스크립트 20개 실패 케이스 수집 -> 자동 Eval 구축	최고
자가 검증 체크리스트	verification-before-completion 스킬로 부분 적용	체크리스트 항목을 파이프라인별로 구체화	높음
루프 탐지	CLAUDE.md에 "같은 에러 2회->방법 전환, 3회->보고" 규칙 존재	Hooks로 하드 제약 구현 (파일 편집 횟수 자동 추적)	중간
비용 모니터링	미구현	LLM 호출마다 태스크ID/모델/토큰/비용 로깅 체계 구축	높음
공유 상태 파일	미구현	멀티에이전트 작업 시 .claude/shared-contracts.md 도입	낮음
Reasoning Sandwich	서브에이전트 모델 선택으로 부분 적용 (탐색=haiku, 일반=sonnet, 분석=opus)	워크플로 내 구간별 추론 강도 명시적 조절	중간
MCP Lazy Discovery	MCP 도구 다수 등록 중	도구 수 15~20개 이내 유지, 불필요한 MCP 스키마 경량화 검토	중간
하네스 부패 방지	수동 점검	주간 자동 점검 (CLAUDE.md 규칙 vs 실제 코드 일관성)	중간