Claude Code 고급 워크플로우 — Anthropic 엔지니어가 실제로 쓰는 CLAUDE.md·Hooks·병렬 에이전트·Skills 완전 가이드

 

[핵심 요약]
→ Boris Cherny (Claude Code 제품 리드): 10~15 병렬 세션 — 터미널 5개 + claude.ai/code 5~10개 + iPhone
→ 핵심 원칙: CLAUDE.md(헌법) + Hooks(결정론적 자동화) + Skills(재사용) + Subagents(컨텍스트 격리)
→ Git Worktree: 2026년 2월 20일 CLI 지원 — 병렬 에이전트의 인프라 기반
→ 컨텍스트 관리: 50%에서 /compact / 태스크 전환 시 /clear / Plan→Execute→Verify 사이클
→ v2.1.101 (2026년 4월 11일): 커스텀 슬래시 명령이 Skills로 통합
→ v2.1.142 (2026년 5월 15일): 현재 최신, Agent View, /goal 추가
→ 설치: curl -fsSL https://claude.ai/install.sh | bash (Native binary 권장, NPM deprecated)
→ 서브에이전트 + MCP 병렬 초기화: 2026년 4월 24일 추가 — 시작 시간 대폭 단축

---

실전 1 — CLAUDE.md: 에이전트 헌법

CLAUDE.md는 README가 아닙니다. 인간이 읽는 문서가 아니라 에이전트가 매 세션 시작마다 읽는 행동 헌법입니다.

 

 

# CLAUDE.md — 잘못된 예시 (README처럼 쓴 것)

## 프로젝트 개요
이 프로젝트는 FastAPI 기반 REST API 서버입니다.
사용자 인증과 결제를 처리합니다.
팀원: Alice, Bob, Carol

## 기술 스택
- Python 3.12
- FastAPI
- PostgreSQL

 

 

# CLAUDE.md — 올바른 예시 (에이전트 행동 제어)

## 빌드 및 테스트 명령어
```bash
# 개발 서버
uv run uvicorn app.main:app --reload

# 테스트 실행 (항상 이 명령어)
uv run pytest tests/ -x -v

# 타입 체크
uv run mypy app/

# 린팅
uv run ruff check app/ --fix
```

## 핵심 규칙 — 반드시 따를 것

1. **타입 힌트 필수**: 모든 함수에 파라미터·반환 타입 명시
2. **테스트 먼저**: 새 기능 구현 전 테스트 작성
3. **절대 건드리지 말 것**: `app/core/security.py` — Carol 소유, PR 필요
4. **마이그레이션 자동 실행 금지**: `alembic upgrade head` 절대 자동 실행 않음
5. **환경변수 하드코딩 금지**: `.env.example` 참조
6. **커밋 메시지 형식**: `feat(module): description` / `fix(module): description`

## 아키텍처 결정 기록

- **ORM**: SQLAlchemy 2.0 async (Tortoise 아님 — 2025년 마이그레이션 완료)
- **인증**: JWT + refresh token (세션 기반 아님)
- **결제**: Stripe v7 (Toss 아님 — 2026년 Q1 결정)
- **캐싱**: Redis (Memcached 아님)

## 에러 처리 패턴

모든 API 에러는 다음 형식:
```python
{"error": {"code": "ERROR_CODE", "message": "한국어 메시지"}}
```

## 파일 소유권

| 파일/디렉토리 | 소유자 | 변경 시 |
|---|---|---|
| `app/core/security.py` | Carol | PR + 리뷰 필수 |
| `app/payments/` | Bob | Slack 알림 필수 |
| `alembic/` | Alice | 직접 수정 금지 |

## 자동 실행 허용 목록
- pytest, mypy, ruff (항상 허용)
- git add, git commit (허용)
- docker-compose up (허용)

## 자동 실행 금지 목록
- alembic upgrade (금지 — 항상 확인 요청)
- git push --force (금지)
- DROP TABLE (금지)
- rm -rf (금지)

 

 

