CLAUDE.md 완전 가이드

CLAUDE.md란?

CLAUDE.md는 Anthropic의 Claude Code가 대화를 시작할 때 자동으로 읽는 마크다운 파일이다. 프로젝트의 빌드 명령어, 코드 스타일, 테스트 방법, 아키텍처 결정 등 Claude가 코드만 읽어서는 알 수 없는 정보를 담는다.

디렉토리 구조 예시

실제 프로젝트에서 CLAUDE.md와 관련 파일을 배치하는 패턴

# 일반 프로젝트
my-project/
├── CLAUDE.md              # 프로젝트 전체 규칙 (git 커밋)
├── CLAUDE.local.md        # 개인 설정 (.gitignore)
├── .claude/
│   └── skills/            # 재사용 가능한 스킬 파일
│       ├── deploy.md
│       └── db-migrate.md
├── src/
│   ├── frontend/
│   │   └── CLAUDE.md      # 프론트엔드 전용 규칙
│   └── backend/
│       └── CLAUDE.md      # 백엔드 전용 규칙
└── ...

# 모노레포
monorepo/
├── CLAUDE.md              # 공통 규칙 (린트, 커밋 컨벤션)
├── packages/
│   ├── web/
│   │   └── CLAUDE.md      # React 규칙, 번들러 설정
│   ├── api/
│   │   └── CLAUDE.md      # Express 규칙, DB 마이그레이션
│   └── shared/
│       └── CLAUDE.md      # 공유 라이브러리 규칙
└── ...

# 글로벌 설정 (홈 디렉토리)
~/.claude/
├── CLAUDE.md              # 모든 프로젝트에 적용
└── skills/                # 글로벌 스킬

실전 예제

프로젝트 유형별 CLAUDE.md 작성 예제

React + TypeScript 프로젝트

# CLAUDE.md

## 빌드 & 테스트
- dev: pnpm dev (Vite, port 5173)
- build: pnpm build
- test: pnpm vitest run
- 단일 테스트: pnpm vitest run src/hooks/useAuth.test.ts
- lint: pnpm eslint . --fix
- type check: pnpm tsc --noEmit

## 코드 스타일
- 컴포넌트는 named export만 사용 (default export 금지)
- 스타일은 CSS Modules (.module.css) 사용, styled-components 금지
- 상태 관리는 Zustand, React Context 금지
- API 호출은 반드시 src/api/ 디렉토리의 함수를 통해서만
- 에러 바운더리는 src/components/ErrorBoundary.tsx 사용

## 아키텍처
- src/features/에 도메인별 디렉토리 (feature-based architecture)
- 공유 컴포넌트는 src/components/ui/
- 훅은 src/hooks/, 유틸은 src/utils/
- 라우팅은 React Router v6, createBrowserRouter 사용

## 중요
- IMPORTANT: PR 전에 반드시 pnpm tsc --noEmit 통과 확인
- 새 페이지 추가 시 src/router.tsx에 라우트 등록 필수

Python FastAPI 프로젝트

# CLAUDE.md

## 환경
- Python 3.12 + uv (pip 사용 금지)
- 의존성 추가: uv add 패키지명
- dev 서버: uv run uvicorn app.main:app --reload
- test: uv run pytest -x -q
- 단일 테스트: uv run pytest tests/test_auth.py -x -q

## 코드 스타일
- 타입 힌트 필수 (mypy strict 모드)
- Pydantic v2 모델 사용, dataclass 금지
- async def 기본, sync는 CPU-bound 작업만
- 로깅은 structlog 사용, print 금지

## DB
- SQLAlchemy 2.0 + async session
- 마이그레이션: alembic revision --autogenerate -m "설명"
- IMPORTANT: 마이그레이션 후 반드시 uv run alembic upgrade head 실행

@import를 활용한 모듈화

# CLAUDE.md — @import로 다른 파일을 참조할 수 있다

## 공통 규칙
이 프로젝트는 모노레포다. 각 패키지의 규칙은 해당 디렉토리의
CLAUDE.md를 참조한다.

@docs/architecture.md    # 아키텍처 문서를 컨텍스트에 포함
@docs/api-conventions.md  # API 설계 컨벤션
@.github/PULL_REQUEST_TEMPLATE.md  # PR 템플릿 참조

시작하기: 5단계