A CLAUDE.md template that changes Claude's behaviour
A CLAUDE.md earns its place by holding the few things Claude cannot infer from your code. Here is what to put in it, what to leave out, and a template to copy.
A CLAUDE.md that actually changes Claude's behaviour is short and specific: the handful of commands, conventions, architectural facts, and gotchas that Claude cannot infer from the code itself. Put it at your project root and check it into git, or in ~/.claude/CLAUDE.md for rules that apply to every project. Keep it well under a couple of hundred lines, because a bloated file is the single most reliable way to get your instructions ignored. Everything below is about which lines earn their place and which quietly cost you.
Claude Code reads CLAUDE.md at the start of every conversation, so every line is a recurring tax on the context window — and Claude's own docs are blunt about the consequence: an over-long CLAUDE.md causes Claude to ignore your actual instructions because the important rules get lost in the noise.
What belongs in CLAUDE.md
The test for every line is the one Anthropic recommends: would removing this cause Claude to make a mistake? If not, cut it. That single question separates a file that steers behaviour from a file that reads like documentation nobody asked for. In practice, the content that passes falls into a few buckets.
| Put it in CLAUDE.md | Leave it out |
|---|---|
| Build, test, and lint commands Claude can't guess | Anything Claude can learn by reading the code |
| Conventions that differ from the language default | Standard idioms the model already knows |
| The preferred test runner and how to run one test | Full API docs — link to them instead |
| Architecture decisions specific to this repo | File-by-file descriptions of the tree |
| Environment quirks and required env vars | Information that changes every week |
| Non-obvious gotchas that have bitten you before | Self-evident advice like 'write clean code' |
Note what is not on the left: style rules your formatter already enforces. If Prettier, Black, gofmt, or ESLint will fix indentation and quote style on save, that is the linter's job, not CLAUDE.md's. Spending context to restate rules a deterministic tool already guarantees is pure overhead — and unlike CLAUDE.md, a formatter never forgets after a long session.
Keep it under about 200 lines
There is no hard limit, but length is the failure mode, so treat roughly 200 lines as a ceiling and prefer far shorter. When a section grows into a multi-step procedure rather than a fact — a deploy runbook, a release checklist — move it out of CLAUDE.md into a skill, which Claude loads on demand instead of every session. That keeps the always-loaded file lean while the procedure stays available when it is actually relevant.
You can also split by reference rather than by inlining. CLAUDE.md supports @path/to/file imports, so a short root file can point to @docs/architecture.md or @package.json and pull them in only as needed. Run /context to confirm Claude actually loaded the file, and /init to generate a first draft from your codebase that you then prune.
Global vs project: how the files stack
CLAUDE.md is not a single file but a small hierarchy, and all applicable files load together rather than one overriding the rest:
~/.claude/CLAUDE.md— your personal rules, applied to every project on the machine../CLAUDE.mdat the project root — checked into git and shared with the team../CLAUDE.local.md— personal project notes; add it to.gitignoreso it stays yours.- Parent directories — pulled in automatically, which is what makes monorepos work:
root/CLAUDE.mdandroot/service/CLAUDE.mdboth apply. - Child directories — loaded on demand when Claude reads a file inside them.
Because they stack, keep the global file to genuinely universal preferences (your shell, your commit style) and let each project's file carry the specifics. If a global rule and a project rule disagree, the more specific, closer file is the one you should trust to win the conflict in practice — so do not put anything in the global file that a single project would need to override.
A concrete version: a global file that says only 'use pnpm, conventional commits, never push to main directly', plus a project file that lists the repo's four commands and its two worst gotchas, is a complete and effective setup — perhaps forty lines total across both. That steers Claude far more reliably than one three-hundred-line file trying to encode every preference at once, because nothing important is buried under things Claude already knew.
Why the rules still get ignored
Even a good file has two failure modes worth planning around. The first is compaction: in a long session, Claude Code summarises earlier context to free space, and detailed behavioural rules can lose force as the conversation they lived in gets condensed. A short CLAUDE.md survives this better than a long one, and you can add an instruction such as 'when compacting, always preserve the full list of build and test commands' to protect the essentials.
The second is delegation. The built-in Explore and Plan subagents deliberately skip CLAUDE.md to stay fast, and users have reported that custom subagents do not always enforce the parent's rules either — one issue documenting exactly this was closed as not planned. The takeaway is not to distrust CLAUDE.md, but to know its ceiling: it is advisory. For a rule that must hold every time, with no exceptions — never touch the migrations folder, always run the formatter after an edit — use a deterministic hook instead of a sentence in CLAUDE.md. This is also why a subagent may not behave the way you expect even when your top-level rules are clear.
A copy-paste template
Start from this and delete anything that does not apply. It is deliberately short; resist the urge to fill every heading.
# <Project name>
One sentence on what this repo is and who uses it.
## Commands
- Install: <cmd>
- Dev server: <cmd>
- Test (single file): <cmd path/to/test>
- Lint / format: <cmd> # runs on save; do not hand-fix style
- Build: <cmd>
## Architecture
- <Entry point> is where requests come in; <module> owns <responsibility>.
- Data lives in <store>; access it only through <layer>, never directly.
- <Any non-obvious boundary or dependency direction>.
## Conventions
- <Convention that differs from the language default>.
- Prefer <pattern> over <pattern> in this codebase because <reason>.
- Tests live in <path> and follow <naming>.
## Don'ts
- Do not edit <generated dir>; it is regenerated by <cmd>.
- Do not add a dependency without checking <policy>.
- Do not run the full suite for a one-file change; run the single test.
## Gotchas
- <Env var> must be set or <thing> fails silently.
- <Known trap that has cost time before>.That is under fifty lines and every heading maps to something Claude cannot read off the code. As the project teaches you where Claude goes wrong, add the specific gotcha and prune anything that has stopped earning its place — treat the file like code, and review it when behaviour drifts.
In practice the ## Don'ts and ## Gotchas sections carry the most weight, because they encode the mistakes Claude would otherwise repeat: the generated directory it keeps editing, the environment variable that fails silently, the full test suite it runs for a one-line change. Those lines pass the removal test cleanly, and the moment a mistake happens twice is the moment to add one. The ## Commands section is the other reliable win, since the exact invocation for your build and single-test runs is precisely the kind of thing Claude cannot guess and wastes time rediscovering.
The mistake to avoid
The failure is not writing too little; it is writing a wall of aspirational rules and assuming Claude reads all of them equally. It does not. A tight CLAUDE.md, a handful of on-demand skills, and a few hooks for the non-negotiables will change behaviour far more than a five-hundred-line manifesto. If you would rather not assemble the starting point yourself, the Kaairos Engineer Kit ships a filled-in CLAUDE.md template alongside license-audited agents, skills, and commands you adapt to your stack — the value is the curation and maintenance, not secret configuration. For how CLAUDE.md fits next to those other primitives, see skills vs subagents vs commands.