CLAUDE.md 마스터 - Claude Code 완전 가이드

잘 작성된 CLAUDE.md는 Claude Code 출력 품질을 높이는 가장 중요한 요소입니다. — 공식 문서

CLAUDE.md란?

프로젝트 루트에 두는 마크다운 파일로, Claude Code가 매 세션 시작 시 자동으로 읽습니다. 프로젝트 구조, 코딩 규칙, 워크플로우 지침을 담으며, Compaction 후에도 디스크에서 다시 읽어 생존합니다.

DANGER: CLAUDE.md는 파일당 200줄 이내를 유지하세요. 길면 Claude가 지시를 무시할 확률이 높아집니다. 매 줄마다 자문하세요: "이 줄을 빼면 Claude가 실수하는가?" 아니라면 삭제. — Boris Cherny

무엇을 넣고, 무엇을 빼야 하는가

넣어야 할 것	빼야 할 것
Claude가 추측할 수 없는 Bash 명령어	코드를 보면 알 수 있는 것
기본값과 다른 코드 스타일 규칙	Claude가 이미 아는 언어 표준 관례
테스트 실행 방법, 선호 러너	상세한 API 문서 (링크로 대체)
레포 에티켓 (브랜치 네이밍, PR 규칙)	자주 변경되는 정보
프로젝트 고유 아키텍처 결정	파일별 상세 설명
개발 환경 특이사항, 비자명한 동작	"깨끗한 코드를 작성하라" 같은 자명한 지침

Compounding Engineering (복리 엔지니어링)

Boris Cherny의 핵심 철학: Claude가 실수할 때마다 CLAUDE.md에 교정 규칙을 추가합니다. 시간이 지날수록 CLAUDE.md의 가치가 복리처럼 증가합니다.

# CLAUDE.md에 추가하는 교정 규칙 예시
- 항상 `bun`을 사용하고 `npm`을 쓰지 마세요
- `interface` 대신 `type`을 선호합니다
- `enum`은 절대 사용하지 마세요 (string literal union 사용)
- IMPORTANT: 테스트는 반드시 `bun test`로 실행하세요

TIP: 중요한 규칙에는 IMPORTANT, YOU MUST, CRITICAL 등의 강조어를 사용하세요. Claude의 준수율이 높아집니다. — 공식 문서

모노레포에서의 로딩 메커니즘

1. Ancestor Loading (위로 올라가기)

Claude Code 시작 시 현재 디렉토리에서 위쪽으로 올라가며 모든 CLAUDE.md를 즉시 로드합니다.

2. Descendant Loading (아래로 내려가기 - 지연 로딩)

하위 디렉토리의 CLAUDE.md는 해당 디렉토리의 파일을 읽을 때에만 로드됩니다.

/mymonorepo/
├── CLAUDE.md          ← 루트 (공유 규칙) — 항상 로드
├── frontend/
│   └── CLAUDE.md      ← frontend/ 파일 접근 시에만 로드
├── backend/
│   └── CLAUDE.md      ← backend/ 파일 접근 시에만 로드
└── api/
    └── CLAUDE.md      ← api/ 파일 접근 시에만 로드

Anti-Patterns (피해야 할 패턴)

과도한 명세 — CLAUDE.md가 너무 길면 중요한 규칙이 노이즈에 묻힘
@import로 전체 문서 임베딩 — 컨텍스트가 팽창하여 핵심이 희석됨
다중 파일 간 충돌 지시 — 루트와 하위 CLAUDE.md의 규칙이 모순됨
오래된 규칙 방치 — 정기적으로 프루닝하지 않으면 오류 유발
부정형만 사용 — "~하지 마라"만 쓰면 Claude가 막힘. 항상 대안을 제시 (Shrivu Shankar)