A Good CLAUDE.md: What to Put In It (and What to Leave Out)

CLAUDE.md is the closest thing Claude Code has to long-term memory: a file it reads at the start of every session and keeps in context throughout. Get it right and the agent knows your conventions without being told; get it wrong and you're either repeating yourself every session or drowning the model in a 500-line wall it skims. Here's what actually belongs in it.

Where it lives

Claude Code loads CLAUDE.md from a few places and concatenates them:

• Project — ./CLAUDE.md (checked into the repo, shared with your team).
• User — ~/.claude/CLAUDE.md (your personal rules, every project).
• Local — ./CLAUDE.local.md (project-specific, git-ignored, just you).

All of them load automatically every session and survive /clear. That's the power: whatever's in there is present every time, so you never have to say it again.

What belongs in it

Standing rules the agent should never have to be told twice:

• Conventions — "use the repository pattern," "prefer composition," "tests go in __tests__."
• Architecture orientation — the two or three sentences on how the project is laid out and where the important things are.
• Commands — how to build, test, lint, and run, so it doesn't guess.
• Hard rules — "never edit generated files," "always run the typecheck before claiming it's done," "don't touch the migrations."
• Gotchas — the non-obvious landmines specific to your codebase.

The test: anything you find yourself correcting more than twice belongs in CLAUDE.md. (When Claude keeps repeating a mistake →)

What to leave out

Here's the part people miss: CLAUDE.md is re-sent to the model on every single turn. A bloated one is a tax you pay continuously — and past a certain size the model skims it, so more text means less adherence, not more. Leave out:

• Long prose and history — it's instructions, not a README.
• Anything the agent can just read — don't paste files it can open itself.
• Duplicated docs — link, don't inline.
• Everything "nice to have" — if it isn't load-bearing, cut it.

Tight and imperative beats long and thorough. (Why a bloated context costs you every turn →)

Keep it a living file

The good CLAUDE.md is short and grows only when a real mistake teaches you a new rule. Prune it like code. And when you're running several sessions off the same CLAUDE.md, Mwah shows you all of them at once — so you can see, at a glance, which agents are honoring your rules and which have gone off the rails.

---

Related: Claude Code keeps making the same mistake · Why Claude Code burns tokens