Claude Code,
제대로 쓰는 법

로딩 순서 (아래로 갈수록 좁은 범위 = 더 높은 우선순위)

~/.claude/CLAUDE.md           ← ① 전역: 모든 프로젝트에 항상 적용
프로젝트루트/CLAUDE.md        ← ② 프로젝트: 이 프로젝트 전용 규칙
프로젝트루트/src/CLAUDE.md    ← ③ 폴더: 특정 폴더 진입 시 추가 적용
프로젝트루트/src/api/CLAUDE.md ← ④ 서브폴더: 더 세밀한 영역 규칙

# 코딩 패턴
에러 처리는 반드시 Result 패턴을 사용한다:
@src/types/result.ts

API 라우트 작성 예시:
@src/app/api/users/route.ts

서비스 레이어 패턴:
@src/services/user.service.ts

~/.claude/commands/            ← 개인 스킬 (모든 프로젝트에서 사용 가능)
  ├── commit.md                  /commit 커맨드
  ├── standup.md                 /standup 커맨드
  └── debug.md                   /debug 커맨드

.claude/commands/              ← 팀 프로젝트 스킬 (git에 커밋, 팀 공유)
  ├── pr.md                      /pr 커맨드
  ├── review.md                  /review 커맨드
  └── security-audit.md          /security-audit 커맨드

---
name: commit
description: 스테이징된 변경사항을 분석하고 Conventional Commits 형식으로 커밋
---

현재 git staging area에 있는 변경사항을 분석하고 커밋해줘.

요구사항:
- 형식: type(scope): description (영어, 50자 이내)
- type: feat/fix/refactor/docs/test/chore/style
- scope: 변경된 주요 모듈명
- body: 변경 이유와 영향 범위 (한국어 OK)
- footer: 관련 이슈 번호 (있으면)

예시:
feat(auth): add OAuth2 login with GitHub provider

Closes #123

Co-Authored-By: Claude <noreply@anthropic.com>

---
name: review              # /name 으로 호출되는 커맨드명
description: 코드 리뷰    # /help 에서 보이는 설명
model: claude-haiku-4-5  # 이 스킬에서 사용할 모델 (비용 최적화)
---

프롬프트 내용...

# $ARGUMENTS 로 동적 인자 전달
# /review src/auth.ts → $ARGUMENTS = "src/auth.ts"
$ARGUMENTS 파일을 코드 리뷰해줘.

~/.claude/projects/[프로젝트경로해시]/memory/
  ├── MEMORY.md               ← 인덱스 (목차, 200줄 제한)
  ├── user_profile.md         ← user 타입
  ├── feedback_style.md       ← feedback 타입
  ├── feedback_testing.md     ← feedback 타입 (복수 가능)
  ├── project_auth.md         ← project 타입
  └── reference_systems.md   ← reference 타입

# MEMORY.md 예시
- [사용자 프로필](user_profile.md) — TypeScript 10년차, React 6개월
- [응답 스타일](feedback_style.md) — 요약 없이, 예제 코드 중심
- [인증 리팩토링](project_auth.md) — JWT→세션, 2026-05-15 배포
- [외부 시스템](reference_systems.md) — Linear, Grafana 위치

Claude Code  ←→  MCP 서버  ←→  외부 서비스
     │               │
     │  JSON-RPC     │  API 호출
     │  (stdio/HTTP) │  (REST, GraphQL, DB)

예시 흐름:
1. Claude: "PR #123에 리뷰 코멘트 달아줘"
2. MCP 서버 (GitHub): GitHub API 호출
3. GitHub: PR에 인라인 코멘트 생성
4. MCP 서버: 결과를 Claude에게 반환
5. Claude: "코멘트 3개 추가했습니다"

이벤트 발생
    ↓
Hook 스크립트 실행
    ↓
exit code 0    → 정상 진행
exit code != 0 → 작업 차단 (Claude에게 에러 메시지 전달)

stdout → Claude가 읽음 (컨텍스트로 전달)
stderr → 로그로만 기록 (Claude에게 전달 안 됨)

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Bash",
      "hooks": [{
        "type": "command",
        "command": "bash -c 'cmd=$(echo \"$CLAUDE_TOOL_INPUT\" | jq -r .command); if echo \"$cmd\" | grep -qE \"rm -rf|git push --force|DROP TABLE\"; then echo \"위험 명령 감지: $cmd\" && exit 1; fi'"
      }]
    }]
  }
}

