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.
A shape that works
# House rules
## 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.
Rules of thumb
-
Commands over prose. "Test:
npm test" is better than a paragraph about the test philosophy. -
Enforce, don't plead. If a rule really must hold (no force-push, tests after edits), put it in a hook or the allow-list in
settings.json.CLAUDE.mdis guidance; hooks are guarantees. -
Move reference material out. Link to
docs/architecture.mdand let the agent read it when needed instead of loading it every session. - Prune monthly. If a rule never changed a diff, delete it.
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.
Top comments (1)
This matches what I've seen. The file gets read at session start when attention is highest, and every extra line dilutes the ones that matter.
My version of the delete test: I only keep a line if I can point to a real mistake the agent made without it. "Run tests with X" stays because it once ran the wrong suite for an hour. "Prefer composition over inheritance" goes, because it's never prevented anything concrete.
The trick that keeps mine around 30 lines is pointers instead of prose: "full deploy checklist: docs/deploy.md" rather than inlining the checklist. The agent follows the pointer when it actually needs it, and the file stays scannable.
One nuance I'd add: line count is a proxy for the real metric, which is "does the agent follow it." I've seen a 25-line file of vague principles get ignored while a longer file of concrete do/don'ts got followed. Short helps, but concrete beats short.