Claude Code CLAUDE.md 작성법 — 프로젝트별 AI 맞춤 설정 완전 가이드

1
2
3
4
5

## 프로젝트 개요

이 프로젝트는 Next.js 14 (App Router) + TypeScript + Prisma + PostgreSQL로 구성된
SaaS 플랫폼입니다. 사용자 인증은 NextAuth.js를 사용하며, 스타일링은 Tailwind CSS를 사용합니다.
배포는 Vercel에서 이루어집니다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22

## 개발 명령어

\`\`\`bash
# 개발 서버
npm run dev

# 빌드
npm run build

# 테스트
npm test
npm test -- --watch     # 워치 모드
npm test -- --coverage  # 커버리지

# 린트
npm run lint
npm run lint:fix

# 데이터베이스
npx prisma migrate dev  # 마이그레이션 실행
npx prisma studio       # DB GUI 열기
\`\`\`

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

## 코딩 컨벤션

- 파일명: kebab-case (예: user-profile.tsx)
- 컴포넌트: PascalCase (예: UserProfile)
- 함수/변수: camelCase
- 상수: UPPER_SNAKE_CASE
- TypeScript strict 모드 사용 (any 타입 금지)
- 에러 처리: try/catch보다 Result 타입 선호
- 비동기: async/await 사용 (Promise.then 체인 지양)
- 임포트 순서: 외부 라이브러리 → 내부 모듈 → 타입

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

## 아키텍처 노트

- `src/app`: Next.js App Router 페이지
- `src/components`: 재사용 가능한 UI 컴포넌트
- `src/lib`: 비즈니스 로직 및 유틸리티
- `src/server`: 서버 전용 코드 (DB 쿼리, API 로직)
- `prisma/schema.prisma`: 데이터베이스 스키마

상태 관리는 Zustand를 사용합니다. Redux는 사용하지 않습니다.
API 라우트는 `src/app/api` 아래에 위치합니다.
서버 컴포넌트와 클라이언트 컴포넌트를 명확히 구분합니다.

1
2
3
4
5
6
7

## 금지 사항

- `prisma/migrations` 폴더 직접 수정 금지
- `.env` 파일 수정 금지 (`.env.example`은 가능)
- `package.json`의 메이저 버전 업그레이드 금지 (논의 후 진행)
- `src/types/generated` 폴더 수정 금지 (자동 생성)
- 프로덕션 데이터베이스에 직접 연결 금지

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47

# CLAUDE.md

## 프로젝트 개요

Next.js 14 App Router + TypeScript + Tailwind CSS + Prisma + PostgreSQL로 구성된
B2B SaaS 플랫폼입니다. 다중 테넌트 아키텍처를 사용하며 각 조직은 독립된 데이터를 가집니다.

## 개발 명령어

\`\`\`bash
npm run dev         # 개발 서버 (포트 3000)
npm run build       # 프로덕션 빌드
npm test            # Jest 테스트
npm run lint        # ESLint 검사
npm run type-check  # TypeScript 타입 검사
npx prisma migrate dev  # DB 마이그레이션
\`\`\`

## 디렉터리 구조

- `src/app`: 페이지 및 API 라우트
- `src/components/ui`: 기본 UI 컴포넌트 (shadcn/ui 기반)
- `src/components/features`: 기능별 컴포넌트
- `src/lib/db.ts`: Prisma 클라이언트 싱글톤
- `src/lib/auth.ts`: NextAuth.js 설정
- `src/server/`: 서버 전용 비즈니스 로직

## 코딩 컨벤션

- TypeScript strict 모드, any 타입 사용 금지
- 컴포넌트는 기본 export, 유틸리티는 named export
- 서버 컴포넌트 기본, 클라이언트 컴포넌트는 'use client' 명시
- API 라우트는 NextResponse 사용
- 에러는 항상 로깅 후 사용자 친화적 메시지 반환

## 테스트

- 단위 테스트: Jest + Testing Library
- E2E 테스트: Playwright (tests/e2e/)
- 새 기능 추가 시 단위 테스트 필수

## 금지 사항

- prisma/migrations 직접 수정 금지
- .env 수정 금지 (.env.example만 수정)
- console.log 프로덕션 코드에 남기기 금지
- src/types/generated/ 수동 수정 금지 (prisma generate로 재생성)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50

# CLAUDE.md

## 프로젝트 개요

Python 3.11 + FastAPI + SQLAlchemy 2.0 + PostgreSQL로 구성된 REST API 서버입니다.
비동기 처리를 기본으로 하며, Alembic으로 마이그레이션을 관리합니다.

## 개발 명령어

\`\`\`bash
# 가상환경 활성화
source venv/bin/activate  # Linux/macOS
venv\Scripts\activate     # Windows

# 개발 서버
uvicorn main:app --reload --port 8000

# 테스트
pytest
pytest --cov=app tests/      # 커버리지

# 린트 및 포맷
ruff check .
ruff format .

# 마이그레이션
alembic upgrade head
alembic revision --autogenerate -m "설명"
\`\`\`

## 코딩 컨벤션

- 타입 힌트 필수 (Python 3.11+ 스타일)
- 비동기 함수는 async def 사용
- 의존성 주입은 FastAPI Depends 활용
- 모델: SQLAlchemy ORM (raw SQL 지양)
- 스키마: Pydantic v2

## 아키텍처

- `app/api/`: 라우터 (엔드포인트만, 비즈니스 로직 없음)
- `app/services/`: 비즈니스 로직
- `app/models/`: SQLAlchemy 모델
- `app/schemas/`: Pydantic 스키마

## 금지 사항

- alembic/versions/ 수동 수정 금지
- .env 파일 수정 금지 (.env.example만 가능)
- 동기 DB 쿼리 사용 금지 (항상 async session 사용)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

# CLAUDE.md (루트)

## 모노레포 구조

pnpm workspaces 기반 모노레포입니다.

- `apps/web`: Next.js 웹 앱
- `apps/api`: FastAPI 백엔드
- `packages/ui`: 공유 UI 컴포넌트
- `packages/types`: 공유 타입 정의

## 공통 명령어

\`\`\`bash
pnpm install        # 전체 의존성 설치
pnpm build          # 전체 빌드
pnpm test           # 전체 테스트
pnpm -F web dev     # 웹만 개발 서버
pnpm -F api dev     # API만 개발 서버
\`\`\`

## 공통 컨벤션

- 패키지 간 타입은 packages/types에서 공유
- UI 컴포넌트는 packages/ui에서 관리

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

# CLAUDE.md (web)

루트 CLAUDE.md의 공통 설정을 따릅니다.
이 섹션은 web 앱 특화 설정입니다.

## 개발 명령어

\`\`\`bash
pnpm dev    # 포트 3000
pnpm build
pnpm test
\`\`\`

## 특이사항

- App Router 전용 (Pages Router 코드 작성 금지)
- i18n: next-intl 사용 (messages/ 폴더)

1
2
3
4
5
6
7

# 나쁜 예
테스트를 실행하려면 npm test를 실행하세요.

# 좋은 예
\`\`\`bash
npm test
\`\`\`

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

## 코드 패턴 예시

API 라우트 기본 구조:
\`\`\`typescript
export async function GET(request: Request) {
  try {
    const data = await getData()
    return NextResponse.json(data)
  } catch (error) {
    console.error(error)
    return NextResponse.json({ error: '서버 오류' }, { status: 500 })
  }
}
\`\`\`

1
2
3
4
5
6

## 환경 정보

- Node.js: 20.x (LTS)
- npm: 10.x
- TypeScript: 5.3
- Next.js: 14.2