DEV Community

Vildanden
Vildanden

Posted on

Keep your CLAUDE.md under 40 lines so Claude Code actually follows it

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.
Enter fullscreen mode Exit fullscreen mode

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.

Top comments (2)

Collapse
 
skillselion profile image
Skillselion •

The 40-line ceiling is the right instinct applied to one file out of several, and the other ones are usually bigger. I read affaan-m/ECC at its current commit this morning: its rules/ folder holds 22 packs, the README calls rules always-loaded context rather than on-demand, and rules/common on its own is 10 files and roughly 19 KB of markdown before you add a language pack. A 40-line CLAUDE.md next to a copied rules tree has not reduced the session budget, it has moved the spend somewhere you are not auditing monthly.

The same goes for installed skills, where the description of every one sits in context whether or not it fires. So the prune rule belongs on the whole set of always-loaded files, including the ones you did not write.

Second, "CLAUDE.md is guidance; hooks are guarantees" needs a footnote, because a hook is a guarantee only when its failure mode blocks. By default it does not: the docs say a PreToolUse hook that cannot start or times out is a non-blocking error, and the call continues through the normal permission flow. The same page is blunt about it, that you should not count on a stalled hook to act as a gate. Two settings turn the guarantee back on. Exit 2 rather than exit 1, because exit 1 without valid JSON is treated as the hook erroring rather than as a verdict. And "onFailure": "block" on the hook entry, which makes a failed or timed-out hook block the way exit 2 does, on Claude Code v2.1.295 or later. For "never run git push --force" that is the difference between a rule and a hope, so it is worth setting on purpose.

Collapse
 
aiinfoshare profile image
aiinfoshare •

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.