[CLAUDE.md WHAT/WHY/HOW 프레임워크]

WHAT: 무엇을 해야 하는가 (규칙, 명령어)
WHY: 왜 그렇게 해야 하는가 (맥락, 히스토리)
HOW: 어떻게 하는가 (구체적 패턴, 예시)

예시:
WHAT: Stripe v7 사용
WHY: 2026년 Q1에 Toss에서 마이그레이션 완료 (레거시 코드 남아있을 수 있음)
HOW: from app.integrations.stripe_v7 import StripeClient

→ WHY가 없으면 Claude가 "더 좋아 보이는" 방법으로 바꿈
→ WHY가 있으면 컨텍스트를 이해하고 지킴

---

실전 2 — Hooks: 결정론적 자동화

Hooks는 Claude의 해석에 의존하지 않고 이벤트 발생 시 결정론적으로 실행됩니다. 할루시네이션이 없습니다.

 

 

# Hooks 설정 위치
.claude/hooks.yaml        # 프로젝트 전용
~/.claude/hooks.yaml      # 전역 (모든 프로젝트)

# 현재 Hooks 확인
/hooks

 

 

# .claude/hooks.yaml

hooks:
  # ── 위험 명령어 사전 차단 ─────────────────────────
  PreToolUse:
    - name: "위험 명령어 차단"
      match:
        tool: Bash
        # 정규식으로 위험 패턴 감지
        command_pattern: "(rm -rf|DROP TABLE|git push --force|alembic upgrade)"
      action:
        type: block
        message: "⛔ 위험한 명령어입니다. 수동으로 실행하세요."

    # 결제 모듈 변경 시 경고
    - name: "결제 모듈 보호"
      match:
        tool: Write
        path_pattern: "app/payments/.*"
      action:
        type: confirm
        message: "💳 결제 모듈을 변경합니다. Bob에게 Slack 알림을 보내셨나요?"

  # ── 파일 저장 후 자동 처리 ─────────────────────────
  PostToolUse:
    # Python 파일 저장 시 자동 포맷·린팅
    - name: "Python 자동 린팅"
      match:
        tool: Write
        path_pattern: ".*\\.py$"
      action:
        type: run
        command: |
          uv run ruff check "$CLAUDE_TOOL_PATH" --fix --quiet
          uv run ruff format "$CLAUDE_TOOL_PATH" --quiet

    # 테스트 파일 수정 시 자동 실행
    - name: "테스트 자동 실행"
      match:
        tool: Write
        path_pattern: "tests/.*\\.py$"
      action:
        type: run
        command: uv run pytest "$CLAUDE_TOOL_PATH" -x -q --tb=short

  # ── 태스크 완료 시 알림 ─────────────────────────────
  Stop:
    - name: "태스크 완료 알림"
      action:
        type: run
        command: |
          # macOS 알림
          osascript -e 'display notification "Claude Code 태스크 완료" with title "Claude Code"'
          # 또는 터미널 벨
          echo -e '\a'

  # ── 워크트리 생성 시 환경 자동 세팅 ────────────────
  WorktreeCreate:
    - name: "워크트리 환경 초기화"
      action:
        type: run
        command: |
          cd "$CLAUDE_WORKTREE_PATH"
          # 의존성 설치
          uv sync
          # 환경변수 복사
          cp ../.env .env
          # 개발 서버 시작 (백그라운드)
          echo "✅ 워크트리 환경 초기화 완료: $CLAUDE_WORKTREE_PATH"

 

 

 

# 전역 Hooks (~/.claude/hooks.yaml) — 모든 프로젝트 공통

hooks:
  PreToolUse:
    # API 키 하드코딩 감지
    - name: "시크릿 감지"
      match:
        tool: Write
        content_pattern: "(sk-ant-|sk-or-|AIzaSy|ghp_)[a-zA-Z0-9]+"
      action:
        type: block
        message: "🔑 API 키가 코드에 포함됐습니다. .env 파일을 사용하세요."

    # 모든 툴 호출 감사 로그
    - name: "감사 로그"
      action:
        type: run
        command: |
          echo "$(date -Iseconds) | $CLAUDE_TOOL_NAME | $CLAUDE_SESSION_ID" \
            >> ~/.claude/audit.log

 

 