{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Write|Edit",
      "hooks": [{
        "type": "command",
        "command": "bash -c 'file=$(echo \"$CLAUDE_TOOL_RESULT\" | jq -r .path // empty); if [ -n \"$file\" ] && echo \"$file\" | grep -qE \"\\.(ts|tsx|js|jsx|json)$\"; then npx prettier --write \"$file\" 2>/dev/null; fi'"
      }]
    }]
  }
}

{
  "hooks": {
    "UserPromptSubmit": [{
      "hooks": [{
        "type": "command",
        "command": "bash -c 'branch=$(git branch --show-current 2>/dev/null || echo \"unknown\"); issue=$(echo \"$branch\" | grep -oE \"[0-9]+\" | head -1); echo \"[현재 브랜치: $branch, 이슈: #$issue]\"; exit 0'"
      }]
    }]
  }
}

{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Write|Edit",
      "hooks": [{
        "type": "command",
        "command": "bash -c 'file=$(echo \"$CLAUDE_TOOL_RESULT\" | jq -r .path // empty); if [ -n \"$file\" ]; then git add \"$file\" 2>/dev/null; echo \"auto-staged: $file\"; fi'"
      }]
    }]
  }
}

{
  "hooks": {
    "PostResponse": [{
      "hooks": [{
        "type": "http",
        "url": "https://hooks.slack.com/services/YOUR/WEBHOOK/URL",
        "method": "POST",
        "headers": { "Content-Type": "application/json" },
        "body": "{\"text\": \"Claude 작업 완료 ✅\"}"
      }]
    }]
  }
}

~/.claude/settings.json    ← 전역 훅 (모든 프로젝트에 적용)
.claude/settings.json      ← 프로젝트 훅 (팀 공유 가능, 토큰 없는 것만)

우선순위 (아래로 갈수록 높음)

~/.claude/settings.json        ← 전역 기본값 (모든 프로젝트 적용)
.claude/settings.json          ← 프로젝트 설정 (전역 덮어씀)
환경변수 (ANTHROPIC_MODEL 등)  ← 최우선 (CI/CD에서 유용)

{
  "model": "claude-sonnet-4-6",

  "permissions": {
    "allow": [
      "Bash(git *)",
      "Bash(npm *)",
      "Bash(npx *)",
      "Read(**)",
      "Write(src/**)",
      "Write(test/**)"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(git push --force*)",
      "Bash(git push --force-with-lease*)",
      "Bash(DROP *)",
      "Write(.env*)"
    ]
  },

  "autoApprove": {
    "tools": ["Read", "Glob", "Grep", "LS"]
  },

  "env": {
    "NODE_ENV": "development",
    "LOG_LEVEL": "debug"
  },

  "includeCoAuthoredBy": true,

  "disabledTools": ["WebSearch", "WebFetch"]
}

# 모델 오버라이드
ANTHROPIC_MODEL=claude-haiku-4-5-20251001 claude -p "빠른 작업"

# API 키 오버라이드
ANTHROPIC_API_KEY=sk-ant-xxx claude -p "작업 실행"

# GitHub Actions에서 Claude 실행
env:
  ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
  ANTHROPIC_MODEL: claude-sonnet-4-6

1. Plan Mode 진입 (Shift+Tab+Tab)

2. 작업 요청
   "인증 모듈을 JWT에서 세션 기반으로 리팩토링해줘"

3. Explore sub-agent가 코드베이스 자동 조사
   - 영향 받는 파일 목록 파악
   - 현재 인증 흐름 분석
   - 의존성 파악

4. Plan sub-agent가 구현 전략 설계
   - 변경 순서 결정
   - 각 파일별 변경 사항 명시
   - 위험 요소 식별

5. 계획 파일 생성 (사람이 검토 가능한 형태)
   예: "변경 파일 7개, 순서: middleware → service → controller → test"

6. 사람이 계획 검토
   - 동의하면: Plan Mode 종료 → 실행
   - 수정 요청: "3단계 순서를 바꿔줘"

7. 실행

