The CLAUDE.md Starter Kit

Claude Code를 5분 만에 더 잘 활용하세요. 플러그인, MCP 서버, 설정은 필요 없습니다. 적절한 위치에 마크다운 파일만 있으면 됩니다.

3단계 계층 구조 (The 3-Level Hierarchy)

Claude Code는 세 가지 위치에서 지침을 읽습니다. 각 위치는 다른 범위를 가집니다:

~/.claude/CLAUDE.md          -> 글로벌(Global): 개인적인 선호도 (모든 프로젝트)
.claude/CLAUDE.md            -> 프로젝트(Project): 팀과 공유 (git에 커밋)
./CLAUDE.local.md            -> 로컬(Local): 개인적인 재정의 사항 (gitignore 처리)

글로벌(Global) = 모든 프로젝트에서 반복할 규칙 (

your-project/
├── .claude/
│   ├── CLAUDE.md              # Project instructions (committed)
...

작동 방식 (How It Works)

Claude Code는 매 세션 시작 시 이 파일들을 자동으로 읽습니다. 발견된 모든 파일은 서로 덮어쓰지 않고 **하나의 컨텍스트로 연결(concatenated into context)**됩니다. 지침이 충돌할 경우, Claude는 가장 마지막에 읽은 지침을 따릅니다. 각 디렉터리 내에서는 CLAUDE.local.md가 CLAUDE.md 이후에 로드되므로, 개인적인 메모가 해당 레벨에서 최종 결정권을 갖게 됩니다.

중요: Claude Code의 시스템 프롬프트에는 이미 약 50개의 지침이 포함되어 있습니다. 이는 최신 모델들이 안정적으로 따를 수 있는 150200개 지침 한도의 3분의 1에 해당합니다. 따라서 CLAUDE.md는 간결해야 합니다. 모든 줄이 주의를 끌기 위해 경쟁하기 때문입니다.

자동 메모리 (Auto memory): Claude는 또한 ~/.claude/projects/<project>/memory/ 경로에서 자체적인 메모를 유지합니다. 여기에는 발견된 빌드 명령어, 사용자의 수정 사항에서 얻은 패턴, 디버깅 통찰 등이 포함됩니다. 이 역시 세션 시작 시 로드됩니다. 따라서 Claude가 스스로 학습할 내용이라면 CLAUDE.md에 넣을 필요가 없습니다. /memory를 실행하여 로드된 모든 내용을 확인하세요. CLAUDE.md와 자동 메모리를 언제 사용해야 하는지는 principles.md를 참고하십시오.

자가 개선 루프 (The Self-Improvement Loop)

이것은 구축할 수 있는 가장 영향력 있는 습관입니다:

Claude에게 수정 사항을 줄 때마다, 다음 문구로 마무리하세요:

"다음에 같은 실수를 하지 않도록 CLAUDE.md를 업데이트해 줘."

Claude는 스스로 규칙을 작성하는 데 능숙합니다. 시간이 지남에 따라 사용자의 CLAUDE.md는 매 세션마다 더 똑똑해지는 살아있는 문서가 됩니다.

무엇을 어디에 넣을까 (Decision Guide)

흔한 실수 (Common Mistakes)

너무 길게 작성하는 것. 프로젝트의 CLAUDE.md가 80줄을 초과하면, Claude는 그 일부를 무시하기 시작합니다. HumanLayer는 이 내용을 60줄 미만으로 유지하고 있습니다. 이것이 좋은 기준점입니다.

개성 관련 지침 (Personality instructions). "선임 엔지니어처럼 행동해라" 또는 "단계별로 생각하라"와 같은 지침은 토큰을 낭비합니다. Claude Code는 이미 강력한 시스템 레벨의 지침을 가지고 있습니다.

@-멘션(mentioning) 문서. docs/api-guide.md와 같이 파일 전체를 컨텍스트에 포함하는 것은 매 세션마다 토큰을 소모합니다. 대신, Claude에게 언제 읽어야 할지 제안하세요:

원칙 (더 깊이 파고들기)

**principles.md**에는 효과적인 CLAUDE.md 파일을 작성하는 데 필요한 모든 것이 포함되어 있습니다:

• 주의 집중 예산(Attention budget) (왜 적을수록 좋은지)
• 조언적 방식 대 결정론적 방식: CLAUDE.md vs hooks
• Anthropic의 공식 include/exclude 테이블
• .claude/rules/ — YAML 프런트매터가 적용된 경로 범위 모듈 규칙
• Claude가 실제로 따르는 작성 규칙 (나쁜 예시/좋은 예시 포함)
• 실제로 작동하는 강조 키워드 (IMPORTANT, YOU MUST)
• 확장을 위한 모듈별 CLAUDE.md 파일
• 점진적 공개 패턴 및 @import 구문
• 아키텍처 다이어그램 (HumanLayer의 패턴)

이 스타터 키트는 다음 자료들을 기반으로 합니다:

• Anthropic — "Claude Code Best Practices" — 공식 가이드라인, 포함/제외 테이블, 규칙
• Anthropic — "Effective Context Engineering" — 컨텍스트 부패(Context rot), 어텐션 예산(attention budget), 적시성 컨텍스트(just-in-time context)
• Anthropic — "Memory and Project Configuration" — CLAUDE.md 계층 구조, 규칙, 자동 메모리
• Anthropic — "Hooks Guide" — 결정론적 라이프사이클 훅(Deterministic lifecycle hooks)
• Boris Cherny's team tips — Claude Code 팀의 팁 10가지 (2026년 1월 31일)
• Boris Cherny's personal setup — 창작자가 Claude Code를 사용하는 방법 (2026년 1월 2일)
• HumanLayer — "Writing a Good CLAUDE.md" — 지침 제한, 점진적 공개(progressive disclosure), 다이어그램 활용
• Matt Pocock — "My AGENTS.md file" — 계획 루프 규칙(Plan loop rules)
• josix/awesome-claude-md — 오픈 소스 프로젝트의 실제 CLAUDE.md 파일 모음
• hesreallyhim/awesome-claude-code — Claude Code 리소스를 위한 주요 awesome 목록
• HumanLayer, Cloudflare, ChrisWiles (5.2k stars)의 실제 CLAUDE.md 파일 및 커뮤니티 자료들

향후 작업

향후 작업

• 이 원칙들로 개선된 실제 CLAUDE.md 파일의 전/후 예시 (Before/after examples)
• 스택별 규칙 템플릿 (Go, Rust, Ruby on Rails, Django)
• 마이그레이션 가이드: "200줄짜리 CLAUDE.md가 있다면 — 이를 규칙으로 분할하는 방법"
• 훅스(Hooks) 북: 일반적인 라이프사이클 훅과 CLAUDE.md 패턴의 조합
• 처음부터 전체 계층 구조를 설정하는 비디오 워크스루