[Hook 이벤트 목록]
PreToolUse:   툴 실행 전 — 차단 가능
PostToolUse:  툴 실행 후 — 린팅, 테스트 등
Stop:         세션 종료 — 알림, 정리
WorktreeCreate: 워크트리 생성 — 환경 초기화
Notification: Claude가 입력 기다릴 때

[환경변수 (Hook 내에서 사용 가능)]
$CLAUDE_TOOL_NAME     현재 실행 중인 툴 이름
$CLAUDE_TOOL_PATH     파일 경로 (파일 관련 툴)
$CLAUDE_SESSION_ID    현재 세션 ID
$CLAUDE_WORKTREE_PATH 워크트리 경로

---

실전 3 — Git Worktree로 병렬 에이전트

 

 

 

# ── 기본 설치 및 설정 ─────────────────────────────────
# Claude Code 최신 버전 설치
curl -fsSL https://claude.ai/install.sh | bash

# 로그인
claude auth login

# ── Worktree 기반 병렬 작업 ───────────────────────────

# 터미널 1: 로그인 기능 개발
claude --worktree feat-login
# → .claude/worktrees/feat-login/ 자동 생성
# → feat-login 브랜치 체크아웃
# → Hook으로 환경 자동 초기화

# 터미널 2: 검색 버그 수정 (동시에)
claude --worktree fix-search-bug

# 터미널 3: 리팩토링 (동시에)
claude --worktree refactor-payments

# → 3개 에이전트가 같은 레포에서 충돌 없이 동시 작업
# → 각자 독립 브랜치 → git 충돌 없음
# → 완료되면 PR 생성 → 코드 리뷰

 

 

# ── Boris Cherny 실제 워크플로우 ──────────────────────

# 아침: iPhone에서 Claude Code 앱으로 태스크 시작
# "user-auth 모듈의 JWT 만료 처리 개선해줘"
# → 세션 시작, 백그라운드에서 진행

# 사무실 도착: 터미널 탭 5개 오픈
# Tab 1: feat-login worktree
claude --worktree feat-login
# Tab 2: fix-perf worktree  
claude --worktree fix-perf
# Tab 3: docs-update worktree
claude --worktree docs-update

# 각 탭에서 Plan → Execute → Verify 사이클
# Plan: "이 태스크를 어떻게 접근할지 계획 세워줘"
# Execute: "계획대로 구현해줘"
# Verify: 자동으로 "pytest && mypy && ruff" 실행

# 컨텍스트 50% 도달 시:
/compact
# → 대화 압축, 중요 컨텍스트 유지

# 태스크 전환 시:
/clear
# → 완전 초기화 (이전 컨텍스트 오염 방지)

 

 

# ── wt 유틸리티 (더 편리한 워크트리 관리) ──────────────
# npm install -g worktree-utils (별도 툴)

# 워크트리 생성 + Claude 즉시 시작
wt switch -x claude -c feat-login -- 'login with email/password 구현'

# 워크트리 목록
wt list
# Branch         Status  HEAD±  Commit  Age   Message
# feat-login     +–      +74    d4e5f6  5m    Add login route
# fix-search     +12            b1c2d3  3m    Escape query params
# ^ main         0              0e6314  1d    Initial commit

# 완료된 워크트리 정리
wt merge feat-login --cleanup

---

실전 4 — Skills: 팀 공용 재사용 워크플로우

 

 

# Skills 위치
.claude/skills/SKILL.md          # 전체 프로젝트용
.claude/skills/deploy/SKILL.md   # 특정 태스크용
~/.claude/skills/                # 개인 전역 Skills

 

 

