새 프로젝트에서 Claude Code를 처음 실행하면 아무것도 모릅니다. 어떤 프레임워크를 쓰는지, 테스트는 어떻게 실행하는지, 코딩 컨벤션은 무엇인지 알지 못합니다. CLAUDE.md는 이 정보를 Claude Code에 미리 알려주는 파일입니다.
프로젝트 루트에 두는 마크다운 파일입니다. Claude Code가 세션을 시작할 때 자동으로 읽어 컨텍스트로 사용합니다. 한 번 잘 작성해두면 매번 설명할 필요가 없습니다.
Manifest 파일: 프로젝트의 메타정보와 규칙을 담는 파일. CLAUDE.md는 Claude Code를 위한 Manifest 역할을 합니다.
## 프로젝트 개요
NestJS + TypeScript로 작성된 헬스케어 SaaS 백엔드.
PostgreSQL + Redis를 사용하며 BullMQ로 비동기 작업을 처리한다.
## 명령어
- 개발 서버: `npm run dev`
- 빌드: `npm run build`
- 테스트: `npm run test`
- 린트: `npm run lint`
- 마이그레이션: `npm run migration:run`
Claude Code가 작업 후 검증할 때 이 명령을 사용합니다. 명령이 틀리면 검증 자체가 실패합니다.
## 코딩 컨벤션
- 파일명: kebab-case (user-service.ts)
- 클래스명: PascalCase
- 변수명: camelCase
- 상수: UPPER_SNAKE_CASE
- 인터페이스 앞에 I 붙이지 않음
- any 타입 사용 금지
## 아키텍처
- src/modules/ 아래 도메인별 모듈 구성
- 각 모듈: controller / service / repository / dto / entity
- 외부 API 호출은 반드시 별도 service로 분리
- 직접 DB 쿼리 금지 — 반드시 Repository 통해서
## 주의 사항
- 절대 프로덕션 DB에 직접 쿼리하지 말 것
- .env 파일 수정 금지
- package.json 버전 변경 시 반드시 확인받을 것
# My Project
## 프로젝트 개요
NestJS + TypeScript SaaS 백엔드. Node.js 20, TypeScript 5.
## 명령어
- 개발: `npm run dev`
- 테스트: `npm test`
- 빌드: `npm run build`
## 아키텍처
- src/modules/ 아래 도메인별 모듈
- 각 모듈: controller, service, dto, entity
- 인증: JWT + Redis 세션
## 코딩 컨벤션
- any 사용 금지
- 비동기 함수 반드시 await 사용
- 에러는 커스텀 Exception 클래스 사용
## 주의
- .env 파일 수정 금지
- DB 마이그레이션 전 반드시 확인
CLAUDE.md는 여러 위치에 둘 수 있습니다.
프로젝트 루트/
CLAUDE.md ← 전체 프로젝트에 적용
src/
modules/
user/
CLAUDE.md ← user 모듈에만 적용
하위 디렉토리의 CLAUDE.md는 해당 디렉토리 내 작업에만 추가로 적용됩니다. 모듈별로 특수한 규칙이 있을 때 씁니다.
홈 디렉토리의 ~/.claude/CLAUDE.md는 모든 프로젝트에 전역으로 적용됩니다. 개인적인 선호 사항이나 공통 규칙을 여기에 씁니다.
처음 프로젝트에서 CLAUDE.md를 직접 작성하기 어렵다면 /init 명령을 씁니다. Claude Code가 프로젝트를 분석해 초안을 만들어줍니다.
claude> /init
생성된 파일을 검토하고 필요한 내용을 추가하면 됩니다.
CLAUDE.md 없이 작업하면 매번 컨텍스트를 설명해야 합니다. "이 프로젝트는 NestJS를 쓰고, 테스트는 이렇게 실행하고..." 같은 설명을 반복합니다.
잘 작성된 CLAUDE.md는 Claude Code가 프로젝트를 처음부터 이해하고 작업합니다. 빌드 명령을 알고 있으므로 수정 후 자동으로 검증합니다. 컨벤션을 알고 있으므로 기존 코드 스타일에 맞게 작성합니다.