Skip to content
Contact

Claude Isn't Ignoring Your CLAUDE.md. Your Old Rule Is Still in There.

Taylor Turner10 min read

Your coding agent just followed a rule you changed a month ago. It sounded sure of itself. You went looking for where it got the idea and found the old rule still sitting there, in a file you'd forgotten the agent reads, right next to the correction you wrote when you changed it.

If that hasn't happened to you, there's a quieter version. The agent gets the right answer, but the session feels slow and the bill is higher than the task deserved. Nothing is visibly wrong, so you don't go looking. A capable model is working around a contradiction in your docs on every prompt, and the only sign is cost and waiting.

I've met this one in both forms. This article is about where it comes from, what it costs, and the one line that fixed it.

How old rules pile up

Old instructions never leave an agent's docs and memory on their own. Nobody put a wrong rule in the file. The world moved and the file didn't.

They accumulate in ordinary ways:

  • A correction gets added next to the rule it corrects. It's faster to append "actually, do X now" than to find and rewrite the original sentence. Both versions stay.
  • A one-off instruction becomes permanent. You tell the agent "for this task, skip the tests," and it saves that to memory as a standing rule.
  • A decision has nowhere else to live. You made a choice and need to record it, and the only file you know the agent reads is the one it reads on every prompt. So it goes there, and stays there long after it stops mattering.

Eventually the same rule exists in three versions across three files, and nothing says which one is current.

I call that point tangle: the moment the rules start to contradict each other. Old rules on their own are cheap. In my testing, extra volume with no contradictions didn't change which rule the model recalled. Tangle is where the bill starts. An SRE would call it split-brain: every version of the rule thinks it's the one in charge, and nothing holds the election.

A person in that spot would ask someone. The agent can only read, so it picks. In my experience it tends to pick whatever looks newest, and "looks newest" is a weak signal when corrections sit beside the things they correct and memory files are loaded in an order you didn't choose.

Six layers for one sentence

Here's what it looked like in CertWatch, my pre-launch product for tracking TLS certificate expiration. One file in Claude Code's memory covered how changes get merged. Most of it dated from the repo's first days, before it had a staging environment or users. When I finally read it top to bottom, it held six layers:

  1. A switch from pushing straight to main to opening PRs, reversing advice from earlier the same day.
  2. A note that production deploys on every push to main, later marked "no longer true."
  3. A statement that branch protection wasn't available, later corrected.
  4. A description of when staging deploys, later corrected.
  5. "Merge once green," which an agent read as standing permission, later corrected to "always wait for an explicit merge instruction."
  6. A temporary exception for one skill, which ended when the skill was retired.

The rule that actually matters fits in one sentence: work on a branch, open a PR, merge only when explicitly told (and only if CI and PR reviews are resolved). An agent had to read through all six layers to find it, and layer five is the one where landing on the wrong version means a merge I didn't ask for.

The same memory index also carried several tombstones. A tombstone is an entry whose only job is to say that something no longer exists: a retired keyword workflow, three retired skills, an old secrets setup, a retired Notion database. Each one is a few lines the agent reads on every prompt to learn about a thing it will never touch.

The skill that didn't fire

Tangle doesn't only make the agent pick the wrong version of a rule. It can also bury a rule that's right, and I ran into this one just last week. I was building a review skill: a contract that tells a reviewer agent what to report, and a folder of personas it can read as. The whole thing is documents written for an agent. We have a skill for exactly that, /author-docs. After a long Claude Code session drafting the issue, I asked whether we'd used it.

We hadn't. Not once. So I had the session load it and read its own draft. It came back with a list, and one item on it was a tangle.

The word "honest" appeared fourteen times across six persona files, and it meant something different in each: blunt in one, quotes everything in another, admits what it doesn't know in a third. Six homes for one word, and no file saying which definition a reviewer should use. The skill's rule is that a definition lives in one place and everything else points to it. I'd built a tangle inside a tool for finding tangle.

Then the part that stuck. The skill was there. It was a standing rule for docs in that repo, listed where the agent could see it, and we'd been writing a skill and then an issue about the skill across several sessions. None of them loaded it. When I asked, Claude said so in one line: it hadn't been using it, and it should have. No stale rule, no missing pointer. A current rule the agent could reach, and didn't, until someone asked.

What happened is easy to trace. The agent had layers of rules to reason through, and the one it matched on was how we write an issue, because issues are how we track work. That rule is right, but it applies later. The design wasn't settled yet, and settling it meant using the skill. Writing the issue should only have started after that. With that many rules in front of it, the agent picked the one that fit the surface of the task and never reached the one that fit the stage.

Nothing in the skill was stale, and no two rules contradicted each other. This is what tangle does short of contradiction: with enough layers to reason through, a right rule gets passed over for a nearer one, and nothing makes the agent check. The only thing that caught it was the question.

What tangle costs

