CLAUDE.md 작성 완벽 가이드: 프로젝트 설정 베스트 프랙티스

CLAUDE.md란?

CLAUDE.md는 Claude Code가 프로젝트를 이해할 수 있도록 도와주는 컨텍스트 파일입니다. 프로젝트 루트에 배치하면 Claude Code가 매 세션 시작 시 자동으로 읽습니다. 잘 작성된 CLAUDE.md는 Claude Code의 응답 품질을 획기적으로 향상시킵니다.

파일 위치와 우선순위

여러 위치에 CLAUDE.md 파일을 배치할 수 있으며, 모두 로드됩니다:

~/.claude/CLAUDE.md          # 전역 설정 (모든 프로젝트 공유)
./CLAUDE.md                   # 프로젝트 루트 (팀 공유)
./CLAUDE.local.md             # 로컬 설정 (.gitignore에 추가)
./src/CLAUDE.md               # 하위 디렉토리 수준 설정

• 전역: 개인 코딩 스타일 선호도
• 프로젝트 루트: 팀이 공유하는 규칙과 기술 스택
• 로컬: Git에 커밋하지 않는 개인 설정
• 하위 디렉토리: 특정 모듈에 대한 추가 컨텍스트

시작 템플릿

실용적인 CLAUDE.md 템플릿입니다:

# 프로젝트 개요

이커머스 백엔드 API. 주문 관리, 재고 관리, 사용자 인증을 담당.

## 기술 스택

- 언어: TypeScript 5.x
- 런타임: Node.js 22
- 프레임워크: Fastify
- DB: PostgreSQL 16 + Prisma ORM
- 테스트: Vitest
- CI: GitHub Actions

## 디렉토리 구조

src/
  routes/       # API 라우트 정의
  services/     # 비즈니스 로직
  repositories/ # 데이터 접근 계층
  middleware/   # 인증, 로깅, 에러 처리
  utils/        # 유틸리티 함수
  types/        # 타입 정의

## 코딩 컨벤션

- 화살표 함수 사용
- 에러 처리는 반드시 try-catch + 커스텀 에러 클래스 사용
- 네이밍: camelCase (변수/함수), PascalCase (타입/클래스)
- 파일명: kebab-case
- 상대 경로 대신 `@/` 경로 별칭 사용

## 자주 쓰는 명령어

- 테스트 실행: `npm test`
- 타입 체크: `npx tsc --noEmit`
- 린트: `npm run lint`
- DB 마이그레이션: `npx prisma migrate dev`
- 개발 서버: `npm run dev`

## 중요 규칙

- prisma/schema.prisma 수정 후 반드시 마이그레이션 생성
- 모든 API 엔드포인트에 Zod 유효성 검사 스키마 필수
- 새로운 라우트는 routes/index.ts에 등록

효과적인 CLAUDE.md 작성 팁

1. 간결하게 유지하기

CLAUDE.md는 컨텍스트 윈도우 토큰을 소비합니다. 장황한 설명을 피하고 불릿 포인트로 작성하세요.

# 나쁜 예
이 프로젝트는 TypeScript를 사용합니다. TypeScript는
Microsoft가 개발한 JavaScript에 타입을 추가한 언어로...

# 좋은 예
- 언어: TypeScript 5.x (strict 모드)

2. 하지 말아야 할 것을 문서화하기

안티패턴을 명시적으로 나열하는 것은 놀라울 정도로 효과적입니다.

## 금지 사항

- `any` 타입 사용 금지
- 디폴트 익스포트 금지 (네임드 익스포트만 사용)
- 디버깅용 console.log 금지 (logger 사용)
- 기존 테스트 삭제 또는 스킵 금지

3. 워크플로 정의하기

작업을 어떤 순서로 처리해야 하는지 Claude Code에 안내하세요.

## 새 기능 추가 절차

1. `src/types/`에 타입 정의 생성
2. `src/repositories/`에 데이터 접근 계층 구현
3. `src/services/`에 비즈니스 로직 구현
4. `src/routes/`에 엔드포인트 정의
5. 각 계층별 단위 테스트 작성
6. `npm test`로 모든 테스트 통과 확인

4. 암묵적 지식 기록하기

다른 곳에 기록되지 않은 중요한 정보를 문서화하세요.

## 프로젝트 특이사항

- `user_id`는 UUID v7 사용 (시간순 정렬 가능)
- 모든 가격 계산은 `Decimal.js` 사용 필수 (부동소수점 오류 방지)
- 환경 변수는 `src/config.ts`에서 일괄 관리 — process.env 직접 접근 금지

팀에서 활용하기

.gitignore 설정

개인 설정을 버전 관리에서 제외합니다:

# .gitignore
CLAUDE.local.md

코드 리뷰에 포함하기

CLAUDE.md를 중요한 프로젝트 문서로 취급하세요. PR 리뷰에 포함시키고 팀 전체가 함께 관리하세요.

CLAUDE.md 업데이트 시점

• 새로운 라이브러리를 추가할 때
• 코딩 컨벤션을 변경할 때
• 디렉토리 구조를 재편할 때
• Claude Code가 같은 실수를 반복하는 것을 발견했을 때

결론

CLAUDE.md를 통해 Claude Code를 프로젝트 전문가로 만들 수 있습니다. /init으로 기본 골격을 생성한 후 작업하면서 점차 다듬어 나가세요. 팀과 공유하여 모든 구성원이 최적화된 Claude Code 경험을 누릴 수 있도록 하세요.