**하네스 엔지니어링(Harness Engineering)**은 AI 에이전트를 감싸는 환경, 도구체인, 안전 제약, 피드백 루프 전체를 설계하는 엔지니어링 실천법이다.
💬 하네스는 AI 에이전트를 둘러싼 스캐폴딩(scaffolding), 제약(constraints), 피드백 루프(feedback loops)의 전체 환경이다. 에이전트가 사용할 수 있는 도구, 부여된 권한, 유지되는 상태, 통과해야 하는 테스트, 수집되는 로그, 시스템이 표류하지 않도록 막는 재시도·체크포인트·가드레일·리뷰·평가가 모두 포함된다.
2026년 3월 31일, Anthropic이 npm 업데이트 패키지에 실수로 Claude Code의 전체 소스코드(TypeScript 512,000줄 이상, 약 2,000개 파일)를 포함하여 배포하는 사고가 발생했다. 버전 2.1.88의 npm 패키지에 소스맵 파일(*.map)이 포함된 것이 원인이었다.
이 유출 사건은 AI 제품의 경쟁력이 모델보다 하네스에서 나온다는 사실을 업계에 각인시키며 "하네스 엔지니어링"이라는 개념을 급속히 확산시켰다.
Claude Code는 2025년 5월 공개 출시 후 6개월 만인 2025년 11월에 연간 **10억 달러(ARR)**를 돌파했는데, 그 비결은 더 나은 프롬프트가 아니라 스트리밍 에이전트 루프, 권한 제어 도구 디스패치 시스템, 긴 세션에 걸쳐 모델의 집중력을 유지하는 컨텍스트 관리 레이어라는 올바른 하네스 구축에 있었다.
[2022~2023] [2024~2025] [2026~]
프롬프트 엔지니어링 → 컨텍스트 엔지니어링 → 하네스 엔지니어링
"무엇을 말하는가" "무엇을 보내는가" "어떻게 작동하는가"| 세대 | 핵심 질문 | 주요 기법 |
|---|---|---|
| 🗣️ 프롬프트 엔지니어링 | 모델에게 무엇을 말하는가? | Few-shot, Chain-of-Thought, Role prompting |
| 📦 컨텍스트 엔지니어링 | 모델에게 무엇을 보내는가? | RAG, 메모리 시스템, 문서 주입 |
| 🔩 하네스 엔지니어링 | 시스템이 어떻게 작동하는가? | Hooks, 권한 제어, 도구 체인, 피드백 루프 |
💡 하네스 엔지니어링은 컨텍스트 엔지니어링을 포함하고, 컨텍스트 엔지니어링은 프롬프트 엔지니어링을 포함한다. 각 레이어는 이전 레이어를 없애는 것이 아니라 범위를 확장한다.
하네스 엔지니어링의 가장 핵심적인 공식:
Agent = Model + Harness**하네스(Harness)**는 모델 자체를 제외한 에이전트를 구성하는 모든 것이다.
🎯 동일한 모델이라도 하네스 설계에 따라 결과물의 품질과 신뢰성이 극적으로 달라진다. OpenAI의 내부 실험에서 에이전트 주변 환경을 올바르게 구조화했을 때, 수동으로 작성된 코드 없이 AI가 약 100만 줄의 프로덕션 소프트웨어를 생성하는 결과를 얻었다.
마틴 파울러(Martin Fowler)는 하네스의 두 가지 핵심 제어 메커니즘을 정의했다.
에이전트가 행동하기 전에 방향을 잡아주는 제어 장치.
에이전트가 행동한 후에 관찰하고 자기 수정을 돕는 장치.
| 유형 | 특성 | 예시 |
|---|---|---|
| ⚡ Computational (계산형) | 결정론적, 빠름, 저렴 | 린터, 테스트 러너, 정규식 검사 |
| 🤖 Inferential (추론형) | AI 기반, 의미론적 검토, 느림 | LLM 기반 코드 리뷰 훅, Agent 훅 |
실무에서 하네스를 설계할 때 유용한 또 다른 프레임워크다.
| 영역 | 역할 | 구성 요소 |
|---|---|---|
| 🎛️ Control (제약 정의) | 에이전트의 행동 범위를 결정 | CLAUDE.md, 린터, 테스트, 코드 리뷰 |
| 🤝 Agency (도구·인터페이스) | 에이전트가 할 수 있는 일을 확장 | MCP 서버, 서브에이전트, 외부 API |
| 🔄 Runtime (실행·복구) | 안정적 실행과 오류 복구를 담당 | Hooks, 재시도 로직, 롤백, 체크포인트 |
Claude Code는 사용자가 하네스를 구성할 수 있는 5가지 레이어를 제공한다.
┌──────────────────────────────────────────────┐
│ Claude Code Harness │
│ │
│ ① CLAUDE.md / Rules ← 가이드 (사전 제어) │
│ ② Skills ← 모듈형 지침 │
│ ③ Hooks ← 센서 (사후 제어) │
│ ④ MCP 서버 ← 에이전시 확장 │
│ ⑤ Sub-agents ← 태스크 위임 │
│ │
│ [Claude Model] │
└──────────────────────────────────────────────┘세션마다 자동으로 로드되는 에이전트의 영구 메모리이자 가이드다.
~/.claude/CLAUDE.md # 전역 규칙 (모든 프로젝트 적용)
~/.claude/rules/ # 전역 규칙 파일들
프로젝트/.claude/CLAUDE.md # 프로젝트별 규칙효과적인 CLAUDE.md 작성 전략:
# 프로젝트 컨벤션
- 언어: TypeScript strict mode
- 테스트: Jest, 커버리지 80% 이상 유지
- 커밋: Conventional Commits 형식 준수
# 금지 사항
- console.log 직접 사용 금지 (logger 유틸리티 사용)
- any 타입 사용 금지
- 테스트 없이 비즈니스 로직 수정 금지
# 아키텍처 원칙
- 계층: Controller → Service → Repository
- 사이드 이펙트는 반드시 Service 계층에서 처리💡 팁: 규칙은 에이전트가 처음부터 올바른 방향으로 행동하도록 사전에 방향을 잡아주는 가이드 역할을 한다. 구체적이고 명확할수록 효과적이다.
CLAUDE.md를 분할한 모듈형 지침 조각이다. 태스크가 매칭될 때만 로드되어 컨텍스트 윈도우를 효율적으로 사용할 수 있다.
~/.claude/skills/
├── testing.md # 테스트 작성 시에만 로드
├── git-commit.md # 커밋 시에만 로드
├── review.md # 코드 리뷰 시에만 로드
└── deploy.md # 배포 작업 시에만 로드✅ 장점: 거대한 CLAUDE.md 하나를 매번 전체 로드하는 대신, 필요한 지침만 선택적으로 불러와 컨텍스트 윈도우를 아낄 수 있다.
Claude Code 라이프사이클의 특정 시점에 자동 실행되는 사용자 정의 스크립트다. 가장 강력한 센서(Sensor) 메커니즘이다.
훅 이벤트 유형:
| 이벤트 | 발생 시점 |
|---|---|
PreToolUse | 도구 실행 직전 |
PostToolUse | 도구 실행 직후 |
Stop | 에이전트 응답 완료 후 |
SessionStart | 세션 시작 시 |
훅 핸들러의 4가지 종류:
| 종류 | 특성 | 활용 사례 |
|---|---|---|
command | 셸 명령어 실행 | 린터, 테스트, 포매터 |
http | HTTP POST 전송 | 외부 서비스 알림, 로깅 |
prompt | Claude 모델로 평가 | AI 기반 코드 품질 검토 |
agent | 서브에이전트 생성 | Read/Grep/Glob으로 복잡한 검증 |
실전 훅 설정 예시 (~/.claude/settings.json):
{
"hooks": {
"PostToolUse": [
{
"matcher": "Edit|Write",
"hooks": [
{
"type": "command",
"command": "npm run lint --fix"
}
]
}
],
"Stop": [
{
"hooks": [
{
"type": "command",
"command": "npm test -- --passWithNoTests"
}
]
}
]
}
}⚠️ 주의: 훅이 생성하는 에러 메시지는 단순한 오류 코드가 아니라, 에이전트가 자기 수정에 사용할 수 있는 구체적인 지침을 포함해야 한다. 그래야 에이전트가 스스로 문제를 교정할 수 있다.
좋은 훅 피드백 메시지 예시:
# ❌ 나쁜 예
echo "Error: lint failed"
exit 1
# ✅ 좋은 예
echo "ESLint 오류: 'any' 타입 사용이 금지되어 있습니다.
해결 방법: 구체적인 타입을 명시하거나, unknown을 사용하세요.
관련 파일: src/utils/parser.ts:42"
exit 1에이전트의 도구 세트를 외부 시스템으로 확장하는 연결 레이어다. MCP 서버를 활용하면 Claude Code가 단순한 코딩 도우미를 넘어 전체 개발 워크플로우를 자율 처리하는 에이전트가 된다.
Claude Code
│
├─→ GitHub MCP # PR 생성, 이슈 관리
├─→ Jira MCP # 티켓 읽기/업데이트
├─→ Slack MCP # 팀 알림
└─→ Database MCP # 쿼리 실행💡 통합 워크플로우 예시: Jira 티켓 읽기 → 코드 구현 → GitHub PR 생성 → 티켓 상태 업데이트 → Slack 알림까지 단일 명령으로 처리할 수 있다.
특정 태스크를 위임받아 독립적으로 실행하는 격리된 Claude 인스턴스다.
긴 작업에서 단일 컨텍스트 윈도우를 초과하는 문제를 해결하기 위해 Anthropic이 개발한 멀티에이전트 패턴이다.
① Planning Agent → 태스크 분해, 우선순위 결정
↓
② Generation Agent → 실제 구현
↓
③ Evaluation Agent → 품질 검증, 피드백 생성💡 핵심: 각 세션 종료 시 다음 세션을 위한 명확한 아티팩트(진행 상황, 결정 사항, 다음 단계)를 생성해야 한다. 새 세션은 이전 세션의 메모리가 없기 때문이다.
복잡한 멀티에이전트 시스템을 처음부터 구축하지 말고, 단일 에이전트 + 훅 + 규칙 파일부터 시작하라.
Phase 1: CLAUDE.md 작성 (기본 가이드)
↓
Phase 2: 핵심 훅 추가 (린터, 테스트)
↓
Phase 3: 스킬로 모듈화
↓
Phase 4: MCP 서버로 외부 연동
↓
Phase 5: 필요시 멀티에이전트 아키텍처 고려하네스의 모든 컴포넌트는 "모델이 스스로 할 수 없는 것"에 대한 가정을 담고 있다. 모델이 발전하면 하네스도 단순화된다. 정기적으로 각 컴포넌트가 여전히 필요한지 검토하라.
| 레이어 | 책임 |
|---|---|
| 📄 Rules/CLAUDE.md | "무엇을 해야 하는가" (지식, 제약) |
| 🧩 Skills | "어떻게 해야 하는가" (절차, 패턴) |
| 🪝 Hooks | "제대로 했는가" (검증, 피드백) |
| 🔌 MCP | "무엇을 할 수 있는가" (도구, 권한) |
~/.claude/CLAUDE.md — 전역 규칙 작성 (코딩 스타일, 금지 사항).claude/CLAUDE.md — 프로젝트별 컨벤션 작성PostToolUse 훅 — Edit/Write 후 린터 자동 실행Stop 훅 — 세션 종료 전 테스트 자동 실행