📋 변경 계획
영향 파일: 12개
예상 위험: AuthService가 JWT 토큰 검증에 의존하고 있어 순서가 중요합니다.

실행 순서:
1. [위험 낮음] config/session.ts 생성 — 세션 설정
2. [위험 낮음] middleware/session.ts 수정 — passport-session 추가
3. [위험 중간] services/AuthService.ts 수정 — JWT → 세션 교체
4. [위험 중간] controllers/UserController.ts 수정 — 토큰 응답 제거
5. [위험 낮음] tests/auth.test.ts 수정 — 세션 기반 테스트로 교체

진행하시겠습니까?

# Plan Mode 자동 적용 규칙
다음 상황에서는 반드시 Plan Mode로 계획을 먼저 제시하고, 승인 없이 실행 금지:
- 10개 이상 파일에 걸친 변경
- DB 스키마 변경 (migration 파일 생성 필요)
- API 인터페이스 변경 (다른 서비스/클라이언트에 영향)
- package.json 의존성 추가/제거
- 인증/보안 관련 코드 변경

계획 출력 형식:
- 영향 파일 수
- 변경 실행 순서 (위험도 포함)
- 예상 위험 요소

"이 프로젝트를 동시에 분석해줘:
 - Explore agent 1: src/auth/ 관련 모든 파일 분석하고 인증 흐름 정리
 - Explore agent 2: API 엔드포인트 목록과 각 엔드포인트의 미들웨어 정리
 - Explore agent 3: 현재 테스트 커버리지 현황과 누락된 테스트 파악
결과를 취합해서 종합 보고서 작성해줘."

메인 Claude
  ├── Explore agent 1 → auth 폴더 분석 보고서 반환
  ├── Explore agent 2 → API 목록 반환            (동시 실행)
  └── Explore agent 3 → 테스트 커버리지 반환

메인 Claude → 3개 보고서 취합 → 종합 분석

## 태스크 목록

- [진행중] [AGENT-A] auth/ 폴더 — JWT 제거, 세션 미들웨어 구현
- [ ] [AGENT-B] payment/ 폴더 — Stripe 웹훅 핸들러 구현
- [ ] [AGENT-C] test/ 폴더 — 위 두 모듈의 통합 테스트 작성
- [완료] [AGENT-D] docs/ 폴더 — API 문서 업데이트

## 규칙
- 각 에이전트는 자신의 폴더만 수정
- 공유 types/ 폴더 수정 시 리드 에이전트에게 위임
- 태스크 시작 시 [진행중]으로 변경
- 완료 시 [완료]로 변경 후 다음 태스크 선택

충돌 방지 3원칙:

1. 영역 분리: 각 에이전트에게 담당 폴더를 명확히 지정
   AGENT-A → auth/
   AGENT-B → payment/
   AGENT-C → test/

2. 공유 파일은 리드 에이전트만 수정
   types/, utils/ 등 공통 모듈은 한 에이전트만 담당

3. 태스크 파일에 상태 표시
   작업 시작 전 [진행중]으로 표시해 중복 작업 방지

"이 버그의 원인으로 두 가지 가설이 있어:
 - Agent A: 가설1 — 캐시 무효화 타이밍 문제를 검증해줘
 - Agent B: 가설2 — 타임존 처리 오류를 검증해줘
먼저 재현 성공한 에이전트의 가설이 맞을 가능성이 높아.
각자 독립적으로 검증하고 결과를 보고해줘."

"동시에 진행해줘:
 - Explore agent: 현재 인증 구조 파악 (auth/ 폴더 전체 분석)
 - Explore agent: API 엔드포인트 전체 목록 정리
 - Plan agent: 세션 기반 전환 전략 수립 (장단점 포함)

3개 결과를 취합해서 마이그레이션 로드맵 만들어줘.

→ 순차 진행보다 3배 빠름
→ 각 에이전트가 독립 컨텍스트로 해당 영역에만 집중

# 에이전트별 독립 작업 공간 생성
git worktree add ../project-auth feature/auth-session
git worktree add ../project-payment feature/payment-stripe
git worktree add ../project-notify feature/notification

