By JaySeptember 2026
When Your AI Agent's Instructions Contradict Themselves
We recently ran a systematic audit of every instruction file feeding our AI coding agents, the CLAUDE.md, AGENTS.md, and skill files that tell an agent how to behave, across seven of our own projects. The tool doing the work was Anthropic's own claude-api skill, specifically its prompt-audit subcommand, built to scan a prompt, skill, or tool description for patterns written for an older, less-steerable model. The premise: instruction files degrade the same way code comments do.
Text tuned for a weaker model doesn't just waste tokens on a newer one. It can actively degrade behavior, because today's models follow instructions far more literally than the older models that language was originally written for.
None of this matters if you're not the one maintaining these files day to day. What does matter (if an AI agent is doing any real work for your business) is the habit it's testing. Does anything ever go back and check that the instructions it's running on still agree with each other? Or does that file just keep growing until nobody's sure which line still applies?
Twenty-eight files, seven projects
The scope: 28 instruction files spanning seven of our own projects, audited in parallel and resolved project by project. Three came back completely clean - every directive in them already tied to a stated reason, nothing dated or padded left to trim. A fourth had exactly one low-confidence item flagged and nothing worth actually changing. The other three needed something real.
What "needed something real" looked like
- One project's main instruction file dropped by roughly 94%, from 85 lines to 5: two full incident post-mortems for bugs that were already fixed and merged months earlier, plus two step-by-step scripts walking the model through routine debugging it doesn't need spelled out.
- One workflow was described three separate times in a single file, each version already slightly drifted from the other two. All three collapsed into one canonical version that the remaining sections now just point back to.
- One older configuration, imported wholesale from a live setup rather than hand-written, needed the biggest cleanup of the seven: the same bug fix documented four separate times across two files, a 55-day-old session snapshot from a one-off event still sitting in live memory, and a hardcoded "it is now 2026" date check that would have quietly gone stale by January.
One of the three otherwise-clean audits turned up something a prompt-cruft scan isn't built to catch: a broken file reference pointing at a file that doesn't exist. It's a different flavor of the same underlying problem Claude Code Imports AGENTS.md - Until It Doesn't already found in Claude Code's own AGENTS.md handling: the file tree can say one thing while the harness actually does another, whether that's an import pointing at a file that was never there, or a real file sitting unread because nothing ever actually loads it. This audit checks whether the words in these files agree with each other. It doesn't independently confirm the harness is reading all of them in the first place; that's a separate check worth running alongside it, not instead of it.
Two files, two different thresholds
Inside that same imported configuration, two files governing the same agent's behavior flatly disagreed with each other.
One file said stop and reassess after 2 failed attempts. The other said after 3.
Nobody had caught it, because nobody reads instruction files end to end looking for internal consistency. A human skim misses it easily, and no linter checks prose against prose. A systematic pass built specifically to compare stated rules against each other caught it on the first try.
Why one config accumulated so much more than the others
Age alone doesn't explain it. A file that just sits untouched for months goes stale, but it doesn't start contradicting itself. What actually happened here is structural: this file isn't a document one person wrote and occasionally edits, it's a running memory log a long series of independent agent sessions kept appending to, each one recording what it had just learned without first checking whether that lesson was already written down somewhere else in the same file. The setup even had its own built-in ritual meant to consolidate and prune that log periodically; it just wasn't being followed consistently.
Duplicate lessons. A rule restated as its own contradiction. A "don't skip this step" reminder sitting right next to proof it had been skipped.
Age is why the stale content lingered instead of getting pruned. The contradictions are the real signature here: multiple independent authors/agents/models layering their own account on top of each other without reconciling it. That's a process failure, not a clock problem.
The takeaway
Across the full set, the degradation wasn't evenly distributed, and it concentrated exactly where you'd expect: not in the file getting daily hands-on edits, but in the one running unattended, accumulating its own history through repeated agent sessions, with nobody periodically reading it end to end. If your agent is allowed to write its own memory over time, that file needs the same review a shared codebase gets, otherwise it just accumulates whatever the last session happened to write, contradictions included.
We run this same audit against every agent configuration we build for a client, before we hand it over and again after it's had time to accumulate its own history. Consistent instructions cost nothing extra to maintain if someone's actually checking them.