ClaudeCode한테 어떻게 잘 시키지? 심화편

AI 믿지 마라 = 예측 가능한 동작 + 사용자가 제어권

---

4.1 팀 워크플로우 설계

핵심 개념

팀에서 Claude Code를 쓸 때의 문제: 업무 스타일 다름 + AI 숙련도 다름. 해결 = 도구로 통일.

팀 워크플로우 3종 세트

1 2 3

1. CLAUDE.md → 규칙 통일 (코드 스타일, 컨벤션) 2. 커스텀 커맨드 → 작업 통일 (/pr-check, /deploy-check) 3. 훅 → 자동 검사 (위험한 명령 차단, 린트)

온보딩 자동화

1 2 3 4 5

새 팀원 합류 → git clone → Claude Code 실행 → CLAUDE.md 자동 로드 ✅ → 커스텀 커맨드 바로 사용 가능 ✅ → 훅 자동 적용 ✅ → 별도 교육 불필요!

핵심 정리

1. CLAUDE.md + 커맨드 + 훅 = 팀 표준화 3종 세트
2. repo에 커밋 → clone만 하면 모든 설정 자동 적용
3. 숙련도 상관없이 같은 품질의 결과

---

4.2 CI/CD 통합

핵심 개념

CI 파이프라인에서 claude 명령어를 실행하여 자동 코드 리뷰 등 수행. 사람 없이 돌아가니까 headless 모드 필요.

headless 모드

1 2	일반 모드: claude (대화형, 사람이 승인) headless 모드: claude -p "PR 리뷰해줘" --print (비대화형, 결과만 출력)

• --print 플래그 = 질문 없이 결과만 출력하고 종료
• CI/CD에 적합

CI 보안 설정

사람이 없으니 읽기만 허용:

1 2	allow: Read, Grep, Glob ← 읽기만 deny: Write, Edit, Bash ← 수정/실행 차단

→ 코드 읽고 리뷰 코멘트만 남기고 끝

핵심 정리

1. CI에서 claude = 파이프라인에 명령어 추가
2. headless 모드 = --print, 비대화형
3. 보안 = 권한으로 읽기만 허용 → “예측 가능 + 제어권” 원칙

---

4.3 Claude Code SDK & 커스텀 에이전트

핵심 개념

SDK = 내 프로그램 안에서 Claude Code 에이전트를 부품으로 사용.

Claude API vs Claude Code SDK

1 2	Claude API: 텍스트 → 텍스트 (LLM만) Claude Code SDK: 텍스트 → 파일 읽기/수정/실행 → 결과 (에이전트)

SDK는 도구 시스템(Read, Write, Bash 등)까지 포함.

커스텀 커맨드 vs SDK 커스텀 에이전트

	커스텀 커맨드	SDK 커스텀 에이전트
실행 환경	Claude Code 터미널	내 앱, 스크립트, 서버
실행 방법	/명령어	코드로 호출
유연성	프롬프트 템플릿	로직, 조건, 루프 다 가능

• 커스텀 커맨드 = 사용자를 위한 단축키
• SDK = 개발자가 Claude Code를 부품으로 쓰는 것

핵심 정리

1. SDK = 내 프로그램에 Claude Code 에이전트 내장
2. API와 차이 = 도구 시스템 포함 (파일 읽기/수정/실행)
3. 커맨드와 차이 = 실행 환경과 유연성

---

4.4 고급 프롬프트 엔지니어링

핵심 개념

복잡한 작업은 한 번에 시키지 말고 계획 → 검토 → 실행 순서로.

복잡한 작업 패턴

1 2	❌ "인증 시스템 추가해줘" → 바로 코드 작성 (예측 불가) ✅ "먼저 계획 세워줘" → 검토 → 실행 → 제어 가능

Plan 모드 활용

1 2 3

1. Plan 모드로 계획 수립 → "이런 순서로 할게요" 2. 계획 검토/수정 → "3번은 이렇게 바꿔" 3. 승인 후 실행 → 필요하면 서브에이전트로 병렬

체이닝

