Why your CLAUDE.md gets ignored

You wrote a CLAUDE.md. You told it the project uses pnpm. Three turns later it ran npm install.

The usual conclusion is that memory files don’t work. They do — but most are written as documentation when they need to be written as a checklist.

The failure has three causes

It’s too long. A 400-line memory file competes with the code, the diff, the conversation and the tool output for the model’s attention. The rule you care about is on line 280, between a paragraph about your CI history and a list of contributors. It is technically present and practically invisible.

It’s not testable. “Write clean, maintainable code” cannot be checked, so it cannot be followed or violated in any detectable way. It reads as encouragement. Compare:

<!-- unfollowable -->
- Prefer good error handling.

<!-- followable -->
- Every `catch` must either re-throw or log with the request id. Never swallow.

The second one is a rule. You can look at a diff and say yes or no.

It explains instead of instructing. Background is expensive. If a rule needs a reason, give it in one clause, not a paragraph — and only where the reason changes the behaviour.

What a working file looks like

# Project rules

## Package manager
- Use `pnpm`. Never `npm` or `yarn` — the lockfile is pnpm's and mixing them breaks CI.

## Tests
- Anything touching `src/payments/**` needs a test in the same commit.
- Run `pnpm vitest run <area>` before saying a task is done. Do not report done on a red suite.

## Database
- Migrations are forward-only. Never edit a migration that has shipped; add a new one.

## Don't
- Don't reformat files you didn't otherwise change.
- Don't add dependencies without saying why in the commit message.

Roughly forty lines. Every line is checkable. A reviewer could hold a diff against it and reach the same verdict the model should have reached.

Put the sharp edges at the top

Attention is not uniform. Instructions at the very top and the very bottom of a long context are followed more reliably than instructions buried in the middle — the same “lost in the middle” effect that shows up across long-context evaluations.

So order by damage, not by category. The rule that prevents a production incident goes first. The naming convention goes last. If your file opens with a project history section, the most important thing you have to say is already in the weakest position on the page.

The habit that actually fixes it

Don’t write the file up front from imagination. Grow it from real failures.

Every time the assistant does something you have to correct, ask whether the correction is general. If it is, add one line. If it isn’t, let it go. Within two weeks you’ll have a short file where every line was paid for by a real mistake — which is exactly the file that works, and nothing like the aspirational one most people write on day one.

And prune it. If a rule hasn’t been relevant in a month, it’s diluting the ones that are.

The rule

A memory file is a checklist the model reads under pressure, not documentation it reads for pleasure. Rules must be specific, testable, and few.