# 프롬프트: 각 worktree에 에이전트 배치
"3개 worktree에서 병렬로 작업해줘:
 - ../project-auth 폴더: 세션 인증 구현 (auth/ 폴더만)
 - ../project-payment 폴더: Stripe 웹훅 구현 (payment/ 폴더만)
 - ../project-notify 폴더: 알림 시스템 구현 (notification/ 폴더만)

 각자 자신의 폴더에서만 작업. 완료 시 PR 생성 후 보고해줘."

# 완료 후 정리
git worktree remove ../project-auth
git worktree remove ../project-payment
git worktree remove ../project-notify

# 기본 Headless 실행 (-p = prompt)
claude -p "src/ 폴더의 모든 TypeScript 파일에서 console.log를 logger.info로 교체해줘"

# 특정 모델로 실행
claude -p "보안 취약점 스캔해줘" --model claude-opus-4-6

# 퍼미션 자동 승인 (신뢰 환경에서만)
claude -p "테스트 실행하고 실패한 것들 수정해줘" --dangerously-skip-permissions

# 출력을 파일로 저장
claude -p "코드 분석 보고서 작성해줘" > report.md

name: Claude Code Review

on:
  pull_request:
    types: [opened, synchronize]

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Install Claude Code
        run: npm install -g @anthropic-ai/claude-code

      - name: Run Claude Review
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          claude -p "PR의 변경사항을 리뷰하고 GitHub PR에 인라인 코멘트를 달아줘. 보안과 로직 버그에 집중해." \
            --dangerously-skip-permissions

on:
  workflow_run:
    workflows: ["CI"]
    types: [completed]

jobs:
  analyze-failure:
    if: ${{ github.event.workflow_run.conclusion == 'failure' }}
    runs-on: ubuntu-latest
    steps:
      - run: |
          claude -p "CI 로그를 분석해서 실패 원인과 수정 방법을 제안해줘" \
            --dangerously-skip-permissions

{
  "permissions": {
    "allow": [
      "Read(*)",
      "Glob(*)",
      "Grep(*)"
    ],
    "deny": [
      "Edit(*)",
      "Write(*)",
      "Bash(*)"
    ]
  }
}

{
  "permissions": {
    "allow": [
      "Read(*)",
      "Edit(src/**)",
      "Edit(test/**)",
      "Bash(npm test*)",
      "Bash(npm run lint*)",
      "Bash(git add*)",
      "Bash(git commit*)"
    ],
    "deny": [
      "Bash(rm *)",
      "Bash(git push --force*)",
      "Bash(npm publish*)",
      "Bash(git reset --hard*)"
    ]
  }
}

#!/bin/bash
FILES=(
  "src/legacy/userUtils.js"
  "src/legacy/paymentUtils.js"
  "src/legacy/emailUtils.js"
)

for file in "${FILES[@]}"; do
  echo "처리 중: $file"
  claude -p "
    $file을 TypeScript로 변환하고 ESM import/export로 교체해줘.
    변환 후 tsc --noEmit으로 컴파일 에러가 없는지 확인해줘.
    에러가 있으면 수정해줘. 에러 없이 완료해야 다음 파일로 넘어가.
  " --dangerously-skip-permissions

  if [ $? -ne 0 ]; then
    echo "오류 발생: $file 처리 중단"
    exit 1
  fi
done
echo "전체 변환 완료"