큰 작업을 작은 단계로 쪼개서 순서대로 실행. = Explore → Plan → Act 루프를 사용자가 직접 제어하는 것.

핵심 정리

1. Plan 모드 = 실행 전 계획 먼저 → 예측 가능성 확보
2. 태스크 분해 = 큰 작업을 작은 단계로
3. 체이닝 = 단계별 순서 실행
4. 결국 “예측 가능 + 제어권” 원칙의 적용

---

4.5 트러블슈팅 & 한계 극복

핵심 개념

Claude가 말귀를 못 알아먹는 원인은 여러 가지. 원인별 대응이 다르다.

원인 분석

1 2 3 4

1. 🙋 프롬프트 모호 → WHCR 미준수 2. 🤖 컨텍스트 너무 김 → 핵심을 놓침 3. 📄 CLAUDE.md 충돌 → 규칙끼리 모순 4. 🔄 환각 → 없는 파일/함수를 있다고 착각

환각 단계별 대응

1 2 3

가벼운 환각 → "다시 확인해봐" 한 번 더 지시 반복 환각 → /clear로 세션 리셋 심한 환각 → /rewind로 오염 전 시점으로 복구

핵심: 오염된 세션이라 판단되면 껐다 키는 게 맞다

예방 수단

예방 수단	효과
WHCR	명확한 프롬프트 → 오해 방지
CLAUDE.md	규칙 명시 → 일관된 동작
/compact	컨텍스트 관리 → 환각 방지
Plan 모드	계획 먼저 → 엉뚱한 실행 방지

핵심 정리

1. 원인 파악이 먼저 — 내 잘못? 컨텍스트? 환각?
2. 환각 = 세션 오염 — /clear 또는 /rewind
3. 예방 > 대응 — WHCR, CLAUDE.md, /compact, Plan 모드
4. 결국 “예측 가능 + 제어권” 원칙

---

4.6 성능 최적화와 모범 사례

핵심 개념

지금까지 배운 모든 것을 하나의 생산성 시스템으로 통합.

나만의 Claude Code 생산성 시스템

1 2 3 4 5 6 7

📋 시작: Plan 모드로 계획 수립 → 검토 → 승인 ↓ 🔨 작업: 코드 작성/수정 ├── PreToolUse 훅: 위험한 명령 차단, 코드 검증 └── PostToolUse 훅: 결과 검증, 린트 ↓ 📝 끝: 자동 문서화 훅 (커밋 메시지, 변경 로그)

전체 도구 맵

단계	도구	출처
프로젝트 규칙	CLAUDE.md	1.5
권한 설정	allow/deny	1.4
계획 수립	Plan 모드	4.4
작업 검수	훅 (Pre/PostToolUse)	3.1
반복 작업	커스텀 커맨드	2.6
컨텍스트 관리	/compact, /clear	3.5
비용 관리	멀티모델 라우팅	2.8
외부 연동	MCP 서버	3.2
팀 표준화	CLAUDE.md + 커맨드 + 훅	4.1
CI/CD	headless 모드	4.2
프로그래매틱	SDK	4.3

모든 것을 관통하는 원칙

“예측 가능한 동작 + 사용자가 제어권” = AI 믿지 마라 = 검증하고, 제어하고, 확인해라

---

🏗️ 에이전틱 하네스 (Agentic Harness) 심화

하네스란 무엇인가?

하네스 = 모델을 에이전트로 만드는 모든 것

Anthropic 공식 정의: “Claude Code는 Claude를 감싸는 에이전틱 하네스(agentic harness)다. 도구, 컨텍스트 관리, 실행 환경을 제공하여 언어 모델을 유능한 코딩 에이전트로 변환한다.”

1	코딩 에이전트 = AI 모델 + 하네스

모델 자체를 제외한 모든 것이 하네스다: 설정 파일, 도구 디스패치, 권한 체계, 컨텍스트 관리, 세션 상태, 라이프사이클 훅, MCP 통합, 에러 복구.

