GitHub ↗
CHAPTER 01 OF 10
🏗️

What Is a Harness? The 98.4% Principle

하네스란 무엇인가 — 98.4% 원칙

AI 에이전트 성능의 98.4%는 모델이 아니라 그 주변을 감싸는 하네스 인프라가 결정한다.

What Is a Harness? The 98.4% Principle cheatsheet
🍌 NANO BANANA CHEATSHEET · CH 01

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의 내부 아키텍처부터 즉시 적용 가능한 실전 설정까지.

🎯 Learning Goals
  • 하네스(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 앱에서, 컨텍스트 창을 올바른 정보로 채우는 것이 핵심 기술이다."

💡 Analogy · 비유
레이싱카 비유 — F1 드라이버 vs. 피트 크루

AI 모델을 F1 레이싱카 엔진이라고 생각해보자. GPT-4o는 페라리 엔진, Claude는 메르세데스 엔진. 둘 다 최고 성능의 엔진이다.

하지만 레이스에서 이기는 것은 엔진만으로 결정되지 않는다. 피트 크루, 전략 팀, 타이어 선택, 연료 계획, 서킷 분석, 드라이버 지시 — 이 모든 것이 하네스다. 같은 메르세데스 엔진을 달아도 피트 크루가 엉터리면 진다.

하네스 엔지니어링이란 바로 이 피트 크루 전체를 설계하는 일이다. CLAUDE.md는 드라이버에게 주는 지시서, 훅은 자동화된 피트 스톱 프로세스, MCP 서버는 서킷 정보 도구, 권한 시스템은 위험 구간 속도 제한이다.

같은 모델을 쓰는 두 팀이 있을 때, 하네스가 정교한 팀이 반드시 이긴다. Terminal Bench 2.0에서 LangChain이 증명했다.

자신의 현재 하네스 상태를 진단하는 감사 스크립트. 실행하면 5개 레이어 완성도를 즉시 파악할 수 있다.

bash
#!/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가 가장 빠른 효과를 낸다.

🏭 현업에서의 평가
시니어 엔지니어들은 신입이 AI 도구를 어떻게 쓰는지를 보고 그 사람의 시스템 사고 수준을 판단한다. 'Claude한테 그냥 물어보면 돼요'라고 말하는 사람과 'CLAUDE.md에 이렇게 설정해두면 자동으로 처리돼요'라고 말하는 사람은 완전히 다른 레벨이다.

✅ 시니어가 보는 것

  • 전역 CLAUDE.md가 있고 50-200줄 이내로 관리되고 있는가
  • PreToolUse 블로킹 훅으로 위험 명령어를 차단하고 있는가
  • MCP 서버로 에이전트의 도구 범위를 확장했는가
  • 하네스 설정이 버전 관리(git)되어 팀 전체에 공유되는가

⚠️ 레드 플래그

  • CLAUDE.md가 없거나 1,000줄 이상 (지침이 무의미해짐)
  • exit 1을 쓰는 훅 (Claude Code는 exit 2만 블로킹)
  • bypassPermissions를 컨테이너 없이 사용
  • 하네스 설정이 한 컴퓨터에만 있고 이식 불가

🎤 예상 인터뷰 질문

  1. LangChain이 모델 교체 없이 Terminal Bench에서 30위에서 5위로 올라간 방법은?
  2. Claude Code에서 PreToolUse 훅의 exit code 0, 1, 2의 차이는?
  3. CLAUDE.md와 permissions.deny의 근본적 차이는? 왜 둘 다 필요한가?
숙달 vs 익숙함: 단순히 '아는' 사람은 CLAUDE.md를 쓰고 끝낸다. 마스터한 사람은 CLAUDE.md를 50줄 이내로 유지하면서 Progressive Disclosure 패턴으로 세부 규칙을 별도 파일에 분리하고, 그 위에 훅과 권한 레이어로 결정론적 강제를 추가한다. 그리고 이 전체 설정을 git으로 버전 관리해서 팀 전체에 배포한다.

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에 커밋된 팀 하네스가 진짜 자산이다. 한 번 만들면 팀 전체가 혜택을 누린다.