#!/bin/bash
# 보안 스캔 결과를 JSON으로 받아 critical 건수 확인
claude -p "
  src/ 폴더의 보안 취약점을 스캔하고 결과를 JSON으로만 출력해줘:
  {\"critical\": [\"설명1\", ...], \"major\": [...], \"minor\": [...]}
  JSON 외 다른 텍스트 없이 JSON만 출력할 것.
" > security-report.json

CRITICAL=$(cat security-report.json | jq '.critical | length')

if [ "$CRITICAL" -gt 0 ]; then
  echo "🚨 Critical 취약점 ${CRITICAL}개 발견!"
  curl -X POST "$SLACK_WEBHOOK" \
    -d "{\"text\": \"보안 스캔: Critical ${CRITICAL}건 발견. 즉시 확인 필요.\"}"
  exit 1
fi
echo "✅ Critical 취약점 없음"

# 1단계: 작업 브랜치 생성
git checkout -b feature/123-add-oauth-login

# 2단계: 프롬프트로 작업 위임
# "OAuth 로그인 기능을 추가해줘. GitHub과 Google을 지원해야 해.
#  기존 JWT 인증과 호환되어야 하고, 테스트도 작성해줘."

# 3단계: 의미 있는 단위마다 커밋 (완전 자동)
/commit
# → "feat(auth): add OAuth provider configuration"
# → "feat(auth): implement GitHub OAuth callback"
# → "test(auth): add OAuth integration tests"

# 4단계: PR 생성
/pr
# → gh pr create --title "feat: add OAuth login" --body "..."

# 5단계: 리뷰 반영
# "PR 코멘트 반영해줘" → 수정 후 /commit

# 6단계: Merge (Squash merge로 깔끔한 히스토리)
gh pr merge --squash

# Git 워크플로우
- 모든 작업은 feature 브랜치에서 시작. main 직접 push 절대 금지.
- 브랜치명: feature/[이슈번호]-[짧은-설명] (예: feature/123-add-oauth)
- 커밋: Conventional Commits 형식 (feat, fix, refactor, docs, test, chore)
- PR은 500줄 이하로 유지. 초과 시 분할 제안.
- Squash merge만 허용. Merge commit 금지.
- PR 없이 main에 직접 push 하지 말 것.

# 현재 작업 임시 저장 (미완성 파일 모두 보관)
git stash push -m "WIP: OAuth 로그인 구현 중"

# 긴급 버그 브랜치 생성
git checkout main
git checkout -b hotfix/critical-login-null-pointer

# 버그 수정 위임
# "로그인 시 NPE 발생하는 버그 수정해줘. 에러 로그: ..."
/commit
# → "fix(auth): handle null user session in login flow"

# main에 머지
git checkout main
git merge hotfix/critical-login-null-pointer

# 원래 작업으로 복귀 (보관해둔 미완성 파일 복원)
git checkout feature/123-add-oauth
git stash pop

# 테스트 원칙 (TDD)
- 구현 코드 작성 전 반드시 실패하는 테스트를 먼저 작성
- 테스트 없이 구현 코드 추가 금지 (예외 없음)
- Red → Green → Refactor 순서 엄수
- 테스트가 Green이 된 후에만 리팩토링 가능
- 테스트 프레임워크: Vitest
- 커버리지 최소 80% 유지
- 모든 public 함수에 단위 테스트 필수

/commit
# → "test(auth): add loginUser unit tests"
# → "feat(auth): implement loginUser function"

# 테스트 더블 정책
- 외부 API 호출 (Stripe, SendGrid, Slack): Mock 사용 — 실제 호출 절대 금지
- DB 쿼리: 단위 테스트는 In-memory DB 또는 Stub, 통합 테스트는 실제 DB
- 이메일 발송: Stub으로 발송 내용만 검증 (실제 발송 금지)
- 파일 시스템: 실제 임시 디렉토리 사용 (os.tmpdir())
- 시간 의존 코드 (new Date()): 시간을 인자로 주입받는 구조로 리팩토링 후 테스트

"PR #123의 각 파일을 검토하고 이슈마다 GitHub PR 인라인 코멘트를 직접 달아줘.
 각 코멘트에는:
 - 이슈 설명 (한국어)
 - 심각도 (critical/major/minor)
 - 수정 제안 코드 (있으면)

 보안 이슈는 반드시 포함. critical 이슈는 PR approval 거부."

# PR 생성 전에 자신이 만든 코드를 스스로 리뷰하게 하기
"방금 작성한 코드를 PR 제출 전에 스스로 리뷰해줘.
 엄격한 시니어 리뷰어 관점에서. 발견한 이슈들을 수정하고,
 수정 완료 후 /commit 해줘. 그 다음 /pr으로 PR 생성."

"PR #45는 820줄이야. 파일 레이어별로 나눠서 리뷰해줘:

 라운드 1: *.test.ts 파일만 — 테스트 품질과 커버리지
 라운드 2: services/ 레이어만 — 비즈니스 로직과 도메인 규칙
 라운드 3: controllers/ 레이어만 — API 설계와 HTTP 처리
 라운드 4: types/ 파일만 — 타입 정의와 인터페이스 설계

 각 라운드 결과를 표로 정리해줘:
 | 파일 | 발견 이슈 | 심각도 (critical/major/minor) |"

"이 PR을 CLAUDE.md의 코딩 컨벤션 기준으로 리뷰해줘.
 각 항목을 ✅ 통과 / ❌ 위반 / ⚠️ 확인필요 로 표시해줘:

 □ 함수명이 camelCase인가
 □ 클래스/컴포넌트명이 PascalCase인가
 □ any 타입 사용이 있는가 (있으면 반드시 ❌)
 □ console.log가 남아 있는가
 □ TODO 주석에 이슈 번호가 있는가 (예: TODO(#123))
 □ 에러 메시지가 한국어로 사용자 친화적인가
 □ 모든 public 함수에 JSDoc 주석이 있는가
 □ 테스트 파일명이 *.test.ts 형식인가

 위반 항목은 수정 방법도 함께 제시해줘."

"PR #45의 모든 리뷰 코멘트를 GitHub에서 가져와서:

 1단계: 심각도별로 분류
   - critical: 보안 취약점, 데이터 손실 가능성
   - major: 버그, 잘못된 로직
   - minor: 스타일, 네이밍, 가독성

 2단계: critical → major 순서로 모두 수정
   (minor는 별도 이슈 생성만)

 3단계: 수정 완료 후 /commit

 4단계: 수정한 파일들만 다시 셀프 리뷰
   (리뷰어 의도가 제대로 반영됐는지 확인)"

# Plan Mode 진입 후:
"UserRepository 인터페이스를 변경해서 비동기 메서드로 바꾸려고 해.
 변경 전에 이 인터페이스가 몇 군데에서 사용되는지,
 어떤 순서로 변경해야 하는지 계획만 세워줘."

# 예상 결과:
# "UserRepository는 12개 파일에서 사용됩니다.
#  변경 순서: repository → service → controller → test
#  예상 위험: AuthService에서 동기 호출을 가정하고 있어 수정 필요."
#
# 계획 검토 후 실행 결정

async function processOrder(orderId: string, userId: string) {
  // 1. 유효성 검사 (40줄)
  const user = await db.users.findById(userId);
  if (!user) throw new Error('User not found');
  if (user.status === 'banned') throw new Error('User is banned');
  const order = await db.orders.findById(orderId);
  if (!order) throw new Error('Order not found');
  if (order.userId !== userId) throw new Error('Not authorized');

  // 2. 결제 처리 (80줄)
  const cart = await db.carts.findByOrderId(orderId);
  const total = cart.items.reduce((sum, i) => sum + i.price, 0);
  const payment = await stripe.charge({ amount: total });

  // 3. 후처리 (80줄)
  await db.orders.update(orderId, { status: 'paid', paymentId: payment.id });
  await sendEmail(user.email, 'order-confirmation', { orderId });
  await analytics.track('order_completed', { userId, orderId, total });
}

async function processOrder(orderId: string, userId: string) {
  const { user, order } = await validateOrderAccess(orderId, userId);
  const payment = await chargeOrder(order);
  await completeOrder(order, user, payment);
}

async function validateOrderAccess(orderId: string, userId: string) { ... }
async function chargeOrder(order: Order) { ... }
async function completeOrder(order: Order, user: User, payment: Payment) { ... }

"이 프로젝트에 오늘 합류한 신규 개발자 관점으로 ONBOARDING.md를 작성해줘.
 포함할 내용:
 1. 개발 환경 셋업 (필수 도구, 버전, 설치 순서)
 2. 프로젝트 실행 방법 (로컬 개발, 테스트, 빌드)
 3. 폴더 구조와 각 폴더의 역할 (각 2줄 이내)
 4. 핵심 도메인 용어 사전 (코드에서 자주 나오는 비즈니스 용어)
 5. '첫 주에 반드시 읽어야 할 파일들' Top 5
 6. '절대 건드리면 안 되는 파일/폴더' 목록과 이유
 7. 신규 입사자가 자주 하는 실수 Top 3"

"이 프로젝트의 기술 스택을 처음 보는 사람도 이해하도록 설명해줘.
 각 기술이 '왜 선택됐는지', '어떤 문제를 해결하는지', '주요 대안이 무엇인지'도 포함해줘.
 package.json, docker-compose.yml, 설정 파일들을 근거로 분석해줘."

레이어 1: 로컬 Hooks (Claude Code hooks) — 즉각적, 개인적
  PreToolUse → 위험 명령 차단 (실행 전)
  PostToolUse → 파일 저장 시 Prettier 자동 실행
  PostToolUse → TypeScript 타입 체크
  → 문제 발견 즉시 차단, 커밋 전에 수정

레이어 2: GitHub Actions (PR 시) — 팀 전체, 강제적
  PR 생성 → Claude 자동 코드 리뷰
  PR 생성 → 린트 + 타입 체크
  PR 생성 → 단위 테스트 + 통합 테스트
  PR 생성 → 코드 커버리지 체크 (80% 미만 실패)
  PR 생성 → 보안 취약점 스캔
  → 모두 통과해야 Merge 허용

name: Claude Code Review
on:
  pull_request:
    types: [opened, synchronize]

jobs:
  claude-review:
    runs-on: ubuntu-latest
    permissions:
      pull-requests: write
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npm install -g @anthropic-ai/claude-code
      - name: Claude Review
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          claude -p "PR #${{ github.event.pull_request.number }}의 변경사항을 리뷰하고 GitHub PR에 인라인 코멘트를 달아줘. 보안 이슈는 critical로 표시." \
            --dangerously-skip-permissions

name: Auto Fix CI Failure
on:
  workflow_run:
    workflows: ["CI"]
    types: [completed]

jobs:
  analyze-and-fix:
    if: ${{ github.event.workflow_run.conclusion == 'failure' }}
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm install -g @anthropic-ai/claude-code
      - name: Analyze and Fix
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          claude -p "CI가 실패했어. 로그를 분석하고 원인을 파악해서 수정해줘. 수정 후 커밋까지 해줘." \
            --dangerously-skip-permissions

name: Auto Release
on:
  push:
    tags: ['v*']

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - run: npm install -g @anthropic-ai/claude-code
      - name: Generate Release Notes
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          claude -p "이 태그(${{ github.ref_name }})의 변경사항을 분석해서 CHANGELOG.md를 업데이트하고 GitHub Release를 생성해줘." \
            --dangerously-skip-permissions

name: Nightly Maintenance
on:
  schedule:
    - cron: '0 2 * * 1'  # 매주 월요일 오전 2시

jobs:
  maintenance:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm install -g @anthropic-ai/claude-code
      - name: Weekly Maintenance
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          claude -p "주간 유지보수: 1) npm audit 실행 후 high 취약점 수정 2) 오래된 의존성 업데이트 PR 생성 3) 스테일 이슈 레이블 정리" \
            --dangerously-skip-permissions

name: Safe Deploy
on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Deploy to Green slot
        run: kubectl apply -f k8s/green/

      - name: Claude Smoke Test
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          claude -p "
            Green 환경 (${{ env.GREEN_URL }})에 smoke test 실행해줘:
            1) /health 엔드포인트 200 응답 확인
            2) /api/auth/login API 응답시간 200ms 이하 확인
            3) DB 연결 상태 확인 (/api/health/db)
            4) 핵심 비즈니스 API 3개 응답 확인

            테스트 결과를 JSON으로 보고해줘.
            하나라도 실패하면 exit 1로 파이프라인 중단.
          " --dangerously-skip-permissions

      - name: Switch traffic to Green (smoke test 통과 시에만)
        if: success()
        run: |
          kubectl patch service myapp \
            -p '{"spec":{"selector":{"slot":"green"}}}'
          echo "✅ Green으로 트래픽 전환 완료"

      - name: Auto rollback on failure
        if: failure()
        run: |
          echo "❌ Smoke test 실패. Blue로 유지."
          kubectl rollout undo deployment/myapp