<!-- .claude/skills/code-review/SKILL.md -->
---
name: code-review
description: PR 코드 리뷰 실행 — 보안·성능·테스트 커버리지 체크
---

# 코드 리뷰 가이드라인

다음 순서로 코드를 리뷰합니다:

## 1. 보안 체크
- SQL 인젝션 가능성
- 하드코딩된 시크릿
- 입력 검증 누락
- 인증/인가 우회 가능성

## 2. 성능 체크
- N+1 쿼리 패턴
- 불필요한 DB 조회
- 메모리 누수 가능성
- 동기 코드의 비동기 대체 가능성

## 3. 테스트 커버리지
- 새로운 코드에 테스트 있는지
- 엣지 케이스 처리 여부
- 에러 케이스 테스트 여부

## 4. 출력 형식
```markdown
## 코드 리뷰 결과

### 🔴 Critical (즉시 수정 필요)
- 

### 🟡 Warning (권장 수정)
- 

### 🟢 Good (잘 된 점)
- 

### 📊 요약
- 전체 품질: X/10
- 배포 권장: Yes/No
```

 

 

<!-- .claude/skills/deploy/SKILL.md -->
---
name: deploy
description: 스테이징 또는 프로덕션 배포
disable-model-invocation: true  # Claude가 실수로 호출 불가
allowed-tools:
  - Bash(gh *)
  - Bash(git *)
---

# 배포 가이드

$ARGUMENTS를 배포합니다 (staging | production).

## 사전 체크리스트
1. 테스트 전체 통과 확인: `uv run pytest tests/ -x`
2. 타입 체크: `uv run mypy app/`
3. 린팅: `uv run ruff check app/`
4. 변경사항 요약 작성

## 스테이징 배포
```bash
gh workflow run deploy.yml -f environment=staging
```

## 프로덕션 배포
```bash
# 반드시 수동 확인 후 실행
gh workflow run deploy.yml -f environment=production
```

⚠️ 프로덕션 배포 전 Slack #deployments에 공지 필수

 

 

 

# Skills 사용
/code-review      # 현재 변경사항 코드 리뷰
/deploy staging   # 스테이징 배포
/deploy production # 프로덕션 배포

# 내장 Skills (2026년)
/batch            # 대규모 병렬 변경 오케스트레이션
/claude-api       # 언어별 API 레퍼런스 로드
/debug            # 디버그 로깅 활성화
/loop             # 반복 간격으로 프롬프트 실행
/simplify         # 3개 병렬 리뷰 에이전트로 코드 품질 체크
/team-onboarding  # 신규 팀원 온보딩 문서 자동 생성

---

실전 5 — Subagents로 컨텍스트 격리

 

 

# Subagent 위치
.claude/agents/         # 프로젝트 전용
~/.claude/agents/       # 전역

# 내장 Subagent 타입
# Explore: 읽기 전용 코드베이스 탐색
# Plan: 실행 없이 계획만
# 범용: 실행 포함

 

 

<!-- .claude/agents/security-reviewer.md -->
---
name: security-reviewer
description: 보안 취약점 전문 분석 에이전트
model: claude-opus-4-7     # 보안 분석은 최강 모델
tools:
  - Read
  - Bash(grep *)
  - Bash(find *)
# 쓰기 툴 없음 — 읽기 전용으로 안전
---

당신은 보안 전문가입니다. 다음 관점에서만 코드를 분석합니다:

1. OWASP Top 10 취약점
2. 한국 KISA 보안 가이드라인
3. Stripe PCI DSS 요구사항

분석 후 심각도(Critical/High/Medium/Low)로 분류하고
구체적인 수정 방법을 제시합니다.

절대 코드를 수정하지 않습니다. 분석과 권고만 합니다.

 

 

<!-- .claude/agents/test-writer.md -->
---
name: test-writer
description: pytest 단위 테스트 자동 작성
model: claude-sonnet-4-6  # 테스트 작성은 Sonnet으로 충분
tools:
  - Read
  - Write
  - Bash(uv run pytest *)
