A CLAUDE.md that actually gets followed

A CLAUDE.md is pulled into context at the start of every session. That single property decides everything about how to write one: each line is paid for on every task, whether or not it is relevant, and instructions compete with each other for attention as the file grows.

Most files fail by being a place things get added to and never removed from.

What belongs in it

Facts that are always true and would otherwise be re-explained:

• How to build, test and lint. The exact commands.
• Where things live, when it is not obvious from the tree.
• Conventions that a reader could not infer from the code.
• Constraints that are genuinely absolute — what must never be touched.

The test for a line: would I say this in every session? If it applies to one kind of task, it belongs elsewhere.

What does not belong

Procedures. A sequence of steps for a particular kind of work has outgrown this file. Move it to a skill, which loads only when relevant and costs nothing the rest of the time. See Skills, and when to write one.

Explanations of general programming. The model knows what a mutex is.

Aspirations. "Write clean, maintainable code" is not actionable and it dilutes the lines that are.

Anything you cannot state concretely. If you cannot express it as a command, a path, or a rule with a clear violation, it will not change behaviour.

Keep it short, and mean it

Practitioner guidance commonly puts the working limit around 300 lines, on the reasoning that a model reliably follows on the order of 150 to 200 standing instructions before compliance degrades. Treat that figure as folklore rather than measurement — it circulates widely without a study behind it — but the direction is consistent with everything else about context: more instructions means each one carries less weight.

The practical version: if you would not read the whole file before starting a task, do not expect it to be applied as though it had been.

Write rules that can be violated

Vague instructions produce vague compliance.

• Weak: "Follow the existing code style."

• Better: "Use tabs. Single quotes. No default exports."

• Weak: "Be careful with the database."

• Better: "Never run migrations. Propose them and stop."

The second version of each can be checked. The first cannot, which is why it gets ignored without anyone noticing.

Put the important thing first

Attention is not uniform across a long file. If something genuinely matters — a destructive command that must never run, a directory that must never be touched — it belongs near the top and phrased as an absolute.

Grow it from what you correct

The best source of lines is your own repeated corrections. When you find yourself telling it the same thing a second time, that is the line. Anything you have never had to say is a line you are paying for speculatively.

Prune on the same principle. A rule that has not been needed in months is either universally obeyed, in which case it costs nothing to keep, or it describes a situation that no longer arises, in which case it costs on every session for nothing.

What goes wrong

Treating it as documentation. The audience is an agent starting a task, not a new colleague reading for background.

Only ever adding. Every line is a permanent cost and there is no natural moment that prompts removal.

Putting procedures in it. They load every session and apply to almost none.

Vague rules. They cannot be violated, so they cannot be followed.

Assuming a long file is a thorough one. Past a point, more instructions means weaker adherence to all of them.

How to check it worked

Delete the file temporarily and run a typical task. What you find yourself having to explain is what actually belonged in it — and anything you never missed was costing you tokens on every session for nothing.