"다음 3개 모듈을 병렬로 개발해줘:
 - Agent A: src/auth/ 폴더에 JWT 제거, 세션 기반 인증 구현
 - Agent B: src/payment/ 폴더에 Stripe 웹훅 핸들러 구현
 - Agent C: src/notification/ 폴더에 이메일/Slack 알림 구현

 각 에이전트는 자신의 폴더만 수정할 것.
 src/types/는 내(리드)가 통합 후 업데이트할 것.
 tasks.md에 진행 상태를 업데이트하면서 작업할 것."

"프로덕션에서 간헐적으로 결제 실패가 발생해. 두 가설이 있어:
 - Agent A: 가설1 — Redis 캐시 동시 접근 레이스 컨디션 검증해줘
 - Agent B: 가설2 — Stripe 웹훅 타임아웃으로 중복 처리 검증해줘

 각자 재현 시나리오를 만들고 테스트해줘.
 먼저 재현한 쪽이 정답일 가능성이 높아.
 결과를 각자 보고해줘."

## 태스크 목록 (멀티 에이전트용)

## 규칙
- 태스크 시작 전 [진행중]으로 변경 (중복 방지)
- 완료 시 [완료]로 변경 후 다음 태스크 선택
- 자신의 담당 폴더 외 수정 금지
- src/types/ 수정 필요 시 리드 에이전트에게 위임

