Claude Code를 위한 하네스 엔지니어링 설정입니다.
프롬프트 엔지니어링을 넘어, AI 에이전트의 전체 운영 환경(도구, 피드백 루프, 수명주기, 안전 게이트, 오케스트레이션)을 설계합니다.
| 단계 | 시기 | 초점 |
|---|---|---|
| 프롬프트 엔지니어링 | 2022-2024 | 단일 입력 최적화 |
| 컨텍스트 엔지니어링 | 2025 | 동적 컨텍스트 구성 |
| 하네스 엔지니어링 | 2026~ | 시스템 전체 운영 설계 |
모델 성능이 상향 평준화되면서, 차별화는 모델이 아니라 모델을 둘러싼 시스템에서 나옵니다.
┌─────────────────────────────────────────────────┐
│ Main Agent (Opus) │
│ 계획 · 판단 · 위임 · 조율 │
│ │
│ ┌─────────┐ ┌──────────┐ ┌──────────┐ │
│ │Reflexion│ │ 백프레셔 │ │ 다중경로 │ │
│ │ Loop │ │ 원칙 │ │ 탐색 │ │
│ └────┬────┘ └─────┬────┘ └────┬─────┘ │
│ │ │ │ │
│ ┌────▼────────────▼───────────▼─────┐ │
│ │ 서브에이전트 오케스트레이션 │ │
│ └────┬────┬────┬────┬────┬──────────┘ │
└───────┼────┼────┼────┼────┼──────────────────────┘
│ │ │ │ │
┌────▼┐┌─▼──┐┌▼───┐┌▼──┐┌▼────────┐
│auto ││code││inst││res││evaluator│
│-dev ││-rev││all ││ear││(반성 │
│ ││iew ││er ││ch ││ 평가자) │
└─────┘└────┘└────┘└───┘└─────────┘
Sonnet Sonnet Sonnet Sonnet Sonnet
이전 (v1): CLAUDE.md 205줄에 모든 규칙을 flat하게 작성 → 길수록 무시될 확률 증가
이후 (v2): CLAUDE.md 68줄 핵심만 + rules/ 4개 파일로 분리
- Anthropic 공식 권장: CLAUDE.md는 200줄 이내,
IMPORTANT/YOU MUST강조 표현 사용 - 상세 규칙은
@~/.claude/rules/파일.md로 import하여 관리
이전: CLAUDE.md의 모든 규칙이 "부탁" 수준 (80% 준수율)
이후: 반드시 실행되어야 하는 규칙을 hooks로 100% 강제
| Hook | 이벤트 | 역할 |
|---|---|---|
session-init.sh |
SessionStart | 세션 시작 프로토콜 강제 주입 |
stop-verify.sh |
Stop | 코드 변경 시 테스트 통과 전 종료 차단 |
post-edit-lint.sh |
PostToolUse | Write/Edit 후 자동 린트 실행 |
Anthropic 공식 원칙: "CLAUDE.md는 어드바이저리, hooks는 결정론적. 반드시 실행되어야 하는 것은 hooks로."
| 에이전트 | 역할 | 도구 | 특징 |
|---|---|---|---|
| auto-dev | 코드 구현, 리팩토링, 버그 수정 | Read, Write, Edit, Bash, Glob, Grep | TDD + Reflexion 내장, 최대 50턴 |
| code-reviewer | 코드 리뷰, 보안/품질 점검 | Read, Glob, Grep (읽기 전용) | 코드 수정 권한 없음 |
| installer | 패키지 설치, MCP 등록, 환경 설정 | Read, Write, Bash, Glob, Grep | 설치 후 자동 검증 |
| researcher | 기술 조사, 아키텍처 분석 | Read, Glob, Grep, WebSearch, WebFetch | 외부 조사 가능 |
| evaluator | 에이전트 출력 평가, 반성 피드백 | Read, Glob, Grep (읽기 전용) | Reflexion 평가자 |
프롬프트 기반으로 강화학습과 유사한 자기개선을 달성합니다.
[행동 수행] → [결과 평가] → [실패 시 반성] → [메모리 저장] → [다음 시도에 반영]
↑__________________________________________________|
- 실패 시: 근본 원인 분석 →
reflexion-log.md에 기록 → 전략 변경 후 재시도 - 성공 시: 비자명한 패턴이면 feedback 메모리에 기록
- evaluator 에이전트가 다차원 평가(정확성/테스트/코드/부작용/효율성) 수행
"성공은 침묵, 실패만 상세"
- 성공 시: 변경 파일 목록 + 한 줄 요약 (최대 5줄)
- 실패 시: 에러 내용 + 반성 분석 + 다음 전략을 상세히 반환
- 서브에이전트 = 컨텍스트 방화벽: 독립 컨텍스트에서 처리, 압축 요약만 반환
복잡한 문제에서 단일 경로 대신 복수 접근법을 시도합니다.
- 트리거: 2회 연속 같은 유형 실패 / 아키텍처 결정 필요
- 방법: worktree 격리 환경에서 2-3개 접근법 병렬 실행
- 선택: evaluator 평가 → 최적 경로 채택, 나머지 폐기
모든 코드 변경은 반드시 이 순서를 따릅니다:
실패 테스트 작성 → 실패 확인 → 실패 테스트 커밋 → 코드 구현 → 테스트 통과 → 구현 커밋
매 세션 시작 시 SessionStart hook이 강제 주입:
환경 확인 → git 히스토리 → 메모리 로드 → 진행 상태 파악 → 기준선 테스트
claude-harness/
├── CLAUDE.md # 전역 하네스 핵심 원칙 (~68줄)
├── settings.json # hooks (강제 실행) + permissions
├── agents/
│ ├── auto-dev.md # 풀스택 개발 에이전트 (Reflexion 내장)
│ ├── code-reviewer.md # 읽기 전용 코드 리뷰 에이전트
│ ├── evaluator.md # Reflexion 평가 에이전트
│ ├── installer.md # 환경 설정/패키지 설치 에이전트
│ └── researcher.md # 기술 조사/분석 에이전트
├── rules/
│ ├── tdd-process.md # TDD 4단계 상세 규칙
│ ├── commit-rules.md # 커밋 메시지 규칙
│ ├── agent-orchestration.md # 병렬 작업/다중 경로 규칙
│ └── code-quality.md # 코드 품질/패키지/MCP 규칙
├── hooks/
│ ├── session-init.sh # 세션 시작 프로토콜 강제
│ ├── stop-verify.sh # 테스트 통과 전 종료 차단
│ └── post-edit-lint.sh # 파일 수정 후 자동 린트
└── README.md
| 조건 | 사용할 것 |
|---|---|
| 매번 예외 없이 실행되어야 함 | hooks/ |
| 모든 세션에 적용되는 핵심 원칙 | CLAUDE.md |
| 주제별 상세 규칙 | rules/ |
| 격리된 특화 작업 | agents/ |
~/.claude/ 디렉토리에 파일을 배치합니다:
# 클론
git clone https://github.com/susia101/claude-harness.git
# 복사
cp claude-harness/CLAUDE.md ~/.claude/CLAUDE.md
cp claude-harness/settings.json ~/.claude/settings.json
cp -r claude-harness/agents/ ~/.claude/agents/
cp -r claude-harness/rules/ ~/.claude/rules/
cp -r claude-harness/hooks/ ~/.claude/hooks/
# hooks 실행 권한 부여
chmod +x ~/.claude/hooks/*.sh주의:
settings.json에 프로젝트별 설정(MCP 서버, 플러그인 등)이 있다면 병합하세요. 덮어쓰면 기존 설정이 사라집니다.
전체 하네스 설정의 정적 토큰 비용:
| 구성 요소 | 토큰 |
|---|---|
| CLAUDE.md (핵심) | ~1,200 |
| rules/ (4개 파일) | ~2,000 |
| auto-dev | ~2,000 |
| evaluator | ~1,100 |
| code-reviewer | ~630 |
| installer | ~750 |
| researcher | ~680 |
| 총합 | ~8,360 |
Claude Code 1M 컨텍스트의 0.8% 만 사용합니다. v2에서 CLAUDE.md를 슬림화했지만, rules 파일이 @import로 로드되므로 총 토큰은 동일합니다. Reflexion에 의한 재시도 감소와 백프레셔에 의한 불필요 출력 제거로 실행 시 토큰은 오히려 절약됩니다.
- Effective Harnesses for Long-Running Agents — Anthropic
- Harness Engineering — OpenAI
- Claude Code Hooks Reference
- Claude Code Memory & CLAUDE.md
- Claude Code Best Practices
- Claude Code Custom Subagents
- Building AI Coding Agents for the Terminal (arxiv)
- Reflexion: Language Agents with Verbal Reinforcement Learning (arxiv)
- DeepSeek-R1: Incentivizing Reasoning via RL (arxiv)
MIT