하네스 엔지니어링 완전 정복 2부 - AGENTS.md 설계, 도구 패턴, 플랫폼 비교 및 EDD

하네스 엔지니어링 완전 정복 2부에서는 실전 AGENTS.md 설계, 5가지 도구 설계 패턴, 플랫폼별(Claude Code, Cursor, Devin 등) 하네스 비교, Eval 주도 개발(EDD), 그리고 직군별 활용법을 완벽하게 다룹니다.

PART 3. 실전 하네스 설계 & 도구 패턴

08. AGENTS.md 작성 완벽 가이드

AGENTS.md는 프로젝트 루트 디렉토리에 배치되어 AI 에이전트의 모든 행동 지침을 규정하는 핵심 하네스 파일입니다.

📋 최상급 실전 AGENTS.md 템플릿 예시

# AGENTS.md - DAVHAVE Project Engineering & Automation Rules

## 1. Project Overview & Tech Stack
- **Project**: DAVHAVE Home & Education Platform
- **Core Stack**: Cloudflare Workers, Cloudflare D1 (SQLite), Vanilla CSS, ES2024 JavaScript
- **Architecture**: Edge-rendered Serverless Application

## 2. Strict Constraints (Constrain)
- **CSS Rule**: Do NOT use TailwindCSS or external UI frameworks. Use Vanilla CSS in public/index.html.
- **Dependency Rule**: Do NOT install heavy npm packages without explicit review.
- **Safety Rule**: Never delete D1 database tables without backup. Always use 'ON CONFLICT DO UPDATE'.

## 3. Context & Information (Inform)
- **Routing File**: src/worker.js handles edge requests.
- **Render Engine**: src/lib/education-render.js renders Markdown lessons.
- **Categories**: Must maintain exact mapping in CATEGORIES object.

## 4. Verification Pipeline (Verify)
- Execute syntax verification before proposing completion:
  node --check src/worker.js
  npx wrangler deploy --dry-run
- Run DB integrity check:
  npx wrangler d1 execute davhave-content --local --command "SELECT count(*) FROM posts;"

## 5. Self-Correction Protocol (Correct)
- If a build fails, inspect logs from manage_task or terminal output silently.
- Do NOT mask errors by returning empty dummy objects.
- Minimum character limit per education lesson is 3,000 characters.

09. 도구 설계 패턴 5가지 (Tool Design Patterns)

패턴명	핵심 규칙 및 설명	실전 적용 코드 예시
1. Single-purpose	한 도구는 단 하나의 명확한 조작만 전담	`view_file`(읽기)과 `replace_file_content`(수정)의 완전 분리
2. Atomic Tool	도구 수행 중 오류 발생 시 원자적 복구	수정 도중 에러 시 이전 파일 스냅샷으로 자동 복원
3. Clear Schema	입력 파라미터를 JSON Schema로 엄격히 명시	`TargetFile`(필수, 절대경로), `StartLine`(정수) 등 타입 강제
4. Error Boundary	에러 시 프로세스가 죽지 않고 디버그 로그 반환	CLI 실행 실패 시 Exit Code 및 stderr 메시지 전달
5. Safe Re-try	동일 조작 재실행 시 idempotency(멱등성) 보장	SQL `INSERT ... ON CONFLICT DO UPDATE` 구문 사용

10. 컨텍스트 엔지니어링 & 토큰 최적화

컨텍스트 프루닝 (Context Pruning): 작업에 불필요한 과거 대화 로그 및 커다란 바이너리/로그 텍스트 절삭
프롬프트 캐싱 (Prompt Caching): 변경되지 않는 AGENTS.md 및 기본 시스템 프롬프트를 캐시에 유지하여 토큰 비용 80% 절감
컨텍스트 압축 (/compact / Summary): 대화 타임라인이 길어지면 핵심 의도만 남기고 요약 압축 수행

PART 4. 플랫폼별 하네스 구현체 비교

플랫폼	주요 하네스 구성요소 및 특징	샌드박싱 및 보안 방식
Claude Code	CLI 기반 샌드박스, Subagent 구조, Doctor 진단, OAuth Keychain	Shell Isolation, Prompt Caching, MCP 연동
Cursor	`.cursorrules`, 인라인 Diff 하네스, Fast Indexing RAG	Codebase Graph Indexing, Vector Search
Devin	가상 OS 샌드박스, Headless Browser, 터미널 루프 제어 하네스	Full Linux Container VM, Visual Feedback
OpenAI Codex	코드 실행 샌드박스, 자동 인터프리터 회류 하네스	Python Isolated Execution Environment

PART 5. 운영과 최적화 & EDD (Eval-Driven Development)

15. Eval 주도 개발 (EDD) 4단계 라이프사이클

     ┌────────────────────────────────────────────────────────┐
     │ 1. Define Task Benchmarks (실전 평가 태스크 30개 설정)    │
     └───────────────────────────┬────────────────────────────┘
                                 │
     ┌───────────────────────────▼────────────────────────────┐
     │ 2. Run Agent Assessment (하네스 적용 후 자동 평가 실행)   │
     └───────────────────────────┬────────────────────────────┘
                                 │
     ┌───────────────────────────▼────────────────────────────┐
     │ 3. Measure Pass Rate (성공률, 빌드에러, 토큰소비량 집계)│
     └───────────────────────────┬────────────────────────────┘
                                 │
     ┌───────────────────────────▼────────────────────────────┐
     │ 4. Refine Harness Rules (실패 원인 분석 ➔ AGENTS.md 보강) │
     └────────────────────────────────────────────────────────┘

23. 실패하는 하네스의 7가지 징후와 트러블슈팅

Over-constraining (과도한 제약): 지나친 금지 명령으로 에이전트의 문제 해결 능력 마비 ➔ 자율성 영역 확보
Context Overload (컨텍스트 과부하): 불필요한 전체 코드베이스 주입으로 토큰 폭발 및 지능 저하 ➔ 프로젝션 맵 적용
Test Swallowing (에러 삼킴): 예외 발생 시 빈 성공 응답을 보내 디버깅 방해 ➔ 명시적 stderr 파이프 전달
Missing Verification Loop (검증 생략): 코드 수정 후 빌드/테스트를 거치지 않고 완결 선언 ➔ Verify 파이프라인 강제
Vague Tool Schemas (모호한 규격): 인자 설명 미비로 형식을 오인 ➔ JSON Schema description 보강
No Rollback Capability (롤백 불가능): 오수정 누적으로 코드 오염 ➔ Git Checkout / Snapshot 롤백 구축
Ignoring Rate Limits & Costs (비용 방치): 무한 루프 탐색으로 결제 폭탄 ➔ 최대 반복 횟수(Max Iterations) 억제

PART 6. 직군별 하네스 활용 가이드

PM / 기획자: 요구사항 명세서(PRD.md)를 하네스 Inform 문서로 변환하여 에이전트 기능 구현 검증
디자이너: 디자인 시스템 토큰(컬러, 폰트, 간격)을 Constrain 규칙으로 부여하여 UI 일관성 유지
마케터 / 콘텐츠 크리에이터: SEO 규칙 및 마크다운 분량 제약을 하네스로 설정하여 고품질 콘텐츠 자동 생성
시니어 개발자: 아키텍처 가이드라인 및 보안 정책을 AGENTS.md에 정의하여 주니어/AI 작업물 품질 상향 평준화

하네스 엔지니어링 완전 정복 [2부: 실전 설계, 플랫폼 비교 & EDD]