5 ways your CLAUDE.md rules quietly fail
# CLAUDE.md
- Always write production grade code.
- Never introduce a regression.
- Be thorough, consider edge cases.
Three rules.
None of them will ever fire.
Not because the agent is lazy.
None of them are instructions.
They are wishes wearing the costume of rules.
I work inside a setup with a large rule library and enough observability to see which rules fire and which sit there as decoration.
That gap is wide.
Most rules read like aspiration.
A few read like physics.
After watching a lot of them hold and a lot of them rot, the failures land in five clean categories.
If your agent keeps ignoring your own instructions, your rule is almost certainly one of these.
1. Aspiration with no edge
"Be thorough." "Write quality code." "Handle errors properly."
Read one out loud and ask a simple question.
What would it look like to violate it.
If you cannot answer in one sentence, the agent cannot either.
A rule the model cannot fail is a mood.
It nods at the line and moves on, because nothing concrete exists to obey.
Repairing this takes one testable sentence. A line you can hold against a diff and answer yes or no.
2. No trigger
This one is specific enough to obey. It still fails.
"Use the new auth pattern."
When.
On every file. Only auth files. Only new code. Only when touching login.
Nothing in the rule says, so the agent guesses.
Sometimes it guesses right. Sometimes it does not.
You read that as the agent being unreliable.
It is the rule staying silent about its own moment.
Every real instruction carries a trigger, the condition that wakes it up.
Strip that trigger and the rule fires at random, which from the outside looks identical to the rule being ignored.
3. No enforcement
Now your rule is specific and it carries a clear trigger.
It still breaks on the long sessions.
Only one thing is holding it up, the agent remembering it.
Early in a session, with the rule fresh in context, compliance looks perfect.
Two hours in, after the context has been squeezed and rebuilt, that rule is a faint memory competing with a hundred others.
Memory does not enforce anything.
A rule that lives only in the model's attention degrades exactly when you need it most, on the long, tired, high stakes session.
A durable rule has a backstop. Something outside the model that notices the miss and says no.
What that backstop is matters less than the fact that one exists.
4. Contradiction with no precedence
Two rules. Both correct. They disagree.
One says move fast and keep changes small.
Another says add a test for every new behavior.
On a one line fix, which wins.
If your rules do not say, the agent obeys whichever it noticed last.
That is a coin flip with extra steps, dressed as a decision.
Contradiction is fine. Real systems carry competing goals.
What is missing is precedence, a stated order so the tie resolves the same way every time, instead of depending on which rule landed closest to the cursor.
5. Stale reference
This is the worst one, because it used to work.
Your rule names a file, a function, a flag, a path.
Then the thing moves. Gets renamed. Gets deleted.
The instruction does not move with it.
Now it points at nothing, or worse, at whatever took the old name.
A rule that lies does more damage than a rule that is missing.
A missing rule fails open and you notice.
A stale rule fails confident. It sends the agent at the wrong target with full authority, and the green log hides it.
Every rule that names a specific artifact carries a small debt. Each time that artifact moves, the line turns into misinformation unless something updates it in the same motion.
What sits under all five
Sharpen the pattern and the five collapse into one test.
What makes this rule fire, and what catches it when it does not.
A rule with no answer to both halves is aspiration. It will shine in the demo and rot in production.
A rule with an answer to both is closer to physics. It holds when the session runs long and the context runs tight and nobody is watching.
Most CLAUDE.md files I read are ninety percent aspiration in the costume of physics.
Honesty fixes more of this than better sentences do.
Be clear about which of your rules can fire, and accept that the rest are notes to yourself.
Notes to yourself are fine. Calling them rules is how a file slowly stops meaning anything, one ignored line at a time.
Your turn
Open your own CLAUDE.md or agent rules right now.
Pick one rule and run the two questions on it. What makes it fire, what catches the miss.
Then tell me which of the five your weakest rule falls into.
I am curious which one bites hardest in the wild, because in my own library it is number three.
