싱글 프로젝트
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

CLAUDE.md
 ├── @.claude/rules/code-style.md
 ├── @.claude/rules/testing.md
 └── @.claude/rules/git-workflow.md


모노레포 (pnpm workspace)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

CLAUDE-template(Root).md          ← 루트 (packages/ 상위)
 └── @.claude/rules/root-code-style.md

CLAUDE-template(Client).md       ← packages/client/CLAUDE.md
 └── @.claude/rules/client-patterns.md

CLAUDE-template(Server).md       ← packages/server/CLAUDE.md
 └── @.claude/rules/server-patterns.md


Java 백엔드
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

AGENTS(java-back).md
 └── @docs/patterns.md

프로젝트 루트/
├── CLAUDE.md                         ← CLAUDE-template(Root).md 기반
│   (공통: 언어 규칙, 조사 원칙, Git 가드레일)
│
├── packages/client/CLAUDE.md         ← CLAUDE-template(Client).md 기반
│   (추가: Server/Client 컴포넌트 규칙, 스타일링, 테스트)
│
├── packages/server/CLAUDE.md         ← CLAUDE-template(Server).md 기반
│   (추가: Request flow, Prisma 가드레일, 에러 핸들링)
│
└── CLAUDE.local.md                   ← 개인 설정 (.gitignore에 포함)
    (OS, Node 버전, 개인 선호)

루트 CLAUDE.md → 패키지 CLAUDE.md → CLAUDE.local.md

복사할 파일:
  CLAUDE.md              → 프로젝트 루트/CLAUDE.md
  code-style.md          → .claude/rules/code-style.md
  testing.md             → .claude/rules/testing.md
  git-workflow.md        → .claude/rules/git-workflow.md
  CLAUDE.local.md        → 프로젝트 루트/CLAUDE.local.md (.gitignore 추가)

복사할 파일:
  CLAUDE-template(Root).md     → 프로젝트 루트/CLAUDE.md
  CLAUDE-template(Client).md   → packages/client/CLAUDE.md
  CLAUDE-template(Server).md   → packages/server/CLAUDE.md
  root-code-style.md           → .claude/rules/root-code-style.md
  client-patterns.md           → .claude/rules/client-patterns.md
  server-patterns.md           → .claude/rules/server-patterns.md
  git-workflow.md              → .claude/rules/git-workflow.md
  CLAUDE.local.md              → 프로젝트 루트/CLAUDE.local.md

복사할 파일:
  AGENTS(java-back).md   → 프로젝트 루트/AGENTS.md (또는 CLAUDE.md)
  patterns.md            → docs/patterns.md
  git-workflow.md        → .claude/rules/git-workflow.md

복사할 파일:
  AGENTS-template.md     → 프로젝트 루트/AGENTS.md (빈 템플릿에서 시작)
  AGENTS-Guide.md        → 작성 가이드로 참고 (프로젝트에 포함하지 않음)

참고 파일:
  skill-template.md      → ~/.claude/skills/ 또는 프로젝트 .claude/skills/에 작성

사용자: "로그인이 안 돼"
Claude: (가정) 아마 토큰 만료 문제일 것이다 → 토큰 갱신 로직 구현
사용자: "아니, 비밀번호 해싱이 문제야"
Claude: 토큰 갱신 코드 위에 해싱 로직을 덧붙임 → 꼬인 코드
사용자: "처음부터 다시 해줘"

┌─────────────────────────────────────────────────────────┐
│ Layer 4: 사용자 습관 (가장 효과적)                            │  
│  → 구체적 프롬프트, 단일턴 완결, 중간 확인                       │
├─────────────────────────────────────────────────────────┤
│ Layer 1: CLAUDE.md 지시사항                                │
│  → 가정 금지, 확인 우선, 복구 프로토콜                          │
├─────────────────────────────────────────────────────────┤
│ Layer 2: Hooks (자동 강제)                                 │
│  → Stop 시 검증, 위험 명령 차단, 포맷팅                        │
├─────────────────────────────────────────────────────────┤ 
│ Layer 3: 작업 구조화                                       │
│  → Plan → Task → Checkpoint → Verify                    │
└─────────────────────────────────────────────────────────┘

사용자: "로그인이 안 돼"

[Investigation Rules 적용 전]
Claude: 토큰 만료 문제 같네요 → 바로 토큰 갱신 코드 작성 (가정)

[Investigation Rules 적용 후]
Claude: 먼저 관련 파일을 확인하겠습니다.
  → src/auth/login.ts 읽기
  → src/middleware/auth.ts 읽기
  → 에러 로그 확인
  → "bcrypt 버전 불일치로 해싱 결과가 다릅니다" (사실 기반 진단)

Turn 1: 사용자 "회원가입 기능 만들어줘"
Turn 2: Claude "계획: 1) 스키마 2) API 3) 폼 4) 검증 5) 테스트" → 승인 요청
Turn 3: 사용자 "좋아, 진행해"
Turn 5: Claude "현재 상태: 스키마와 API 완료, 폼 작업 중"
Turn 7: Claude "현재 상태: 폼 완료, 이메일 인증도 추가할까요?" → 확인 요청
         (원래 요청에 이메일 인증은 없었음 → drift 감지)

