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.md is guidance; hooks are guarantees.
  • Move reference material out. Link to docs/architecture.md and 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.