.claude 세팅, 왜 해야 하는가?

# CLAUDE.local.md (나만의 설정)

## 내 선호
- 설명은 한국어로
- 커밋 메시지도 한국어

## 현재 작업 컨텍스트
- 작업 중: 결제 모듈 리팩토링 (#1234)
- 주의: payment-gateway.ts 레거시 호환 유지

## 실험
- Vitest property-based testing 시도 중

프로젝트 루트/
├── CLAUDE.md                      # 팀 규칙 (자동 로드)
├── .claude/
│   ├── settings.json              # deny/allow 정책
│   ├── rules/                     # @import 모듈
│   │   ├── architecture.md
│   │   ├── coding-style.md
│   │   └── testing.md
│   └── skills/                    # OMC에 "없는" 프로젝트 전용만
│       └── proj-db-migrate/
│           └── SKILL.md
│
├── CLAUDE.local.md                # 개인 (gitignore)
└── .claude/settings.local.json    # 개인 오버라이드 (gitignore)

~/.claude/                         # 개인 글로벌
├── CLAUDE.md                      # 내 전체 프로젝트 공통 선호
├── settings.json
└── skills/                        # OMC 스킬 + 내 커스텀 스킬
    ├── (OMC: plan, prd, exec, verify, fix ...)
    └── (내 커스텀 스킬들)
    # → 이건 각자의 스타일/자유도

# CLAUDE.md

## 프로젝트 개요
SaaS 웹 애플리케이션. pnpm workspace 모노레포.

## 기술 스택
- Next.js 16 (App Router + React Server Components)
- React 19, TypeScript 5 (strict mode)
- Tailwind CSS 4 + shadcn/ui (new-york 스타일)
- Zustand (클라이언트 상태) + TanStack React Query v5 (서버 상태)
- Axios custom wrapper: src/libs/http.ts
- NextAuth v4 (JWT strategy)
- 패키지 매니저: pnpm

## 핵심 명령
- 빌드: pnpm build
- 개발: pnpm dev
- 린트: pnpm lint
- 타입체크: pnpm typecheck
- 테스트: pnpm test

## 폴더 구조 (주요)
- src/app/          → App Router 페이지 & 레이아웃 (RSC 기본)
- src/components/   → 재사용 컴포넌트 (shadcn 기반)
- src/libs/         → 유틸리티 (http.ts, auth.ts 등)
- src/hooks/        → 커스텀 훅
- src/stores/       → Zustand 스토어
- src/types/        → 공유 타입 정의

## 규칙
- TypeScript strict / const 우선, var 금지 / any 금지
- 서버 컴포넌트 기본, 'use client' 최소화
- API 호출은 반드시 http.ts 래퍼 사용 (fetch 직접 사용 금지)

## 상세 규칙 (필요 시 로드)
@.claude/rules/architecture.md
@.claude/rules/coding-style.md
@.claude/rules/state-management.md
@.claude/rules/testing.md

## 금지 사항
- .env, .env.*, secrets 파일 내용 출력/커밋 금지
- console.log 커밋 금지 (디버깅 후 제거)
- pages/ 디렉터리 사용 금지 (App Router만)
- CSS-in-JS / CSS 모듈 금지 (Tailwind + shadcn만)

# 아키텍처 규칙

## 라우팅
- Next.js App Router만 사용 (pages/ 절대 금지)
- 페이지 컴포넌트는 React Server Component가 기본
- 클라이언트 로직 필요 시 별도 Client Component로 분리, 'use client' 선언
- 'use client'는 가능한 트리 하단(leaf)에서만 — 페이지 전체를 client로 만들지 않기

## API 레이어
- Route Handler: src/app/api/ 하위에 RESTful 경로로 구성
- 요청/응답 스키마는 Zod로 정의, 런타임 검증 필수
- API 호출(클라이언트→서버)은 반드시 src/libs/http.ts 래퍼 사용
  - http.get(), http.post(), http.put(), http.delete()
  - 인터셉터에서 토큰 자동 주입 / 에러 핸들링 처리됨

## 인증
- NextAuth v4, JWT strategy
- 서버 컴포넌트: getServerSession(authOptions)
- 클라이언트 컴포넌트: useSession()
- Route Handler: getServerSession(authOptions)
- 미들웨어(src/middleware.ts)에서 보호 경로 체크

## 컴포넌트 구조
- shadcn/ui 커스터마이징: src/components/ui/
- 비즈니스 컴포넌트: src/components/{feature}/
- 레이아웃: src/app/(그룹)/layout.tsx

# 상태 관리 규칙

## 원칙: 서버 상태와 클라이언트 상태를 명확히 분리

### 서버 상태 = TanStack React Query v5
- API에서 받아오는 모든 데이터는 TanStack Query로 관리
- queryKey 컨벤션: [도메인, 식별자, 파라미터]
  (예: ['users', userId, { page }])
- src/hooks/ 하위에 도메인별 커스텀 훅으로 래핑
  - 예: useUser(id), useUsers(params), useCreateUser()
- useMutation 사용 후 invalidateQueries로 캐시 동기화

### 클라이언트 상태 = Zustand
- UI 상태, 폼 상태, 로컬 전용 상태만 Zustand 사용
- 스토어 위치: src/stores/{storeName}.ts
- 슬라이스 패턴 사용: 스토어가 커지면 슬라이스로 분리

### 사용하지 않는 것
- useState로 서버 데이터 관리 금지 → TanStack Query 사용
- Redux, Recoil, Jotai 등 다른 상태관리 라이브러리 금지
- Context API로 전역 상태 관리 금지 (테마/로케일 등 예외)

# 코딩 스타일 규칙

## TypeScript
- strict mode 필수
- any 금지 → unknown + 타입 가드, 또는 구체 타입
- interface 우선, type alias는 유니온/유틸리티에 사용
- 공유 타입: src/types/{domain}.ts

## 네이밍
- 파일: kebab-case (user-profile.tsx)
- 컴포넌트: PascalCase (UserProfile)
- 함수/변수: camelCase
- 상수: UPPER_SNAKE_CASE
- 타입/인터페이스: PascalCase, I 접두사 금지

## 컴포넌트
- named export 기본 (page.tsx, layout.tsx, route.ts만 default export)
- Props 타입은 컴포넌트 바로 위에 interface로 정의
- 이벤트 핸들러: handle{Event}

## import 순서
1. React / Next.js
2. 외부 라이브러리
3. @/ 내부 모듈
4. 상대 경로 (./)
- 그룹 사이에 빈 줄

## 스타일
- Tailwind CSS 4 유틸리티 클래스만 사용
- cn() 유틸리티로 조건부 클래스 병합
- 인라인 style 금지, CSS 모듈 금지

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",

  "permissions": {
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./.env.local)",
      "Read(./secrets/**)",
      "Bash(curl *)",
      "Bash(wget *)",
      "Bash(ssh *)",
      "Bash(rm -rf *)",
      "Bash(npx *)",
      "Bash(pnpm dlx *)"
    ],
    "allow": [
      "Bash(pnpm lint)",
      "Bash(pnpm lint:fix)",
      "Bash(pnpm typecheck)",
      "Bash(pnpm test *)",
      "Bash(pnpm build)",
      "Bash(pnpm dev)",
      "Bash(pnpm format)",
      "Bash(git status *)",
      "Bash(git diff *)",
      "Bash(git log *)"
    ]
  }
}

# 테스트 규칙

## 도구
- Vitest + @testing-library/react + MSW

## 원칙
- 새 기능/버그 수정 시 관련 테스트 작성 필수
- 테스트 파일 위치: 대상 파일 옆에 {name}.test.ts(x)

## 완료 기준 (DOD)
- pnpm test 통과
- pnpm lint 통과
- pnpm typecheck 통과

---
name: proj-db-migrate
description: Prisma 마이그레이션 생성/적용/시드 업데이트를 안전하게 수행
allowed-tools: Bash(pnpm prisma *),Bash(pnpm db:*),Read,Write
---

# DB Migration (프로젝트 전용)

OMC의 범용 스킬과 겹치지 않는, 우리 프로젝트 고유 워크플로.

## 절차
1. prisma/schema.prisma 변경사항 확인
2. pnpm prisma migrate dev --name {description} 실행
3. 생성된 마이그레이션 SQL 파일 검토
4. prisma/seed.ts 업데이트 필요 여부 확인
5. pnpm db:seed 실행 (필요 시)
6. pnpm typecheck 으로 Prisma Client 타입 정합성 확인

## 주의
- 프로덕션 DB에는 절대 직접 실행 안 함
- 마이그레이션 이름: kebab-case (add-user-avatar)