Mitchell Hashimoto의 철학: “에이전트가 실수하면, 그 실수를 다시는 하지 않도록 엔지니어링하라.”

하네스의 6대 구성요소

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18

┌─────────────────────────────────────────────────┐ │ Agentic Harness │ │ │ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │ │ CLAUDE.md│ │ Settings │ │ Hooks │ │ │ │ (Advisory)│ │(Enforce) │ │(Determ.) │ │ │ └──────────┘ └──────────┘ └──────────┘ │ │ │ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │ │Permission│ │ Skills │ │ MCP │ │ │ │ (Safety) │ │(On-demand)│ │(External)│ │ │ └──────────┘ └──────────┘ └──────────┘ │ │ │ │ ┌─────────────┐ │ │ │ AI Model │ │ │ │ (Claude) │ │ │ └─────────────┘ │ └─────────────────────────────────────────────────┘

구성요소	성격	역할
CLAUDE.md	Advisory (조언)	지시문, 컨벤션, 프로젝트 지식. 따르려 노력함
Settings.json	Enforcement (강제)	권한 규칙, 환경변수, 도구 제한. 반드시 지켜짐
Hooks	Deterministic (결정론적)	매번 동일하게 실행. 포맷터, 검증, 자동화
Permissions	Safety (안전)	4단계 파이프라인으로 도구 호출 안전성 보장
Skills	On-demand (요청 시)	필요할 때만 로딩되는 전문 지식 패키지
MCP Servers	External (외부)	파일 I/O와 셸을 넘어선 외부 도구 연결

CLAUDE.md vs Settings vs Hooks — 핵심 차이

1 2 3

"항상 Prettier로 포맷해줘" → CLAUDE.md (조언 — 가끔 빠뜨릴 수 있음) "Prettier가 허용된 명령이다" → settings.json (강제 — 항상 적용) "파일 편집 후 자동으로 Prettier 실행" → Hook (결정론적 — 100% 실행)

핵심 원칙: 매번 반드시 일어나야 하는 것은 훅에, 가이드라인은 CLAUDE.md에, 제한은 settings에.

12가지 에이전틱 하네스 패턴

Claude Code의 아키텍처에서 추출된 12가지 핵심 패턴:

카테고리 1: 메모리와 컨텍스트

#	패턴	설명	활용
1	Persistent Instruction File	매 세션 로딩되는 지속적 설정 파일	CLAUDE.md
2	Scoped Context Assembly	여러 스코프에서 동적으로 조립되는 지시문	디렉토리별 CLAUDE.md, @import
3	Tiered Memory	3계층 메모리: 인덱스(항상) → 토픽별(필요 시) → 전체(검색 시)	컨텍스트 효율성
4	Dream Consolidation	유휴 시간에 메모리 정리/중복제거/가지치기	장기 세션 유지
5	Progressive Context Compaction	대화 나이에 따른 다단계 압축	자동/수동 compaction

카테고리 2: 워크플로우와 오케스트레이션

#	패턴	설명	활용
6	Explore-Plan-Act Loop	3단계: 탐색(읽기전용) → 계획 → 실행	Plan 모드
7	Context-Isolated Subagents	별도 컨텍스트의 격리된 에이전트	Agent 도구
8	Fork-Join Parallelism	병렬 서브에이전트 → 결과 합류	워크트리 + /batch

카테고리 3: 도구와 권한

#	패턴	설명	활용
9	Progressive Tool Expansion	기본 도구로 시작, 필요 시 확장	MCP Tool Search
10	Command Risk Classification	명령어의 동사/플래그/대상으로 위험도 분류	Bash classifier
11	Single-Purpose Tool Design	타입 검증된 단일 목적 도구 > 범용 셸	Read, Edit, Glob 등

카테고리 4: 자동화

#	패턴	설명	활용
12	Deterministic Lifecycle Hooks	라이프사이클 지점에서 결정론적 실행	PreToolUse 훅 등

권한 시스템 4단계 파이프라인 (상세)

모든 도구 호출은 이 파이프라인을 통과한다:

1 2 3 4 5 6 7 8 9 10