Turn 1: "회원가입 기능 만들어줘"
Turn 3: 스키마 추가
Turn 5: API 추가... 그런데 이메일 인증도 필요할 것 같아서 추가
Turn 7: OAuth 로그인도 있으면 좋겠다... 추가
Turn 9: 사용자 "나는 간단한 회원가입만 원했는데 왜 이렇게 복잡해?"

시도 1: 환경변수 문제라고 가정 → .env 수정 → 실패
시도 2: 환경변수 로딩 순서 변경 → 실패

[Recovery Protocol 발동]
Claude: "2번 실패했습니다. 접근을 바꾸겠습니다."
  → 에러 스택 트레이스를 처음부터 다시 분석
  → 실제 원인: import 순서로 인한 circular dependency

시도 1: 환경변수 수정 → 실패
시도 2: 환경변수 다른 방식 → 실패
시도 3: 환경변수 또 다른 방식 → 실패
시도 4: 환경변수 라이브러리 교체 → 실패
시도 5: ...계속 같은 방향... (wrong turn → lost)

[Compact 전]
Turn 1-20: 복잡한 리팩토링 진행 중
  - CLAUDE.md: Investigation Rules, Recovery Protocol 적용 중
  - Task 목록: 5개 중 3개 완료
  - 중간 결과: src/utils/refactored.ts에 저장

[Compact 발생 → 대화 내용 압축]

[Compact 후]
  - CLAUDE.md: 여전히 전문 주입됨 → 규칙 유지
  - Task 목록: 여전히 "5개 중 3개 완료" 상태 유지
  - 중간 결과: 파일에 있으므로 읽을 수 있음
  - ⚠️ 유실: "왜 이 방식을 선택했는지"의 판단 근거

Turn 1: 사용자 "로그인 버그 수정해줘"
Turn 5: Claude "수정 완료했습니다"
  → [Stop Hook 실행]
  → Claude 컨텍스트에 "원래 요청과 결과물이 일치하는지 검증하세요" 주입
  → Claude: (자체 검증) 원래 요청은 로그인 버그 수정... 실제로 수정한 것은... 일치함

Turn 1: "로그인 버그 수정해줘"
Turn 5: OAuth 연동 코드를 작성하고 있음
  → [Stop Hook 실행]
  → "원래 요청과 결과물이 일치하는지 검증하세요"
  → Claude: 원래 요청은 "로그인 버그 수정"인데 OAuth 연동을 하고 있었습니다. 
            궤도를 벗어났네요. 원래 요청으로 돌아가겠습니다.

Turn 3: Claude가 src/auth/login.ts 수정
  → [PostToolUse Hook 실행]
  → tsc --noEmit 실행
  → 타입 에러 2개 발견
  → Claude 컨텍스트에 에러 메시지 주입
  → Claude: 타입 에러를 즉시 수정 (잘못된 방향으로 진행하기 전에 catch)

Turn 3: login.ts 수정 (타입 에러 발생, 모름)
Turn 5: auth.ts 수정 (login.ts의 타입 에러 위에 추가 코드)
Turn 7: middleware.ts 수정 (에러 누적)
Turn 9: "왜 빌드가 안 되지?" → 3개 파일의 꼬인 타입 에러를 한꺼번에 수정해야 함

Claude: (잘못된 방향으로) 테이블을 다시 만들자 → DROP TABLE todos
  → [PreToolUse Hook 실행]
  → "DROP TABLE" 감지 → exit 2
  → Bash 실행 자체가 차단됨
  → Claude: "위험한 명령어가 차단되었습니다. 다른 접근을 시도하겠습니다."

[Plan 단계] — 무엇을 할지 정의
    ↓
[Task 분해] — 단계별로 나누기
    ↓
[실행 + Checkpoint] — 각 단계 완료 시 확인
    ↓
[Verify] — 전체 결과를 원래 요청과 비교

사용자: "회원가입 기능을 만들어줘"

[Plan]
Claude: 다음 계획으로 진행하겠습니다:
  1. User 모델에 email, password 필드 추가
  2. POST /api/auth/register 엔드포인트 구현
  3. 회원가입 폼 컴포넌트 생성
  4. 입력 검증 (Zod 스키마)
  5. 테스트 작성
  승인하시겠습니까?

사용자: "승인"

[Task 1 완료 → Checkpoint]
Claude: "User 모델 완료. 다음 단계: API 엔드포인트"

[Task 3 완료 → Checkpoint]  
Claude: "폼 컴포넌트 완료. 현재 소셜 로그인도 추가할 수 있는데, 범위에 포함할까요?"
  → drift 감지 — 원래 요청에 소셜 로그인은 없었음

[Verify]
Claude: "모든 단계 완료. 원래 요청 '회원가입 기능'에 대해:
  ✅ User 모델, ✅ API, ✅ 폼, ✅ 검증, ✅ 테스트"

[무엇을] + [어디서] + [어떤 상태인지] + [기대 결과]

사용자: "현재 상태 요약해줘"
Claude: "원래 요청: X. 현재 진행: Y 완료, Z 진행 중. 범위 변경 없음."
사용자: "좋아, 계속해"