---

당신은 pytest 전문가입니다.

테스트 작성 규칙:
1. 모든 엣지 케이스 포함 (빈 입력, None, 최대값)
2. Given/When/Then 패턴
3. 픽스처는 conftest.py에
4. 모킹은 unittest.mock 사용
5. 테스트 실행 후 결과 보고

작성 후 반드시 실행해서 통과 확인합니다.

 

 

# Subagent 사용
# 단일 메시지로 여러 서브에이전트 병렬 실행
"security-reviewer로 app/payments/ 보안 분석하고,
 test-writer로 app/users/auth.py 테스트 작성하고,
 Explore 에이전트로 현재 API 문서 현황 파악해줘"

# → 3개 서브에이전트 동시 실행
# → 각자 독립 컨텍스트 윈도우 (메인 컨텍스트 오염 없음)
# → 완료 후 결과만 메인으로 반환

# 백그라운드로 서브에이전트 실행
Ctrl + B  # 백그라운드로 전환
# → 메인 세션 계속 사용 가능
# → 백그라운드 에이전트 완료 시 알림

 

 

[서브에이전트 언제 쓰나]

메인 에이전트 직접 실행:
→ 단순·빠른 태스크
→ 메인 컨텍스트와 밀접한 관련
→ 10단계 이하 작업

서브에이전트:
→ 탐색 (코드베이스 읽기) — Explore 에이전트
→ 컨텍스트를 오염시키는 대규모 검색
→ 병렬로 독립 실행 가능한 작업들
→ 특정 전문 역할 (보안, 테스트, 문서화)

서브에이전트 모델 라우팅:
→ Opus: 보안 분석, 아키텍처 결정
→ Sonnet: 코드 생성, 리팩토링, 테스트
→ Haiku: 분류, 요약, 단순 검색
→ 비용 최적화: 태스크 복잡도에 맞는 모델 선택

---

실전 6 — 컨텍스트 관리 마스터하기

 

 

 

# ── 컨텍스트 상태 확인 ────────────────────────────────
# 세션 중 컨텍스트 사용량 실시간 표시 (하단 상태바)
# [███████████░░░░░░░] 65% — 아직 괜찮음
# [████████████████░░] 85% — /compact 시점
# [██████████████████] 100% — 강제 압축 또는 에러

# ── 컨텍스트 관리 명령어 ─────────────────────────────
/compact     # 50~80% 시점에 사용 — 중요 내용 유지하며 압축
/clear       # 태스크 전환 시 — 완전 초기화 (이전 오염 방지)
/goal        # 현재 목표 명시적 설정 (v2.1.142 신기능)

# ── 언제 어떤 명령어를 쓰나 ──────────────────────────
# /compact:
#   - 같은 태스크 계속 진행 중
#   - 이전 맥락이 필요함
#   - 50~80% 구간에서 사용

# /clear:
#   - 완전히 다른 태스크로 전환
#   - 이전 맥락이 새 태스크를 오염시킬 우려
#   - 버그 디버깅 완료 후 새 기능 개발 시작

# ── Plan → Execute → Verify 사이클 ───────────────────
# 모든 태스크에 이 순서를 강제

# 1. Plan (계획)
"이 기능을 어떻게 구현할지 계획만 세워줘. 코드는 아직 작성하지 마."
# → Claude가 접근법 설명 → 검토 → 승인

# 2. Execute (실행)
"계획대로 구현해줘"
# → Claude가 실제 코드 작성

# 3. Verify (검증) — Hook이 자동 실행
"테스트 실행하고 타입 체크해줘"
# 또는 Hook이 자동으로:
# uv run pytest && uv run mypy app/ && uv run ruff check app/

 

 

 

# ── 자동 메모리 활용 ──────────────────────────────────
# Claude Code는 세션 간 학습을 자동 축적
# - 어떤 빌드 명령이 작동하는지
# - 디버깅에서 어떤 접근이 성공했는지
# - 암묵적 코딩 선호도

