Most CLAUDE.md files I see grow into a wiki: architecture notes, style essays, a changelog, three pasted READMEs. Then people wonder why the agent ignores the one rule that mattered.
CLAUDE.md is loaded into context at the start of a session, so every line competes with your actual task. Short, concrete house rules beat long explanations.
## Before you edit
- Read the file and its tests before changing it.
- Ask before adding a new dependency.
## Commands
- Test: `npm test`
- Lint: `npm run lint -- --fix`
- Never run: `git push --force`, `rm -rf`, database migrations.
## Done means
- Tests and lint pass locally.
- You list the files you changed and why, in one line each.
## Style
- Match the surrounding code. No drive-by refactors.
That is the whole file. Each line is something you could check in a diff.
npm test" is better than a paragraph about the test philosophy. settings.json. CLAUDE.md is guidance; hooks are guarantees.docs/architecture.md and let the agent read it when needed instead of it every session.
Check the memory docs for your installed Claude Code version; how nested and user-level files are loaded can change between releases.
I ship this short house-rules file together with the allow-list and the safety hooks in Vildanden Agent Config. The free sample is enough to try the pattern today.