Writing a CLAUDE.md the Model Actually Follows

Most project instruction files fail the same way. They read like a wish list written by someone who has never had to follow one: aspirational, unordered, and full of advice that could apply to any codebase on earth.

"Write clean code." "Follow best practices." "Consider performance." None of that changes a single decision.

The files that work read like a senior engineer briefing a new hire on their first morning — specific, ordered, and short enough to actually finish.

Start with what surprises people

The single highest-value section is the one that lists what a competent stranger would get wrong. Not what your project does — what it does differently.

From a real client project:

- Prices are stored in piastres (integers). Never use floats for money.
- Every branch has its own catalog. There is no global product list.
- The checkout does not process payments. It composes a WhatsApp message.
- Arabic is the primary language. Build RTL first, verify LTR second.

Four lines that prevent four days of wrong work. Everything else in the file is less valuable than this section, and it should sit near the top.

Commands, not descriptions

Do not describe the build system. Give the exact commands.

npm run dev      # port 5173, do not change it — the OTP callback is registered
npm run build    # must pass before any handover
npm run test:e2e # requires the dev server already running

Note the comments. The command alone is discoverable from package.json. The constraint attached to it is not, and the constraint is the part that saves you.

Say what "done" means

Ambiguity about completion is where most frustration comes from. If done means the tests pass, say so. If it means the build succeeds and the preview was actually opened, say that instead.

Done means: build passes, no new console errors, RTL checked at 375px,
and the change was verified in the running app — not just in the diff.

Now there is a shared definition, and "it's finished" stops being a matter of opinion.

Keep it under a page

Long instruction files quietly stop being read in full — by people and by models alike. Every line you add dilutes the ones already there.

My working limit is roughly 60 lines. When a file outgrows that, it is usually because I have started documenting the codebase inside it. Codebase facts belong in the codebase; the instruction file should hold only what cannot be discovered by reading the code.

A good test: delete any line whose absence would not cause a mistake. Most files lose half their length and improve.

Write rules as constraints, not preferences

"Prefer functional components" is a preference. It loses to whatever pattern is nearby in the file being edited.

"Do not add class components. This project has none, and adding one breaks the shared hook utilities" is a constraint with a reason, and reasons survive edge cases in a way bare preferences do not.

Whenever I write a rule, I try to include the consequence. It costs eight words and it changes how the rule is applied when the situation is not exactly what I imagined.

Update it when you correct something twice

The file should grow from friction, not from planning sessions. Every time I catch myself giving the same correction a second time, that correction becomes a line. Every time a line stops being true, it gets deleted immediately — a stale rule is worse than a missing one, because it burns trust in the whole file.

The measure of a good instruction file is not how much it explains. It is how many mistakes it prevents per line.

The short version

Lead with the surprising constraints. Give exact commands with their gotchas. Define done. Attach reasons to rules. Delete anything that has not prevented a mistake. Then stop writing — the file is finished long before it feels finished.