도구 호출 요청 ↓ [1] Deny Rules 확인 → 매칭 시 즉시 거부 ↓ [2] Allow Rules 확인 → 매칭 시 즉시 승인 ↓ [3] Bash Classifier → 별도 모델 인스턴스가 위험도 평가 (2초 타임아웃) │ (에이전트의 추론을 볼 수 없음 — 프롬프트 인젝션 방지) ↓ [4] 사용자 대화상자 → 최종 판단

설계 철학: “모델이 무엇을 할지 결정하고, 다른 시스템이 허용 여부를 결정한다.”

프로덕션 하네스 설정 예시

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40

// .claude/settings.json — 팀 공유 하네스 { "permissions": { "allow": [ "Read", "Grep", "Glob", "Bash(npm test:*)", "Bash(npm run lint:*)", "Bash(git status:*)", "Bash(git diff:*)" ], "deny": [ "Bash(rm -rf:*)", "Bash(git push --force:*)", "Bash(curl:*)", "Read(.env*)" ] }, "hooks": { "PostToolUse": [ { "matcher": "Edit", "hooks": [{ "type": "command", "command": "npx prettier --write $CLAUDE_FILE_PATH 2>/dev/null; exit 0" }] } ], "PreToolUse": [ { "matcher": "Bash", "hooks": [{ "type": "command", "command": "./scripts/validate-safe-command.sh", "timeout": 600, "statusMessage": "명령어 안전성 검증 중..." }] } ] } }

---

🎭 오케스트레이션 (Orchestration) 심화

오케스트레이션이란?

오케스트레이션 = 여러 에이전트(또는 단일 에이전트의 여러 단계)를 조율하여 복잡한 작업을 달성하는 것

하네스가 각 에이전트의 “환경”이라면, 오케스트레이션은 에이전트들의 “협업 구조”다.

단일 에이전트 오케스트레이션: Agent Loop

Claude Code의 핵심은 query() 함수의 에이전트 루프다:

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15

┌─→ [1] 컨텍스트 조립 (시스템 프롬프트 + CLAUDE.md + 대화 히스토리 + MCP) │ ↓ │ [2] API 호출 (스트리밍) │ ↓ │ [3] 응답 파싱 (텍스트 블록 + tool_use 블록) │ ↓ │ [4] 권한 체크 (Deny → Allow → Classifier → 사용자) │ ↓ │ [5] 도구 실행 (읽기: 최대 10개 병렬 / 쓰기: 직렬) │ ↓ │ [6] 결과 피드백 (도구 출력 → 대화 메시지) │ ↓ │ [7] 컨텍스트 관리 (한계 접근 시 자동 압축) │ ↓ └── [8] 종료 판단 (도구 호출 없는 텍스트 응답 = 종료)

핵심: 도구 호출이 포함된 응답이 오는 한 루프는 계속된다. 일반 텍스트만 응답하면 자연 종료.

멀티 에이전트 오케스트레이션: 3단계 티어

Tier 1: 서브에이전트 (Agent Tool)

독립 컨텍스트에서 실행되는 자식 에이전트. 결과만 부모에게 반환.

1 2 3 4 5 6 7 8 9 10 11 12

# .claude/agents/security-reviewer.md --- name: security-reviewer description: 보안 취약점 리뷰 tools: Read, Grep, Glob, Bash model: sonnet permissionMode: plan # 읽기 전용 memory: project # 프로젝트 메모리 공유 isolation: worktree # Git 워크트리 격리 --- 당신은 시니어 보안 엔지니어입니다. 인젝션, 인증 우회, 데이터 노출, 암호화 오용에 집중하세요.

서브에이전트 설정 옵션:

옵션	설명
tools / disallowedTools	허용/차단 도구
model	sonnet, opus, haiku
permissionMode	default, acceptEdits, auto, plan…
isolation: worktree	Git 워크트리 격리
background: true	메인 스레드 비차단
memory	세션 간 지속 메모리 (user/project/local)
mcpServers	스코프된 MCP 접근
maxTurns	최대 에이전트 턴 제한

