A CLAUDE.md is a brief, not a manual.
It is read on every task, so everything in it competes for attention with everything else.
Every line costs attention on every single task — which makes omission the hard skill
A project instruction file is prepended to the model's context for every request in that repository. That framing settles most arguments about what belongs in it. Facts the model can discover by reading the code do not belong — it will read the code. Explanations of how a well-known framework works do not belong — it knows. What belongs is the non-obvious and non-discoverable: the constraint that is not visible from any single file, the convention the codebase violates deliberately, the command that must be run a specific way, the thing a competent newcomer would get wrong on their first day. Most CLAUDE.md files fail not by containing something wrong but by containing so much true-but-obvious material that the two lines that actually matter are buried in it.
- Include
- Constraints not visible from any one file. Deliberate deviations from convention.
- Include
- Exact commands — build, test, deploy — where the obvious guess is wrong.
- Include
- The quality bar and who the output is for.
- Omit
- Anything discoverable by reading the code. It will read the code.
- Omit
- General framework or language explanation. That is training data.
- Omit
- Aspirational rules nobody enforces. They dilute the ones that matter.
- Length
- If it does not fit on one screen, the important lines are competing with filler.
FAQ
Short enough that every line earns its place, which in practice is usually well under a page. The failure mode is not a file that is too terse — it is one where three genuinely load-bearing constraints sit inside two hundred lines of accurate but discoverable description, and get weighted the same as everything around them.
Only the part that is not visible from the code. "This is a Next.js app with a Cloudflare worker" is discoverable in seconds. "The worker and the app share a types package that must be rebuilt before the app typechecks" is not, and is exactly the kind of thing worth writing down.
Emphasis inflation. Files accumulate CRITICAL, MUST and ALWAYS on rules that were added because a model once got them wrong, and current models follow instructions closely enough that the shouting causes over-application instead. Say it once, plainly, with the reason.
A README explains the project to a human deciding whether to use or contribute to it. A CLAUDE.md tells an agent how to work inside it. They overlap on setup commands and diverge everywhere else — most of a good README is exactly the discoverable material a CLAUDE.md should leave out.