## 태스크

- [완료] [AGENT-A] src/auth/ — 세션 기반 인증 구현
- [진행중] [AGENT-B] src/payment/ — Stripe 웹훅 구현
- [ ] [AGENT-C] src/notification/ — 이메일 알림 구현
- [ ] [AGENT-C] test/integration/ — 통합 테스트 작성

## 공유 파일 (리드 에이전트만 수정)
- src/types/index.ts
- src/config/index.ts
- package.json

# 에이전트별 독립 작업 공간 생성 (각자 다른 브랜치)
git worktree add ../project-auth feature/auth-session
git worktree add ../project-payment feature/payment-stripe
git worktree add ../project-notify feature/notification

# 프롬프트: 각 worktree에 에이전트 배치
"3개 worktree에서 병렬로 작업해줘:
 - ../project-auth 폴더 (feature/auth-session 브랜치): 세션 인증 구현
 - ../project-payment 폴더 (feature/payment-stripe 브랜치): Stripe 웹훅 구현
 - ../project-notify 폴더 (feature/notification 브랜치): 알림 시스템 구현

 각자 자신의 worktree에서만 작업.
 공유 파일(types/)은 메인 브랜치에서 내가 직접 통합할 예정.
 완료 시 PR 생성 후 보고해줘."

# 완료 후 정리
git worktree remove ../project-auth
git worktree remove ../project-payment
git worktree remove ../project-notify

