Why Claude ignores your CLAUDE.md

The complaint is real and it is not your file

Search for it and you will find the same sentence written a hundred different ways. A thread on Hacker News is titled, almost word for word, "Claude often ignores CLAUDE.md." The replies are not people who forgot to write one. They are people who wrote a careful one, watched it work, and watched it stop.

That pattern matters more than the complaint. A file that never worked is a syntax problem. A file that works and then stops is something else, and it has a name.

What actually happens, in order

Ask for the behaviour and you get it. Ask again and you get it. Somewhere around the fifth or sixth exchange the agent does the thing your file told it not to, and you go back and re-read the file to check you actually wrote it down.

You did. Published measurements of instruction compliance across coding agents put it around 95% early in a session, falling to roughly 20 to 60 percent by message six to ten. That is not a Claude-specific finding and it is not ours. It shows up across tools, which is the strongest signal that it is structural rather than a bug someone will fix.

The reason is unglamorous. CLAUDE.md is loaded as context. Context is finite, it fills with the actual work, and the further the instruction sits from the moment of the decision, the less it weighs. Nothing in the system re-asserts it. The file did not fail. It was read once, at the start, and then the session moved on without it.

The three things people try next, and what each one buys

Writing it more forcefully. Capital letters, "IMPORTANT", "you MUST". This buys a little and it is worth doing, but it treats a decay problem as an emphasis problem. We have measured this on our own tooling: making a routing banner louder did not move adherence at all. Changing the order of operations did.

Making the file longer. Every rule you have ever needed, in one place. This usually makes things worse, because a longer file competes with the work for the same finite context, and the rules that matter get diluted by the rules that almost never apply.

Repeating yourself in the prompt. This works, which is exactly the problem. You are now the mechanism. It does not survive a long session and it does not survive you getting tired.

None of these is wrong. They are all the same move, which is trying to make one early read carry an entire session.

What a durable fix has to do

Three properties, and the third is the one people skip.

Be re-asserted, not just written. The instruction has to arrive near the decision, not only at the start. In Claude Code the mechanism for this is a hook: a small script that runs on every prompt and puts the routing decision back in front of the model. Anthropic's own documentation points the same direction, recommending hooks and re-invoking skills after context compaction. That is a useful thing to know independently of what you use, because it means the fix is not exotic.

Be small enough to route. A router over a thousand unrelated skills is a worse router than one over twenty well-matched ones. This is the least intuitive part. More installed capability makes selection harder, not easier.

Be readable before you trust it. If the thing making decisions on your behalf is not plain text you can open, you have swapped one unverifiable process for another.

What we can and cannot show you

We run this mechanism, so treat what follows as interested and check it yourself.

In our own usage, routing fires on roughly one prompt in four, and precision sits around 88 to 92 percent. Those are internal numbers from our own sessions, not a benchmark, and we do not publish them as a multiple of anything.

We also ran a selection-at-scale check to see whether native skill selection collapses once you have around a hundred well-described skills installed. It did not. So the honest claim is narrower than the one we could make: the problem is not that agents cannot pick a skill, it is that nothing reliably reminds them to pick one on turn nine. Anyone showing you a large efficacy multiple for this should show you the run first.

The smallest useful experiment

You do not need a tool to test this, and you should not take our word for it.

1. Put one specific, checkable rule in your CLAUDE.md. Something with a visible output, like a commit message format or a file it must never touch.
2. Work normally for fifteen exchanges on a real task.
3. Do not remind it. Note the first turn where the rule is broken.

If that number is small, the problem is decay and emphasis will not fix it. If the rule holds for a full session, your setup is fine and you can stop reading about this.

Either way you will have measured your own situation, which is worth more than anyone's blog post about theirs.