I wanted to know what tangle does to the model, not just to me, so I built a small test: a repo's docs and memory with the same contradictions I'd found in my own, thirty situations where it had to say what it would do, and a few hundred runs on each of two models. The results were consistent.

  • On tangled docs, Claude Sonnet 5.5 followed an outdated rule 18% of the time. On clean docs, it never did.
  • Claude Opus 5.5 was right 96.3% of the time on the same tangled docs. It did it with about twice as much thinking as it used on clean docs, and each answer took almost twice as long. On a smaller model, tangle shows up as wrong answers. On a bigger one, it shows up as cost and waiting.
  • Load order made it worse, and you don't control it. When the memory files loaded before the main instructions file, Sonnet was wrong 56% of the time and Opus 33.3%.
DocsSonnet accuracySonnet tokens / timeOpus accuracyOpus tokens / time
Clean98.0%111 / 1.6s100%182 / 2.8s
Tangled80.0%1.8x / 1.4x96.3%2.2x / 1.8x
Tangled, memory first44.0%3.4x / 2.3x66.7%2.6x / 2.1x

Tokens are the mean per answer, time is the mean seconds per answer, and the multiples are against the Clean row.

One line that fixed it

A line at the top of AGENTS.md saying which part of the docs is current took Sonnet from following an outdated rule 18% of the time to 0.3% and Opus's thinking from 2.2x back to 1.3x. With memory loaded first, the same line took Sonnet from 56% to 7.3% and Opus from 33.3% to zero. This is the line, as tested:

The ## Rules section below, and each doc in docs/ above its first ## heading, are current. Later sections, notes and files in .agent/memory/ may be older; where they disagree with those, follow the rules.

It names that repo's layout. The shape is what matters: which part is current, which parts may be older, and which wins.

Docs, with the lineSonnet accuracySonnet tokens / timeOpus accuracyOpus tokens / time
Tangled99.0%1.1x / 1.0x100%1.3x / 1.2x
Tangled, memory first92.7%1.3x / 1.2x100%1.3x / 1.2x

This is the result I'd want someone to take away. The expensive part of tangle isn't the stale rule. It's the model having to decide, on every prompt, which rule you meant. Telling it once removes the decision.

How we organized things

The cleanup followed one idea: every kind of thing gets one home, and the file the agent reads on every prompt keeps only what it needs every time.

  • Decisions live in ADRs. A decision is a record of why, and why doesn't need to load on every prompt.
  • Terms live in a glossary.
  • Repeatable procedures live in skills, loaded when the task needs them.
  • Open gaps live in the issue tracker, not in a "known issues" paragraph that outlives the issue.
  • Narrative, the story of how we got here, lives in Notion. People read it. Agents don't need to.

Three rules keep it that way:

  • A correction replaces the rule it corrects. No appending. If a rule changed, the old sentence is gone and the file reads as if the new rule had always been true. Git keeps the history.
  • One line at the top says which part wins. When two files disagree, the agent shouldn't have to guess. The precedence line is the single sentence from the test above.
  • Memory gets a regular review. Memory is where one-off instructions turn permanent, so it needs a scheduled look. Claude Code's /doctor every week or two is enough, followed by deleting whatever no longer describes the repo.

What I don't know yet

The test was small and used specific models and one tool. Another tool may load files in a different order, and that order can change under you with an update. The precedence line only helps if the section it points to is actually right; it moves the decision from the model to you, which is where it belongs, but it doesn't make the decision for you. And I don't know yet how fast a clean setup piles up again.

What I'd tell someone cleaning up

  • Put one line at the top of your AGENTS.md or CLAUDE.md saying which part is current when two disagree. Mine, in plain form: "The Rules section of this file, and the top of each doc above its first heading, are current. Anything below that, and anything in memory, may be older. Where they disagree, follow the rules." Do this first. It's the cheapest fix with the biggest effect.
  • Pick one rule you know has changed. Search for it across every file the agent reads, including memory. Keep one copy.
  • When you correct a rule from now on, rewrite the sentence instead of adding one after it.
  • Move decisions, terms, procedures and open gaps out of the every-prompt file and into one home each.
  • Delete tombstones. If a thing is gone, the agent doesn't need a note saying so.
  • A rule can be right, reachable, and skipped. Ask the agent which rules it applied. The answer is sometimes "none," and it will say so.
  • Read the agent's memory on a schedule. /doctor every week or two is enough. Treat anything that reads like a one-off as a candidate for removal.

There's nothing clever in any of this. It's the same hygiene I'd apply to a runbook at work: one source of truth, corrections that replace, a review cadence. The difference with an agent is that nobody gets to ask a question. A person who finds two versions of a rule asks which one you meant. The agent reads both, picks one and sounds sure. The docs have to answer the question before it's asked.

If you've found your own six-layer file, I'd like to hear what the one sentence turned out to be.

Share

ZeroFault Labs helps owner-led service firms build practical AI workflows and hand them over. How AI Workflow Consulting works