CLAUDE.md 프로젝트 설정

CLAUDE.md란?

CLAUDE.md는 프로젝트 루트에 위치하는 파일로, Claude Code가 해당 프로젝트에서 작업할 때 참고하는 지시사항을 담습니다. 팀의 코딩 컨벤션, 빌드/테스트 명령어, 주의사항 등을 미리 정의해두면 매번 설명하지 않아도 됩니다.

파일 위치 우선순위

위치	적용 범위
`~/.claude/CLAUDE.md`	모든 프로젝트 (글로벌)
`{project}/CLAUDE.md`	해당 프로젝트 전체
`{project}/src/CLAUDE.md`	해당 디렉토리 하위

여러 위치의 내용이 모두 합쳐져서 적용됩니다.

기본 구조 예시

1# 프로젝트명2 3## 프로젝트 개요4Next.js 15 + TypeScript + Prisma + MySQL 스택의 위키 서비스.5 6## 자주 쓰는 명령어7- `npm run dev` — 개발 서버 시작 (포트 3001)8- `npm run build` — 프로덕션 빌드9- `npm test` — 전체 테스트 실행10- `npm run lint` — ESLint 검사11 12## 코딩 컨벤션13- TypeScript strict mode 필수14- 함수형 컴포넌트 사용 (클래스 컴포넌트 금지)15- import 순서: 외부 라이브러리 → 내부 모듈 → 타입16- 주석은 꼭 필요한 경우에만 (WHY만 설명)17 18## 파일 구조19- `src/app/` — Next.js App Router 페이지20- `src/components/` — 재사용 가능한 컴포넌트21- `src/lib/` — 유틸리티, DB 접근, 헬퍼22- `src/types/` — 공통 타입 정의23 24## 주의사항25- `.env.local` 파일 절대 커밋 금지26- `src/legacy/` 디렉토리는 수정하지 말 것27- DB 마이그레이션 전 반드시 백업 확인28- API 응답은 항상 NextResponse.json() 사용29 30## Git 컨벤션31- 커밋 메시지: `feat:`, `fix:`, `refactor:`, `docs:` 접두사 사용32- PR 전 `npm run lint && npm test` 통과 필수

효과적인 CLAUDE.md 작성 팁

빌드/테스트 명령어는 반드시 포함

Claude가 코드를 수정한 후 스스로 검증할 수 있게 합니다.

1## 검증 명령어2- 빌드: `npm run build`3- 테스트: `npm test`4- 타입 체크: `npx tsc --noEmit`5- 린트: `npm run lint`

금지사항 명시

1## 하지 말 것2- `console.log` 사용 금지 (logger 사용)3- `any` 타입 사용 금지4- `!` (non-null assertion) 남용 금지5- 하드코딩된 URL이나 포트 금지

프로젝트 특이사항 설명

1## 특이사항2- DB 연결은 `src/lib/db.ts`의 `query()`, `execute()` 함수만 사용3- 인증은 세션 쿠키 기반이며 `src/lib/session.ts` 참고4- 페이지 컴포넌트는 Server Component 기본, 클라이언트 상태 필요 시만 'use client'

글로벌 CLAUDE.md

~/.claude/CLAUDE.md에 모든 프로젝트에 적용할 개인 설정을 저장합니다.

1# 글로벌 설정2 3## 응답 스타일4- 한국어로 대화5- 코드 변경 후 항상 변경 이유 설명6- 완료 후 간결하게 요약 (불필요한 반복 설명 금지)7 8## 기본 도구9- 패키지 매니저: npm10- 테스트 프레임워크: Jest11- 린터: ESLint