Ch9. Agentic 개발 체계

<!-- CLAUDE.md (루트) -->
# 프로젝트 개요
Turborepo 모노레포. Yarn 4 + Next.js 16 + Vercel 배포.

## 공통 명령어
- `yarn dev` — 전체 개발 서버
- `turbo run build --filter=앱명` — 특정 앱 빌드
- `turbo run test` — 전체 테스트

## 아키텍처
apps/ → 배포 단위, packages/ → 재사용 단위.
의존성 방향: types → utils/db(Prisma) → ui → apps.
API는 각 Next.js 앱의 API Routes + Server Actions로 처리.

## 주요 패키지
- @acme/db — Prisma 클라이언트 (스키마: packages/db/prisma/)
- @acme/ui — 공유 UI 컴포넌트
- @acme/utils — 유틸리티 함수

## Git 규칙
- 커밋 메시지: conventional commits (feat/fix/chore)
- 커밋/푸시 금지: 명시적 요청 전까지 실행하지 않는다

<!-- apps/web/CLAUDE.md -->
# apps/web (메인 서비스)
Next.js App Router. 포트 3000.

## 라우팅
- /(public) — 공개 페이지
- /(auth) — 인증 필요 (proxy.ts에서 경량 redirect 처리)
- /api/* — API Routes (외부 웹훅, 서드파티 연동)

## 데이터 접근
- DB: import { getDb } from '@acme/db' (Prisma lazy singleton)
- 뮤테이션: Server Actions 우선, 외부 연동만 API Routes
- 스키마 변경: packages/db/prisma/schema.prisma 수정 후 prisma migrate dev

## 환경 변수
- DATABASE_URL: Neon PostgreSQL (서버리스)
- NEXT_PUBLIC_APP_URL: 앱 URL

# worktree 생성
git worktree add ../monorepo-web -b feat/web-redesign
git worktree add ../monorepo-admin -b feat/admin-rbac

# 세션 1: web 작업
cd ../monorepo-web && claude

# 세션 2: admin 작업
cd ../monorepo-admin && claude

# 세션 3: 메인 레포에서 패키지 작업
cd ../monorepo && claude

<!-- CLAUDE.md에 서브에이전트 가이드라인 추가 -->
## 에이전트 활용 가이드
- 코드 탐색: Task(subagent_type=Explore) 사용
- 구현 전 설계: Task(subagent_type=Plan) 사용
- 빌드/테스트: Task(subagent_type=Bash) 사용
- 3개 이상 파일 수정: TodoWrite로 진행 상황 추적

// .claude/settings.json
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "command": "prettier --write $CLAUDE_FILE_PATH 2>/dev/null || true"
      }
    ],
    "PreToolUse": [
      {
        "matcher": "Bash",
        "command": "echo '$CLAUDE_TOOL_INPUT' | jq -r '.command' | grep -qE '(rm -rf /|DROP TABLE|format c:)' && echo 'BLOCK: 위험한 명령 차단' && exit 1 || exit 0"
      }
    ]
  }
}

# 1. 피처 브랜치별 worktree 생성
git worktree add ../proj-feat-auth -b feat/auth
git worktree add ../proj-feat-payment -b feat/payment

# 2. 각 worktree에서 Claude Code 세션 시작
# (tmux/screen으로 세션 관리)
tmux new-session -s auth -c ../proj-feat-auth "claude"
tmux new-session -s payment -c ../proj-feat-payment "claude"

# 3. 완료 후 worktree 정리
git worktree remove ../proj-feat-auth
git worktree remove ../proj-feat-payment

# Context Pack: 결제 webhook 수정

## 읽을 파일
- apps/web/app/api/webhooks/paddle/route.ts
- packages/db/prisma/schema.prisma
- packages/billing/src/paddle.ts

## 지켜야 할 규칙
- webhook raw body 검증을 유지한다
- 같은 event id는 idempotent하게 처리한다
- 결제 상태 변경은 audit log를 남긴다

## 검증 명령
- turbo run test --filter=web...
- turbo run typecheck --filter=web...