내장 서브에이전트 타입:

타입	모델	용도
Explore	Haiku	읽기전용 코드베이스 탐색 (3단계 세밀도)
Plan	—	Plan 모드의 읽기전용 리서치
General-purpose	—	전체 도구 접근 복잡 태스크

Tier 2: Agent Teams (실험적)

독립 Claude Code 인스턴스들이 피어-투-피어 통신으로 협업.

1 2 3 4 5 6

// 활성화 { "env": { "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1" } }

아키텍처:

1 2 3 4 5 6 7 8 9 10 11 12 13 14

┌─────────────────────────────────────────┐ │ Team Lead │ │ (작업 생성, 팀원 배정, 조율) │ │ │ │ ┌──────────┐ ┌──────────┐ │ │ │Teammate A│←→│Teammate B│ 메시지 │ │ │ (구현) │ │ (테스트) │ 교환 │ │ └──────────┘ └──────────┘ │ │ ↕ ↕ │ │ ┌────────────────────────┐ │ │ │ Shared Task List │ 공유 │ │ │ (의존성, 파일 잠금) │ 태스크 │ │ └────────────────────────┘ │ └─────────────────────────────────────────┘

서브에이전트 vs Agent Teams:

	서브에이전트	Agent Teams
컨텍스트	독립, 결과만 반환	완전 독립 인스턴스
통신	부모에게만 보고	피어-투-피어 메시지
조율	메인 에이전트가 관리	공유 태스크 목록으로 자기 조율
적합	단일 목적 작업	논의가 필요한 복잡한 작업
토큰 비용	낮음 (요약된 결과)	높음 (각각 별도 인스턴스)

조율 원시 요소:

• 공유 태스크 목록 (pending → in-progress → completed)
• 의존성 해결 (선행 태스크 완료 시 자동 차단 해제)
• 파일 잠금 (경합 방지)
• 계획 승인 게이트 (팀원은 읽기전용으로 계획 → 리드 승인 후 실행)

Tier 3: Coordinator Mode

1	CLAUDE_CODE_COORDINATOR_MODE=1

메인 에이전트가 4개 도구만 사용 (AgentTool, SendMessage, TaskStop, SyntheticOutput). 모든 실제 구현은 워커가 담당.

핵심 오케스트레이션 패턴

패턴 1: Fan-Out / Fan-In (Fork-Join)

1 2 3

┌→ Agent A (워크트리 A) ─→┐ 태스크 분해 ────→ ├→ Agent B (워크트리 B) ─→├→ 결과 병합 └→ Agent C (워크트리 C) ─→┘

• /batch 스킬이 이 패턴을 구현
• 5-30개 독립 작업 단위로 분해
• 각 에이전트가 격리된 워크트리에서 구현 → 테스트 → PR 생성
• 부모 컨텍스트 캐시 재사용 (병렬 분기가 토큰 비용 면에서 “거의 무료”)

패턴 2: Writer/Reviewer (Generator/Evaluator)

1 2 3

Generator ──→ 코드 작성 ──→ Evaluator ──→ 비판적 리뷰 ↑ │ └──────── 피드백 기반 개선 ←─────────────┘

• 단일 에이전트는 자기 작업을 신뢰하게 과대평가하는 경향
• 적대적 패턴으로 반복 개선 강제
• /simplify가 변형 구현: 3개 병렬 리뷰 에이전트 (품질, 재사용성, 효율성)

패턴 3: Sequential Dependency Chain

1	Schema 정의 → API 구현 → Frontend 개발 → 테스트 → 보안 감사

의존 관계가 있을 때 병렬화하지 않는 것도 중요한 패턴. CLAUDE.md에 의존 관계를 명시:

1 2 3

## 작업 의존성 - Schema가 확정되기 전에 API를 구현하지 마세요 - API가 완성되기 전에 Frontend를 시작하지 마세요

패턴 4: Competing Hypotheses (경쟁 가설)

1 2 3

