It gets injected into context wholesale, every session — every line competes for attention with the rules that actually matter. Official docs and community consensus agree: short, precise, only what Claude can’t guess.
DO / worth writing
- Keep it short: under 200 lines total, 80–120 for the distilled versionOver-long files are not executed line by line — they get averaged into mush
- Write commands fully and literally: build / test / lint / migrate, flags includedThe single highest-value item — saves Claude three rounds of guessing
- Only facts and no-go zones that can't be read from the code and are costly to guess wronge.g. CI's Node version, untouchable migration files, signature-verification logic
- Use @ references instead of retelling: @README.md, @docs/architecture.mdRelative and absolute paths work; recursive imports up to 5 levels deep
- Layer things: behavior goes global, facts go per-project, local rules go in subdirectoriesLazy loading keeps irrelevant rules out of context entirely
- Hand hard constraints to Hooks (e.g. "lint must run before every commit")Hooks execute at lifecycle points — they don't depend on Claude's mood
- Run /memory regularly to review, prune, and de-conflict every layerWhen two rules conflict, Claude may pick either one
DON'T / skip these
- Persona prompts: "You are a senior engineer, think step by step"Words that don't change concrete behavior are wasted instruction budget
- Things Claude can self-learn in one session (file naming patterns, dependency lists)Auto memory (MEMORY.md) will remember those — writing them is duplication
- Multi-step proceduresMake them a Skill loaded on demand instead of carrying them every session
- Pasting whole architecture documentsOne @ reference is enough; Claude reads it when needed
- Real keys, tokens, passwords — including in CLAUDE.local.mdWrite where to get them, not the values; these files are not a vault
- Treating CLAUDE.md as an enforcement switchIt is context, not a barrier; for "block no matter what," use a PreToolUse hook
← Back to guides