Put only universally applicable instructions in CLAUDE.md. Task-specific or situational content raises the chance the agent treats the whole file as noise and ignores it - the failure mode broken down in why agents ignore your CLAUDE.md.
Include
- Non-guessable shell commands and the project’s test runner.
- Code style that differs from language defaults.
- Repository etiquette, architecture decisions, and environment gotchas.
Exclude
- Anything the code, types, or existing docs already make clear.
- One-off, task-specific steps - pass those in the prompt or via progressive disclosure (
@imports, skills, child-directory files) instead.
Why
CLAUDE.md loads at the start of every session and consumes context on every turn. A short, universal file stays high-signal; a bloated one dilutes the instructions that matter. That’s context engineering - same discipline, one file, zero exceptions.