버그 보고 → 5개 에이전트가 각각 다른 가설 조사 → 서로의 가설을 반증 시도 (과학적 토론) → 적대적 검증을 통과한 가설 = 원인

순차적 조사는 앵커링 편향에 빠짐. 병렬 적대적 조사가 이를 방지.

패턴 5: The Ralph Loop (상태 비저장 반복)

1 2 3

태스크 선택 → 구현 → 검증 → 커밋(통과 시) → 컨텍스트 리셋 → 반복 ↓ (실패 시) 3회 막힘 → 종료

컴팩션 대신 Git 히스토리와 메모리 파일로 상태 유지. 컨텍스트 오버플로우 방지.

패턴 6: Hierarchical Delegation (계층적 위임)

1 2 3 4 5

Orchestrator / \ Feature Lead A Feature Lead B / \ / \ Impl. Test Impl. Test

피처 리드가 자체 스페셜리스트를 생성. 실제 엔지니어링 조직 구조를 모방. 단일 오케스트레이터의 컨텍스트 과부하 방지.

멀티모델 라우팅

모델	적합한 작업	설정
Opus	복잡한 추론, 아키텍처 설계	오케스트레이터/리드
Sonnet	집중된 구현 작업	워커/구현 에이전트
Haiku	빠른 읽기전용 탐색	Explore 서브에이전트

1 2	# 서브에이전트를 더 저렴한 모델로 라우팅 CLAUDE_CODE_SUBAGENT_MODEL=sonnet

오케스트레이션 디스패치 품질

대부분의 서브에이전트 실패는 실행 실패가 아니라 호출(dispatch) 실패다.

좋은 디스패치에 반드시 포함할 것:

• ✅ 구체적 범위 (어떤 파일, 어떤 함수)
• ✅ 파일 참조 (경로, 줄 번호)
• ✅ 예상 출력물 (무엇을 반환해야 하는지)
• ✅ 성공 기준 (어떻게 검증하는지)

나쁜 예: “이 코드 분석해줘” 좋은 예: “src/auth/jwt.ts의 verifyToken 함수에서 토큰 만료 검증 로직을 분석하고, edge case를 보고해줘”

백프레셔와 안전장치

메커니즘	설명
WIP 제한	동시 에이전트 3-5개 최대
체크인 주기	5-10분마다 상태 확인
킬 기준	3회 이상 막힌 에이전트 종료
파일 소유권	하나의 파일은 하나의 에이전트만 수정
검증 시스템	타입체크, 테스트, 커버리지로 자가 검증

Boris Cherny 워크플로우 (1인 팀)

1 2 3 4

10-15개 동시 Claude Code 세션 × 각각 독립 Git 워크트리 × 각각 별도 태스크/브랜치 = 솔로 개발자 → 소규모 엔지니어링 팀

생산성 스택: CLAUDE.md 컨벤션 + 온디맨드 스킬 + 결정론적 훅 + 워크트리 격리

---

🔄 하네스 vs 오케스트레이션 — 관계 정리

	하네스 (Harness)	오케스트레이션 (Orchestration)
질문	“이 에이전트가 무엇을 보고, 하고, 기억할 수 있는가?”	“에이전트들이 어떻게 분업하고, 소통하고, 결과를 합치는가?”
성격	환경 (Environment)	조율 (Coordination)
비유	작업대 (도구, 권한, 절차)	프로젝트 관리 시스템 (누가, 무엇을, 어떤 순서로)
구성	CLAUDE.md, settings, hooks, permissions, skills, MCP	Agent loop, subagents, teams, task분해, fan-out/in
변화	모델 발전 시 일부 불필요해질 수 있음	조율 복잡성 문제이므로 상대적으로 안정적

관계: 오케스트레이션은 하네스 위에서 작동한다. 모든 서브에이전트, 팀원은 하네스 설정을 상속하거나 오버라이드한다.

Anthropic의 통찰: “하네스의 모든 구성요소는 ‘모델이 혼자서는 못하는 것’에 대한 가정을 인코딩한다. 그 가정은 스트레스 테스트할 가치가 있다.”