What is the 3-level CLAUDE.md hierarchy?

Claude Code reads CLAUDE.md files at 3 levels: 1) ~/.claude/CLAUDE.md, global rules that apply to every project (your personal preferences, tools you always use); 2) project root CLAUDE.md, team-shared context committed to git (tech stack, conventions, commands); 3) .claude/CLAUDE.local.md, personal project overrides, gitignored (local paths, personal shortcuts). Each level is additive. Lower files override higher ones for the same setting.

3-level hierarchy From daily practice

CLAUDE.md Best Practices

Q: What should I put in CLAUDE.md?

CLAUDE.md should contain: your tech stack and key dependencies, project-specific commands (build, test, dev), coding conventions (linting rules, naming standards), architecture decisions (folder structure, key patterns), and anything Claude asks repeatedly that you find yourself typing every session. Do NOT include: general coding best practices (Claude already knows these), content that belongs in README, or per-developer personal preferences (use CLAUDE.local.md for those).

Q: How long should CLAUDE.md be?

Project-level CLAUDE.md: 50-200 lines is the sweet spot. Shorter means Claude lacks critical context. Longer means Claude wastes tokens on noise every session. Global CLAUDE.md: up to 400 lines is reasonable since it's amortized across all projects. If your CLAUDE.md exceeds 500 lines, it's probably including content that should live elsewhere (README, API docs, architecture diagrams).

CLAUDE.md is Claude Code's memory system. Get it right and Claude stops asking the same questions every session. Get it wrong and you waste tokens on noise.

Browse 275 Templates → Cheatsheet

The 3-Level Hierarchy

Claude Code reads CLAUDE.md files at three levels, each additive:

Level	Path	Scope	Git
Global	`~/.claude/CLAUDE.md`	Every project on your machine	No (personal)
Project	`{project-root}/CLAUDE.md`	Shared team context	Yes (committed)
Personal	`.claude/CLAUDE.local.md`	Personal overrides, local paths	No (gitignored)

 Claude reads all three files at session start and merges them. Lower levels override higher ones for the same setting. Your team's shared conventions live in project-level CLAUDE.md; your personal shortcuts live in CLAUDE.local.md.

  What to Include
 Always include
  Tech stack: language versions, key frameworks, database. "Node 22, TypeScript strict, PostgreSQL 16, tRPC."
 Build commands: how to run, test, and build. Claude will run these when needed. "pnpm dev / pnpm test / pnpm build"
 Code conventions: linting rules, naming standards, file organization. Anything you enforce in CI.
 Architecture decisions: folder structure, key patterns, what NOT to do. "Never put business logic in API routes."
 Repeated context: anything you find yourself typing every new session.
 
 Never include
  General coding best practices, Claude knows these already
 Content that belongs in README (setup instructions for humans)
 API documentation, link to it instead of pasting it
 Per-developer personal preferences, use CLAUDE.local.md
 Anything that changes every week, stale instructions confuse Claude
 
 
  Minimal Working Template
 This is the smallest CLAUDE.md that covers the essentials for a TypeScript project:
 # Project Context

## Stack
- Node 22 + TypeScript (strict)
- PostgreSQL 16, Prisma ORM
- Next.js 15 (App Router)
- pnpm workspace

## Commands
- Dev: `pnpm dev`
- Test: `pnpm test`
- Build: `pnpm build`
- Typecheck: `pnpm tsc --noEmit`

## Conventions
- Components: PascalCase, colocated with tests
- API routes: snake_case, always return `{data, error}`
- No `any` types, use `unknown` and narrow
- Migrations: never edit existing, always create new

## Architecture
- Business logic lives in `src/lib/`, never in `src/app/`
- Database access only through repository pattern in `src/repositories/`
- Tests are colocated: `Button.test.tsx` next to `Button.tsx`


      Start small. Add to CLAUDE.md when Claude asks something you've answered before, that's the signal to capture it.
    
  Anti-patterns That Hurt Performance
  Padding with generic rules: "Write clean code", "Follow SOLID principles". Claude knows these. You're just burning context tokens.
 Pasting entire files: if you reference a file by path, Claude can read it on demand. Pasting it upfront means it's read every session regardless of relevance.
 Stale instructions: a CLAUDE.md referencing deprecated patterns (old library versions, renamed commands) actively misleads Claude. Review quarterly.
 One monolithic global CLAUDE.md: global CLAUDE.md grows fast. Split personal preferences (global) from project conventions (project-level) from personal local paths (CLAUDE.local.md).
 Missing build commands: this is the most common omission. Without them, Claude either guesses (wrong) or asks every session.
 
 
  FAQ
  What should I put in CLAUDE.md?
 Tech stack, build commands, code conventions, architecture decisions, and anything you find yourself typing every new session. Not general best practices (Claude already knows them), not README content, not per-developer preferences (use CLAUDE.local.md).
 
  How long should CLAUDE.md be?
 Project-level: 50-200 lines is the sweet spot. Global: up to 400 lines is reasonable. Over 500 lines, you're probably including content that belongs elsewhere (README, API docs, architecture diagrams). Longer does not mean better; every line costs tokens on every session.
 
  Does CLAUDE.md replace README?
 No. README is for humans setting up the project. CLAUDE.md is for Claude's in-session context. They overlap slightly (both might list build commands) but serve different audiences. Don't duplicate them; if it's in README, just reference the file path in CLAUDE.md.
 
 
  Next Steps
 See the 275 CLAUDE.md templates organized by project type, stack, and role. Or read the full cheatsheet for the complete Claude Code command reference.