CLAUDE.md 작성법 — 순서 최적화와 베스트 프랙티스
Claude Code안 바뀌는 건 위에, 자주 바뀌는 건 아래에 — 프롬프트 캐싱 최적화
CLAUDE.md는 Claude Code가 프로젝트를 이해하는 가장 중요한 파일이다. 매 세션 시작 시 자동으로 로드되며, 여기 적힌 규칙을 Claude가 따른다.
가장 중요한 원칙: 배치 순서
안 바뀌는 걸 위에, 자주 바뀌는 걸 아래에 둬야 한다. 이유는 프롬프트 캐싱 때문이다.
Claude Code는 시스템 프롬프트를 캐싱하는데, 캐싱은 앞에서부터 일치하는 부분까지만 유효하다. 파일 앞부분이 바뀌면 캐시가 전부 무효화된다. 그래서 절대 안 바뀌는 내용(프로젝트 설명, 코딩 규칙)을 맨 위에 두면 캐시 히트율이 올라가고, 매번 바뀌는 내용(현재 작업 컨텍스트)은 맨 아래에 둬야 캐시에 영향을 주지 않는다.
권장 배치 순서
- 프로젝트 설명 — 이름, 기술 스택, 목적 (거의 안 바뀜 → 캐시 히트)
- 코딩 규칙 — 컨벤션, 금지 사항, 스타일 (가끔 추가는 되지만 기존 내용은 안 바뀜 → 캐시 히트)
- 아키텍처 결정 — DB, 인증, 라우팅 등 설계 패턴 (가끔 변경 → 가끔 캐시 미스)
- 현재 작업 컨텍스트 — 지금 진행 중인 작업, 임시 메모 (자주 변경 → 캐시 미스, 하지만 맨 아래라 위의 캐시에 영향 없음)
규칙 파일 분리
.claude/rules/ 디렉토리에 주제별 .md 파일을 분리하면 메인 CLAUDE.md를 깔끔하게 유지할 수 있다. 규칙 파일은 CLAUDE.md와 함께 자동으로 로드된다.
3가지 레벨의 CLAUDE.md
~/.claude/CLAUDE.md— 개인 전역 규칙 (모든 프로젝트 공통)프로젝트루트/CLAUDE.md— 프로젝트 규칙 (Git에 커밋, 팀 공유).claude/rules/*.md— 주제별 분리 규칙 (Git에 커밋)
프롬프트 캐싱과 배치 순서
Claude Code는 CLAUDE.md를 시스템 프롬프트에 포함시키고, 이 프롬프트를 앞에서부터 캐싱합니다. 앞부분이 이전 세션과 동일하면 캐시 히트 → 더 빠르고 비용 절감.
핵심: 캐싱은 앞에서부터 일치하는 부분까지만 유효. 자주 바뀌는 내용을 위에 두면 전체 캐시가 깨진다.
CLAUDE.md 권장 템플릿
# CLAUDE.md
## 프로젝트 설명 ← 1순위 (절대 안 바뀜)
- 프로젝트명: MyApp
- 기술 스택: Rails 8, SQLite, Tailwind
- 대화 언어: 한국어
## 코딩 규칙 ← 2순위 (가끔 추가)
- jsonb 사용 금지 (SQLite)
- enum은 Rails 8 문법 사용
- 테스트는 RSpec request spec
## 금지 사항 ← 2순위 (거의 안 바뀜)
- git clean 금지
- git reset --hard 금지
- .env 파일 커밋 금지
## 아키텍처 결정 ← 3순위 (가끔 변경)
- Item 모델 중심 설계
- appX 앱은 네임스페이스 분리
- 인증은 Devise + CsrfSafeSessions
## 규칙 파일 목록 ← 3순위
| 파일 | 내용 |
|------|------|
| rails8.md | Rails 8 규칙 |
| rspec.md | 테스트 규칙 |
## 현재 작업 (임시) ← 4순위 (자주 변경, 맨 아래!)
- app142 인증 추가 작업 중
- PR #456 리뷰 대기3가지 레벨의 CLAUDE.md
| 레벨 | 위치 | 범위 | Git |
|---|---|---|---|
| 개인 전역 | ~/.claude/CLAUDE.md |
내 모든 프로젝트에 적용 | 비추적 |
| 프로젝트 | 프로젝트루트/CLAUDE.md |
해당 프로젝트 전체 (팀 공유) | Git 커밋 |
| 주제별 분리 | .claude/rules/*.md |
해당 프로젝트 (주제별 분리) | Git 커밋 |
작성 팁
구체적으로 작성 — "깔끔한 코드 작성"보다 "enum은 Rails 8 문법(attribute + enum :status)으로 작성"이 훨씬 효과적
금지 사항은 이유와 함께 — "jsonb 금지" 보다 "jsonb 금지 (SQLite 미지원)"이 Claude가 더 잘 따름
예제 코드 포함 — "이렇게 작성해라"와 함께 코드 블록을 넣으면 정확도가 크게 올라감
규칙이 20개 넘으면 .claude/rules/로 분리 — CLAUDE.md가 너무 길면 컨텍스트 윈도우 낭비
코드에서 읽을 수 있는 건 안 적음 — 파일 구조, git 히스토리, 변수명 등은 Claude가 직접 읽을 수 있으므로 중복 불필요
디버깅 해결법 안 적음 — 수정 내역은 코드와 커밋 메시지에 있음. CLAUDE.md는 "규칙"을 적는 곳
사용 방법
프로젝트 루트에 CLAUDE.md 생성 → 안 바뀌는 순서대로 작성 (프로젝트 설명 → 코딩 규칙 → 아키텍처 → 현재 작업)
규칙이 많아지면 .claude/rules/ 디렉토리에 주제별 .md 파일로 분리
개인 전역 규칙은 ~/.claude/CLAUDE.md에 설정 (모든 프로젝트 공통 적용)
자주 바뀌는 내용(현재 작업, 임시 메모)은 항상 파일 맨 아래에 배치
Tags
Source
Anthropic Docs