CLAUDE.md — Project Instructions
CLAUDE.md is a markdown file at the root of a project (or in subdirectories) that Claude Code reads automatically and treats as part of its system prompt. Use it to encode project conventions, architectural decisions, and instructions like 'always run tests after editing.'
CLAUDE.md is a sticky note on the office monitor — every time you sit down (every turn), you read it. Make it a checklist, not an essay.
Three locations matter: ~/.claude/CLAUDE.md (global, applies everywhere), <project>/CLAUDE.md (committed, shared with team), <project>/CLAUDE.local.md (gitignored, personal). Subdirectory CLAUDE.md files are loaded when Claude operates in that directory. Content should be terse and rule-oriented: 'use pnpm not npm,' 'tests live in __tests__/,' 'never edit generated/.' Avoid wall-of-text explanations — every line costs tokens on every turn.
CLAUDE.md sits in the cached prefix, so it's free after the first turn — but it does count toward the context window. Best practice: keep it under ~300 lines. Override hierarchy: nearest file wins for conflicts, but all files load (additive). Use it for *behaviors*, not *facts about code* — the model can read the code. Save 'when running tests, always include --coverage' (behavior) over 'this project uses Jest' (derivable from package.json). Bad CLAUDE.md is worse than no CLAUDE.md because it pollutes every prompt.
CLAUDE.md is project-level context that Claude Code loads automatically into the system prompt. I use it to encode invariants the model can't infer from the code — coding conventions, deployment rules, 'never push to main without a review,' which package manager to use. I keep it under 300 lines and rule-oriented because it sits in every turn's prompt. The commit-vs-personal split (CLAUDE.md vs CLAUDE.local.md) lets the team share rules while individuals add personal preferences.
Treating CLAUDE.md as a wiki. Long explanatory prose costs tokens every turn and the model rarely needs the explanation — it needs the rule. 'Use 4-space indents' beats two paragraphs about why we use 4-space indents.