The measurement
The file that only grows
Your CLAUDE.md has never once gotten shorter. On August 11, 2026, a paper landed on arXiv with a title that reads like a support ticket: “Why Does CLAUDE.md Keep Growing? Catastrophic Remembering in Agentic Coding.”
The authors traced 247,694 instruction lifetimes across 1,867 repositories. Agentic prompt files “grow without bound,” more than tripling over their lifetime (plus 226%) and gaining 4.9 net instructions every commit. Growth stops for two reasons: the repository dies, or somebody throws the file away and starts over.
The older an instruction gets, the less likely anyone is to delete it. Log-hazard of −0.032 per commit. Every line in your CLAUDE.md is accruing tenure.
They name the mechanism catastrophic remembering, the inverse of catastrophic forgetting. Appending an instruction is free. Deleting one, once nobody remembers why it was added, means proving it safe against every combination of the instructions around it: O(2^|D|) for a prompt of |D| instructions. The file becomes a landfill with a table of contents.
The lived version
It just has to be slightly behind the code
In July 2026, a developer three weeks into building a product with agents asked Claude what in his own docs was hurting its reasoning. He had been disciplined about it. The write-up drew 177 upvotes, which is Reddit for oh no, mine too.
His three read-before-you-code docs totaled 1,085 lines, roughly 75% of it finished work: checked-off checklists, phase completion logs, old verification notes. The pricing doc stated the enabled payment methods two ways, one with a line-number reference to a line that no longer existed. Two features were marked “awaiting merge/deploy” while sitting on main for days.
And the detail that belongs in a museum: a hard rule in AGENTS.md pointed at a sibling repo through a Windows path, A:\Dev\.... He had moved to WSL. The rule was impossible to follow, and no agent ever flagged it.
agents trust these files more than they trust their own searches. That's by design, it's what the files are for. But it means the doc doesn't have to be wrong in an obvious way to do damage. It just has to be slightly behind the code.
A 63-point reply drew the rot in four lines. Claude loves logging to a doc, the commenter noted, but “it rarely deletes things, it prefers to append them instead.” So you get:
The asymmetry
Nothing in the repo notices
Every other artifact in your repository has something that screams when reality diverges from the description. Types have a compiler, tests a runner, infrastructure a plan-diff, dependencies a lockfile. Even your YAML has a schema.
Your spec has a spell-checker.
A June 2026 prevalence study across 10,008 public GitHub repositories and 6,145 agent config files found configurations “are rarely revised”: 58% have a single commit, ever. Age-normalised, they change 0.4 times a month against 0.6 for CI/CD workflows in the same repositories. Fewer than 1% declare any permission boundary; the YAML, which only runs tests, manages 33%. And 10.1% of tracked config paths are SHA-256 duplicates of a file in an unrelated repository, three-quarters of those pairs crossing organisations: copy-paste inheritance with no upstream.
- Growth over a file's life
- +226%
- across 247,694 instruction lifetimes in 1,867 repositories
- Configs never revised
- 58%
- have exactly one commit, across 10,008 repositories
- Repos with stale references
- 23.0%
- found by a pre-agent docs linter, pointed sideways
A June 2026 paper coined “context rot” and measured it lazily, pointing a pre-agent README-and-wiki consistency checker at AI config files. On a statistically representative sample of 356 repositories, it found stale code-element references in 23.0% of them.
A March 2026 Hacker News comment under a 322-point thread reported 10 to 84% of symbol references stale in TypeScript repos: a model reading a CLAUDE.md that names a function renamed three weeks ago “is getting a confident lie.” Treat the range with suspicion; the commenter sells a tool that finds them. The phrase stands regardless.
The failure mode
A stale spec is not ignored, it is obeyed
The February 2026 ETH Zurich evaluation of AGENTS.md files is cited for its headline: context files don't reliably improve success rates while adding over 20% to inference cost. The clause underneath: “while instructions in the context files are well followed by coding agents, repository overviews, although popular and recommended by model providers, are not helpful.”
Well followed. A stale rule gets executed, promptly, with a cheerful summary of what it did.
A May 2026 factorial study across 1,650 Claude Code sessions and 16,050 function-level observations found each additional generated function carries roughly 5.6% lower odds of compliance. None of four structural variables moved the needle: file size, instruction position, architecture, contradictions in adjacent files, all null after correction, Bayes factors of 0.05 to 0.10 affirmatively supporting the nulls. Reformatting your CLAUDE.md is a craft project, not a fix.
In July, a 325-point Hacker News thread carried HANDBOOK.md, a benchmark for whether long policy documents reliably govern agents. They do not. One commenter reported asking Claude to crawl its own history logs: after it breaks a rule, the probability of breaking rules rises, “like few-shot in reverse.”
The Constraint Decay thread in May named the part nobody instruments: that paper measures within-turn decay, but “the version that bites in multi-agent setups is across-session — the architectural rules an agent wrote down on Monday don't reach the agent making the next change on Tuesday.”
The mechanism
Nobody ships a conflict checker
Growth is only expensive. Conflict is what makes it fatal. The factorial study nulled a different claim: contradictions between adjacent files had no detectable effect on average compliance. The conflicts below sit inside one prompt, mathematically unsatisfiable. Different mechanism, different measurement, and only the second has a body count.
A paper posted July 31, 2026 benchmarked verifier-checked instructions as they stack up. Follow rate starts around 96% at one instruction and falls to as low as 20% by twenty. The cause is pairwise conflict: in their set, a single “output JSON” constraint is jointly unsatisfiable with nine others. A prompt compiler recovered about 11 points for weak models and roughly nothing for strong ones.
Instructions arrive at 4.9 net per commit and never leave. You are maintaining an unindexed constraint solver with no conflict detection and no way to query it.
A June 2026 study of 100 popular repositories with AGENTS.md or CLAUDE.md files found the smells are the norm: lint leakage in 62%, context bloat in 42%, skill leakage in 35%. Once you have “50 different kind of instructions that have been grown over the years from commits, documentations, code,” a July commenter noted, there might be contradictions. Two files, one saying npm run test and the other npm run test:unit, is a coin flip that looks like a config.
The standard itself is a suggestion. AGENTS.md mandates nothing: no schema, no validation, no versioning, no staleness mechanism. Its steward, the Linux Foundation's Agentic AI Foundation, lists “AGENTS.md v1.0 — first stable behavioral specification” as a future roadmap item. In July, Anthropic published new context-engineering rules for the Claude 5 generation to a 463-point thread, where readers picked up its claim to have removed 80% of its own system prompt, and noted the new claude doctor command for shrinking yours. The 80% is Anthropic's figure, unaudited.
The flagship spec-driven IDE has no drift detection either. In Kiro issue #9435, opened June 15, 2026 and still open, a user asks AWS to record a git ref in spec metadata, because “there's no way to know what state the code was in when a spec was created — you have to manually check if relevant files changed.” The objection that git covers this dies in one sentence: “The git history of the spec only tells you when the spec changed — not whether the source code it references has diverged.” GitHub's Spec Kit is the one shipped tool with a named drift gate, /speckit.converge, released June 18. It has over 126,000 stars and, in this window, zero published adoption or outcome numbers.
The counter-evidence
The steelman wins on the scoreboard
I would love to say the measurements support building a specification IDE. They mostly do not.
The heaviest blow is an April 2026 controlled study of 679 rule files containing 25,532 rules across 5,000-plus Claude Code sessions on SWE-bench Verified. Random rules improved performance as much as expert-curated ones: both +13.8 percentage points, measured on a subset of tasks chosen to be discriminative. Pass rates stayed flat as rule counts went from 0 to 50. The one durable finding is polarity: every individually beneficial rule was a negative constraint (“do not refactor unrelated code”), every individually harmful one a positive directive (“follow code style”).
If a random file helps as much as your curated one, the thing you spent Tuesday afternoon wordsmithing was ballast with good intentions.
In August 2026, someone ran eight AI agent memory systems through 2,176 scored tasks: 272 each, including 72 questions about facts never stored to catch invention, scored by a judge calibrated against two human labelers. A plain markdown wiki that the agent curates itself, following Karpathy's llm-wiki gist, scored 98.5 and beat every commercial product. The best hosted product managed 96.9. The products lost where tooling is supposed to win: Zep's median time-to-freshness for a just-stored fact was 162.7 seconds, and it passed 8 of 24 update questions. It is one person's benchmark, self-run and self-published, so hold it loosely. But it is the only head-to-head in the window, and plain text won it.
The winning entry comes with an asterisk: that wiki is one the agent curates itself. Something rewrites it on a loop. That is the deletion mechanism markdown lacks, bolted on from outside. The benchmark is evidence for markdown plus a compaction loop, not for markdown.
Two of my three complaints take real damage here. Conflict detection: the adjacent-file nulls say contradictions matter less than I would like. Markdown as a terrible place to keep a spec: a curated wiki held up fine. What survives untouched is staleness, for a boring methodological reason: every null above measures average success on a benchmark. None measures the cost of one obeyed stale symbol name in a repository the model has never seen, because SWE-bench tasks barely exercise repo-specific drift. That is not the same as the failure mode being absent. The A:\Dev\... rule is what it looks like when it lands.
My favourite argument in the whole pile is a 28-point aside from April: “I've been through enough ticketing system migrations (actually through 3 different JIRA instances) not to trust that the ticketing system will always exist.” A markdown file in the repo outlives every tool you would migrate it into. That is risk management wearing nostalgia's coat, and no vendor has an answer to it.
The strongest objection came in July from a since-removed r/ExperiencedDevs post that reached 1,248 points: “Good luck replacing actual, deterministic programming languages with 10-KLOC, ambiguous, hand-wavy ‘specs’ written in markdown.” That cuts both ways: no authoring environment saves you, because the spec is lossy by nature.
What worked
What measured better was compiling it
Markdown is a fine place to write a specification, a terrible place to keep one: no mechanism for deletion, none for conflict detection, nothing that tells you it went stale. The 2026 measurements do not reward better prose. They reward prose a machine can fail.
ContextCov, posted February 28, 2026, compiles AGENTS.md into AST queries, shell shims, and architectural validators. Across 300 tasks in 12 repositories it hit 88.3% constraint compliance, against 67.0% for prompt-only and 50.3% for asking the model to check its own work, at 3.4× lower feedback cost.
- Compile itProse turned into AST queries and validators: 88.3% constraint compliance against 67.0% for prompt-only
- Probe itGuidance tested against the repo resolved 33.0% of tasks against 28.3% for a written knowledge base
- Phrase it negativelyEvery individually beneficial rule was a constraint on what not to do, never a directive
A June paper made the guidance argue with the repository first, using synthetic bug-fix probes to patch the parts that were wrong. Refined guidance resolved 33.0% of SWE-bench Verified, against 28.3% for the written knowledge base it started from and 25.5% for nothing at all, p < 0.001 on both. Two caveats: the runs used Qwen3.5-35B rather than a frontier model, and the win is coverage, not precision.
The practitioners got there first. Fiberplane's Drift, announced March 25, 2026, anchors markdown prose to code symbols with tree-sitter and a git SHA, and fails CI when they diverge: “a CI gate that says ‘you touched AuthConfig, now update the spec that describes it.’” Mike Hearn, in a 287-point May thread, moved his acceptance criteria to Markdown plus Gherkin so “they become executable and analyzable” and you can “navigate from any specific acceptance criteria to the code which tests it.” A 402-point r/ClaudeCode post in February described 3,000 hours converging on /pmatch: “drift detection, mechanized. Two agents (Sonnet + Kimi) independently extract claims from a source-of-truth document and verify each against the target”. That is a person hand-assembling a compiler for prose because none shipped.
Even the skeptics arrive at the same rule. Patrik Björklund, whose February post is the best defence of disciplined context files in the window (57 lines global, 289 project, a hundred-plus skill files loaded conditionally), concedes the point: “if a rule can be enforced by a linter or pre-commit hook, do that. Reserve context files for things that can't be machine-enforced.” He also says, “Am I fooling myself…? Maybe. I haven't run controlled A/B tests.”
Under 652 points in March, the unanswered question: “Why is everyone still talking about markdown files as the only form of spec? … Stop being so text-file-brained?” A 473-point thread the day before had the requirement list: “Specs are subject to bit-rot, there's no impetus to update them as behaviour changes… There's no way to systematically determine if the behaviour of your system matches the specs.”
The missing primitive
English is the new code and has no comments
The August 11 paper names what nobody built: a comment. A place to record why a rule exists, so a person or a script can later establish the reason is gone and delete the line.
Inverting IFEval into worlds where the optimal prompt is known, comments encoding the latent reasoning removed 99.3% of excess instructions, taking bloat in that setting from +211.3% down to +1.4%. On WildIFEval, the same trick improved agentic instruction-following by up to 23.1%.
C got comments in 1972. We spent 2026 writing our most consequential instructions in a format that cannot tell a rule from a rule's obituary, then acting surprised when agents follow both.
On August 11, 2026, the industry measured what everyone suspected, then asked out loud: “If English is the new code, why don't we have comments yet?”
Nobody has an answer. The next tool worth having will not help you write a specification. It will tell you, without asking a model to guess, which parts of yours stopped being true. Until it ships, you are the compiler.