# 자동 메모리 확인
/memory

# 특정 패턴 기억 강제
"이 패턴을 기억해줘: FastAPI 엔드포인트는 항상
 async def로 작성하고 Depends()로 의존성 주입"

---

실전 7 — MCP 연동으로 외부 도구 통합

 

 

# MCP 서버 추가
claude mcp add github -- gh api
claude mcp add postgres -- psql "$DATABASE_URL"

# 프로젝트별 MCP 설정
# .claude/config.json

 

 

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    },
    "postgres": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-postgres",
               "${DATABASE_URL}"]
    },
    "slack": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-slack"],
      "env": {
        "SLACK_BOT_TOKEN": "${SLACK_BOT_TOKEN}"
      }
    }
  }
}

 

 

 

# MCP 연동 후 가능한 것들
"GitHub에서 오픈 PR 목록 가져와서 리뷰 우선순위 정해줘"
"DB에서 슬로우 쿼리 찾아서 최적화해줘"
"Slack #backend 채널 오늘 메시지에서 버그 리포트 찾아줘"

# 2026년 4월 24일: 서브에이전트 + MCP 병렬 초기화
# → 멀티 에이전트 + 멀티 MCP 환경 시작 시간 대폭 단축

---

팀 도입 체크리스트

 

 

[즉시 시작 — Day 1]
☐ claude auth login
☐ CLAUDE.md 프로젝트 루트에 생성 (WHAT/WHY/HOW 프레임워크)
☐ 핵심 규칙 5~7개 명시
☐ 절대 건드리면 안 되는 파일/디렉토리 명시
☐ 자동 실행 허용·금지 목록 명시

[이번 주 — Week 1]
☐ .claude/hooks.yaml 생성
   → 위험 명령어 차단 Hook
   → Python 파일 저장 시 자동 린팅 Hook
   → 태스크 완료 알림 Hook
☐ /compact 타이밍 습관화 (50~80%)
☐ Plan → Execute → Verify 사이클 적용

[다음 달 — Month 1]
☐ 팀 공용 Skills 2~3개 작성 (/code-review, /pr-summary)
☐ Git Worktree 병렬 작업 세팅
☐ 서브에이전트 1~2개 정의 (security-reviewer, test-writer)
☐ MCP 서버 연결 (GitHub, DB)
☐ /batch로 대규모 리팩토링 실험

[비용 최적화]
☐ 서브에이전트 모델 라우팅 설정
   → 복잡 태스크: claude-opus-4-7
   → 일반 태스크: claude-sonnet-4-6
   → 분류·요약: claude-haiku-4-5
☐ Skills: CLAUDE.md에 없고 필요할 때만 로드
   (CLAUDE.md는 항상 로드 → 컨텍스트 차지)
☐ 컨텍스트 50% 초과 전 /compact 습관화

---

마무리

 

 

✅ 핵심 원칙 3가지
→ CLAUDE.md: "AI 팀원을 위한 헌법" — README 아님
→ Hooks: 중요한 규칙은 프롬프트가 아닌 코드로 강제
→ 병렬: 기다리는 시간 없음 — 한 에이전트 작업 중 다른 것 리뷰

✅ Boris Cherny 워크플로우 요약
→ 10~15 병렬 세션 (각자 Git Worktree)
→ 50% 컨텍스트 → /compact
→ 태스크 전환 → /clear
→ 항상 Plan → Execute → Verify
→ 서브에이전트로 컨텍스트 격리

❌ 흔한 실수
→ CLAUDE.md를 README처럼 쓰기 — WHY 없이 WHAT만
→ 모든 것을 메인 에이전트 하나로 처리 — 컨텍스트 오염
→ /compact 없이 100% 도달 — 성능 급락
→ Hooks 없이 프롬프트로만 규칙 강제 — 할루시네이션으로 우회됨
→ 직렬 작업 — 에이전트가 일하는 동안 기다리는 시간 낭비