topic★★★★★난이도 · 약 12분
CLAUDE.md — AI에게 주는 프로젝트 설명서
프로젝트의 규칙·구조·컨벤션을 AI에게 알려주는 마크다운 파일.
#CLAUDE.md#설정#컨벤션
왜 배우는가
AI는 프로젝트마다 다른 컨벤션을 모른다. CLAUDE.md가 없으면 매번 같은 설명을 반복해야 한다. 한 번 잘 작성해두면 AI가 알아서 규칙을 지킨다.
CLAUDE.md는 Claude Code가 대화 시작 시 자동으로 읽는 프로젝트 설명서다. 여기에 코딩 컨벤션, 프로젝트 구조, 절대 금지 사항 등을 적어두면 AI가 매번 참고한다.
| 항목 | 설명 |
|---|---|
| 위치 | 프로젝트 루트에 `CLAUDE.md` 파일 생성 |
| 자동 읽기 | Claude Code가 대화를 시작할 때 자동으로 컨텍스트에 포함 |
| 계층 구조 | 루트 CLAUDE.md + 하위 폴더별 CLAUDE.md → 해당 폴더 작업 시 추가 로드 |
| 자동 생성 | `/init` 명령어로 프로젝트 분석 후 초안 자동 생성 |
| 우선순위 | 홈 디렉토리 `~/.claude/CLAUDE.md` → 프로젝트 루트 → 하위 폴더 순 |
markdown
# 프로젝트 규칙
## 기술 스택
- Next.js 16 (App Router), React 19, Tailwind CSS v4
## 절대 금지
- 다크 테마 사용 금지
- any 타입 사용 금지
- console.log 커밋 금지
## 코딩 컨벤션
- 컴포넌트 파일명: PascalCase (예: UserCard.tsx)
- 유틸 함수: camelCase (예: formatDate.ts)
- 커밋 메시지: conventional commits 형식이런 규칙을 CLAUDE.md에 한 번 적어두면 AI가 코드 생성 시 자동으로 지킨다. 프로젝트마다 다른 컨벤션을 매번 말할 필요가 없다.
하위 폴더 CLAUDE.md — 폴더마다 별도 규칙을 둘 수 있다. 예를 들어 `src/components/CLAUDE.md`에 컴포넌트 작성 규칙을, `src/domains/CLAUDE.md`에 도메인 계층 규칙을 적으면 해당 폴더 작업 시 자동으로 추가 로드된다.
bash
# CLAUDE.md 자동 생성
claude /init
# 이 명령어를 실행하면 Claude Code가:
# 1. 프로젝트 파일 구조를 분석
# 2. package.json, tsconfig 등 설정 파일 파악
# 3. 자동으로 CLAUDE.md 초안 작성/init은 프로젝트를 분석하여 CLAUDE.md를 자동 생성한다. 이후 직접 편집하여 프로젝트에 맞게 보완하면 된다.