What Is a Harness? The 98.4% Principle
하네스란 무엇인가 — 98.4% 원칙
AI 에이전트 성능의 98.4%는 모델이 아니라 그 주변을 감싸는 하네스 인프라가 결정한다.
Overview
AI 코딩 에이전트를 처음 쓰기 시작한 사람들이 하는 가장 큰 실수는 '어떤 모델을 쓰느냐'에 집착하는 것이다. GPT-4o를 쓰느냐 Claude를 쓰느냐보다 훨씬 더 중요한 것이 있다. 바로 하네스(harness) — 모델이 작동하는 환경 전체를 어떻게 설계했느냐다.
2026년 3월, Claude Code의 소스코드가 npm sourcemap을 통해 유출되었다. 512,000줄의 TypeScript, 1,906개의 파일을 분석한 학술 논문(arXiv:2604.14228)의 결론은 충격적이었다: AI 의사결정 로직은 전체 코드의 1.6%에 불과하고, 나머지 98.4%는 하네스 인프라다. 도구 관리, 권한 체크, 컨텍스트 조립, 메모리, 훅 — 이 모든 것이 하네스다.
더 강력한 증거가 있다. LangChain은 2026년 Terminal Bench 2.0에서 모델을 전혀 바꾸지 않고, 오직 하네스 3가지를 개선하는 것만으로 순위를 30위에서 5위로 올렸다. 52.8%에서 66.5%로, +13.7포인트. Morph와 MindStudio의 독립 연구에서도 동일한 패턴이 나타났다: 하네스 교체 = 17-24포인트 이동, 모델 교체 = 약 1포인트 이동.
이 코스는 하네스 엔지니어링을 처음부터 끝까지 다룬다. Claude Code의 내부 아키텍처부터 즉시 적용 가능한 실전 설정까지.
- 하네스(harness)와 모델(model)의 차이를 명확히 설명할 수 있다
- AI 에이전트의 5대 필수 구성요소를 열거하고 각각의 역할을 설명할 수 있다
- 왜 하네스 개선이 모델 업그레이드보다 ROI가 높은지 근거로 설명할 수 있다
- 자신의 현재 하네스 레이어 완성도를 5단계로 자가진단할 수 있다
Sections
하네스의 정의 — 모델과 현실 세계 사이의 모든 것
하네스(Harness) = AI 에이전트에서 언어 모델과 현실 세계 사이의 모든 것. 모델 자체가 아니라, 그 모델이 실행되는 전체 환경.
Firecrawl의 2026년 정의에 따르면 하네스는 5가지 필수 요소로 구성된다:
| 구성요소 | 역할 | Claude Code에서 |
|---|---|---|
| Agent Loop | think → act → observe 사이클 | queryLoop() 함수 |
| Tool Interface | 외부 시스템 접근 방법 | 54개 도구 + MCP |
| Context Management | 컨텍스트 창에 들어가는 정보 제어 | CLAUDE.md + 압축 파이프라인 |
| Control Mechanisms | 훅, 권한, 가드레일 | Hooks + Permission 시스템 |
| State Persistence | 세션 간 메모리 | MEMORY.md + JSONL 트랜스크립트 |
이 5가지 중 하나라도 부실하면 나머지가 아무리 좋아도 에이전트는 신뢰할 수 없다. 예를 들어, 아무리 좋은 CLAUDE.md를 써도 Control Mechanisms(훅)이 없으면 에이전트가 그 규칙을 '무시'할 수 있다. 지시(instruction)는 확률적이지만, 훅은 결정론적이다.
The 98.4% Principle — Claude Code 유출본 분석
2026년 3월 31일, Claude Code v2.1.88의 소스코드가 npm sourcemap 노출로 유출되었다. VentureBeat, Zscaler 등 8개 이상의 독립 소스가 진위를 확인했다. 학술 논문 arXiv:2604.14228은 이를 체계적으로 분석했다.
핵심 발견: 512,000줄 TypeScript 중 AI 의사결정 로직은 단 1.6%. 나머지 98.4%는:
- 스트리밍 실행 엔진
- 7개 독립 안전 레이어
- 5단계 컨텍스트 압축 파이프라인
- 23개 bash 보안 체크
- 앱 UI 렌더링
- 세션 영속성
이것이 하네스 엔지니어링의 핵심 명제다. 당신이 가진 Claude Sonnet은 Anthropic이 쓰는 Claude Sonnet과 동일한 모델이다. 차이는 하네스에서 나온다.
5개 레이어로 본 하네스 완성도 진단
실무에서 모든 하네스 가이드는 같은 5개 레이어로 수렴한다. 자신의 현재 설정을 아래 기준으로 점검해보자.
| 레이어 | 내용 | 진단 기준 |
|---|---|---|
| 1. Memory | CLAUDE.md, MEMORY.md, .claude/commands/ | 전역 CLAUDE.md가 50줄 이내로 존재하는가? |
| 2. Tools | MCP 서버 | filesystem, git 서버가 설정되어 있는가? |
| 3. Permissions | allow/deny 규칙 | 위험 명령어 deny 규칙이 있는가? |
| 4. Hooks | PreToolUse, PostToolUse | 최소 1개 이상의 PreToolUse 블로킹 훅이 있는가? |
| 5. Observability | 감사 로그, JSONL 트레이스 | 도구 호출 로그가 저장되는가? |
1/5 = 일반 개발자 수준. 4-5/5 = 프로덕션 레디.
대부분의 개발자는 Layer 1(CLAUDE.md 없거나 너무 긺)에서 걸린다. 가장 빠른 개선: 전역 ~/.claude/CLAUDE.md 50줄 이내 작성 → 즉각적인 효과.
왜 하네스가 모델보다 ROI가 높은가
직관에 반하는 사실: 더 비싼 모델로 업그레이드하는 것보다 하네스를 개선하는 것이 더 큰 효과를 낸다.
LangChain Terminal Bench 2.0 (2026):
- 모델 변경 없음
- 하네스 3가지 개선: LocalContextMiddleware, PreCompletionChecklistMiddleware, LoopDetectionMiddleware
- 결과: 30위 → 5위, 52.8% → 66.5% (+13.7%p)
Morph/MindStudio 독립 연구:
- 모델 교체 효과: ~1%p 이동
- 하네스 교체 효과: 17-24%p 이동
The Constraint Paradox (LangChain 발견):
- 최대 추론 예산 적용: 53.9% 성능
- 높은 제약(constraints) 적용: 63.6% 성능
- 더 많은 컴퓨팅이 아니라 더 나은 제약이 답이다
이는 '프롬프트를 잘 써야 한다'는 통념도 부분적으로 바꾼다. Karpathy의 2025년 발언: "사람들은 프롬프트를 짧은 태스크 설명으로 생각한다... 실제로 모든 산업용 LLM 앱에서, 컨텍스트 창을 올바른 정보로 채우는 것이 핵심 기술이다."
AI 모델을 F1 레이싱카 엔진이라고 생각해보자. GPT-4o는 페라리 엔진, Claude는 메르세데스 엔진. 둘 다 최고 성능의 엔진이다.
하지만 레이스에서 이기는 것은 엔진만으로 결정되지 않는다. 피트 크루, 전략 팀, 타이어 선택, 연료 계획, 서킷 분석, 드라이버 지시 — 이 모든 것이 하네스다. 같은 메르세데스 엔진을 달아도 피트 크루가 엉터리면 진다.
하네스 엔지니어링이란 바로 이 피트 크루 전체를 설계하는 일이다. CLAUDE.md는 드라이버에게 주는 지시서, 훅은 자동화된 피트 스톱 프로세스, MCP 서버는 서킷 정보 도구, 권한 시스템은 위험 구간 속도 제한이다.
같은 모델을 쓰는 두 팀이 있을 때, 하네스가 정교한 팀이 반드시 이긴다. Terminal Bench 2.0에서 LangChain이 증명했다.
자신의 현재 하네스 상태를 진단하는 감사 스크립트. 실행하면 5개 레이어 완성도를 즉시 파악할 수 있다.
#!/usr/bin/env bash
# harness-audit.sh — 현재 하네스 완성도 진단
echo "=== HARNESS AUDIT ==="
score=0
# Layer 1: Memory
if [ -f "$HOME/.claude/CLAUDE.md" ]; then
lines=$(wc -l < "$HOME/.claude/CLAUDE.md")
if [ "$lines" -le 200 ]; then
echo "✅ Layer 1: Global CLAUDE.md exists ($lines lines)"
((score++))
else
echo "⚠️ Layer 1: CLAUDE.md too long ($lines lines — target <200)"
fi
else
echo "❌ Layer 1: No global CLAUDE.md (~/.claude/CLAUDE.md)"
fi
# Layer 2: Tools (MCP)
mcp_count=$(cat ~/.claude/settings.json 2>/dev/null | \
python3 -c "import json,sys; d=json.load(sys.stdin); print(len(d.get('mcpServers',{})))" 2>/dev/null || echo 0)
if [ "$mcp_count" -gt 0 ]; then
echo "✅ Layer 2: $mcp_count MCP server(s) configured"
((score++))
else
echo "❌ Layer 2: No MCP servers configured"
fi
# Layer 3: Permissions
deny_count=$(cat ~/.claude/settings.json 2>/dev/null | \
python3 -c "import json,sys; d=json.load(sys.stdin); print(len(d.get('permissions',{}).get('deny',[])))" 2>/dev/null || echo 0)
if [ "$deny_count" -gt 0 ]; then
echo "✅ Layer 3: $deny_count deny rule(s) configured"
((score++))
else
echo "❌ Layer 3: No deny rules in permissions"
fi
# Layer 4: Hooks
hook_count=$(cat ~/.claude/settings.json 2>/dev/null | \
python3 -c "import json,sys; d=json.load(sys.stdin); print(len(d.get('hooks',{})))" 2>/dev/null || echo 0)
if [ "$hook_count" -gt 0 ]; then
echo "✅ Layer 4: $hook_count hook event(s) configured"
((score++))
else
echo "❌ Layer 4: No hooks configured"
fi
# Layer 5: Observability
if ls ~/.claude/projects/*/memory/MEMORY.md 2>/dev/null | head -1 | grep -q .; then
echo "✅ Layer 5: Memory files found"
((score++))
else
echo "❌ Layer 5: No MEMORY.md files in any project"
fi
echo ""
echo "Score: $score/5"
[ $score -le 1 ] && echo "Level: 일반 개발자 — 즉시 Layer 1부터 시작하세요"
[ $score -eq 2 ] && echo "Level: 입문 — Layer 2, 4가 핵심입니다"
[ $score -eq 3 ] && echo "Level: 중급 — 거의 다 왔습니다"
[ $score -ge 4 ] && echo "Level: 프로덕션 레디 — 지속적 개선 단계" 각 레이어를 순서대로 체크하고 0-5점 점수를 낸다. 이 스크립트를 ~/.claude/hooks/audit.sh에 저장하고 필요할 때마다 실행하자. Layer 1과 4가 가장 빠른 효과를 낸다.
✅ 시니어가 보는 것
- 전역 CLAUDE.md가 있고 50-200줄 이내로 관리되고 있는가
- PreToolUse 블로킹 훅으로 위험 명령어를 차단하고 있는가
- MCP 서버로 에이전트의 도구 범위를 확장했는가
- 하네스 설정이 버전 관리(git)되어 팀 전체에 공유되는가
⚠️ 레드 플래그
- CLAUDE.md가 없거나 1,000줄 이상 (지침이 무의미해짐)
- exit 1을 쓰는 훅 (Claude Code는 exit 2만 블로킹)
- bypassPermissions를 컨테이너 없이 사용
- 하네스 설정이 한 컴퓨터에만 있고 이식 불가
🎤 예상 인터뷰 질문
- LangChain이 모델 교체 없이 Terminal Bench에서 30위에서 5위로 올라간 방법은?
- Claude Code에서 PreToolUse 훅의 exit code 0, 1, 2의 차이는?
- CLAUDE.md와 permissions.deny의 근본적 차이는? 왜 둘 다 필요한가?
Key Takeaways
98.4% 원칙
Claude Code 소스의 98.4%는 하네스 인프라고 1.6%만 AI 로직이다. 성능 개선의 여지도 그만큼 하네스에 있다.
하네스 5대 요소
Agent Loop, Tool Interface, Context Management, Control Mechanisms, State Persistence — 5개 모두 갖춰야 신뢰할 수 있는 에이전트다.
하네스 > 모델 업그레이드
LangChain: 하네스 개선 +13.7%p, 모델 교체 ~1%p. ROI는 하네스 쪽이 압도적이다.
지시는 확률적, 훅은 결정론적
CLAUDE.md 규칙은 모델이 '무시'할 수 있다. exit 2 PreToolUse 훅은 시스템이 보장한다.
The Constraint Paradox
제약이 많을수록 성능이 올라간다. 최대 추론 예산(53.9%) vs 높은 제약(63.6%) — 더 많은 컴퓨팅이 답이 아니다.
5-Layer 자가진단
Memory, Tools, Permissions, Hooks, Observability — 4/5 이상이 프로덕션 레디 기준이다.
즉시 시작점
오늘 당장 할 것: ~/.claude/CLAUDE.md 50줄 이내로 작성. 가장 빠른 ROI의 첫 단계다.
하네스는 팀 자산
개인 하네스가 아니라 git에 커밋된 팀 하네스가 진짜 자산이다. 한 번 만들면 팀 전체가 혜택을 누린다.