Stage 1 — 병렬 탐색 (동시 실행):
  Explore A: 인증 코드 분석
  Explore B: API 엔드포인트 분석
  Explore C: 테스트 현황 분석
  ↓ (모두 완료 대기)

Stage 2 — 순차 통합/설계 (사람 개입 포함):
  Plan: 3개 분석 결과 취합 → 구현 전략 수립
  → 나에게 계획 보고 후 승인 대기
  ↓ (승인 후)

Stage 3 — 병렬 구현 (동시 실행):
  Agent A: 인증 모듈 구현 (auth/ worktree)
  Agent B: 결제 모듈 구현 (payment/ worktree)
  ↓ (모두 완료 대기)

Stage 4 — 순차 통합 테스트:
  통합 테스트 실행 → 문제 수정 → PR 생성

"4단계 파이프라인으로 진행해줘:

 Stage 1 (병렬): Explore 에이전트 3개로 인증/API/테스트 현황 동시 분석
 Stage 2 (순차): 분석 완료 후 나에게 구현 계획 보고. 내 승인 대기.
 Stage 3 (병렬): 승인 후 auth/, payment/ 모듈 동시 구현
 Stage 4 (순차): 모두 완료 후 통합 테스트 실행

 각 Stage 완료 시 진행 상황 보고해줘.
 Stage 2에서는 반드시 멈추고 내 승인을 기다려."

1주차: 읽기, 분석, 제안만 (실행 없음)
  → Claude의 판단 방식을 관찰

2주차: 단일 파일 수정 (검토 후 적용)
  → 예상 범위 내에서 작업하는지 확인

3주차: 멀티 파일 수정 (Plan Mode 필수)
  → 더 복잡한 작업으로 신뢰 범위 확장

4주차: Auto Mode 활용 (검증된 범위에서만)
  → 자율 실행 범위를 점진적으로 확대