Claude Code 공식 개발가이드

Source: raw/articles/claude_code_harness_guide.md (code.claude.com 공식 문서 집약, 2026-04 기준) Type: local aggregate (URL 목록 포함 수동 작성) Valid as of: 2026-04-20

핵심 Takeaway

• Claude Code 하네스 = CLAUDE.md + Skills + Subagents + Hooks + MCP + Agent Teams — 각각 에이전틱 루프의 서로 다른 지점에 삽입 (출처: §1 기능 전체 구조)
• CLAUDE.md는 200줄 이하 유지. 인간 작성 ~4% 향상, LLM 생성 → 성능 악화 + 비용 20% 증가 (출처: §8.3 ETH Zurich 연구)
• Skills: 사용될 때만 로드 → 장문 레퍼런스를 컨텍스트 비용 없이 보유 가능 (출처: §3.1)
• Subagents: 컨텍스트 방화벽 역할 — 대규모 탐색 결과를 요약만 반환 (출처: §4.1)
• Hooks: 5개 이벤트(PreToolUse/PostToolUse/Notification/Stop/PreCompact), exit code로 차단(2)/피드백(1)/성공(0) 제어 (출처: §5.2-5.5)
• 4단계 하네스 구축 순서: CLAUDE.md+PostToolUse → Skills → PreToolUse+MCP → Subagents+Agent Teams (출처: §9)

상세 요약

기능 도입 순서 (권장)

CLAUDE.md (같은 실수 2번 반복 시)
  → Skill (CLAUDE.md가 절차로 커질 때)
    → Hook (Claude가 매번 수동으로 실행하는 게 있을 때)
      → MCP (외부 서비스 접근 필요 시)
        → Subagent (탐색 결과가 메인 컨텍스트 오염 시)
          → Agent Teams (병렬 독립 세션 필요 시)

4단계 하네스 구축 패턴

Phase	구성	목적
1 기초	CLAUDE.md + PostToolUse Hook	컨벤션 + 자동 lint/test
2 피드포워드 강화	+ Skills + .claude/rules/	재사용 지식·절차 분리
3 피드백 루프 강화	+ PreToolUse + Stop Hook + MCP	위험 작업 차단 + 외부 연동
4 오케스트레이션	+ Custom Subagents + Agent Teams	컨텍스트 격리·병렬 처리

Hooks exit code 의미

exit code	동작
0	성공, 계속 진행
1	에러 — Claude에게 stdout/stderr 피드백으로 전달
2	즉시 차단 (작업 중단, 인간 확인 필요)

연결되는 위키 페이지

• claude-code — 이 가이드의 주체
• harness-engineering — 4단계 구축 패턴 매핑
• guides-sensors — Hooks = Sensor 구현, Skills = Guide 구현
• keep-quality-left — PostToolUse/Stop Hook 설계 원칙