CLAUDE.md Sprawl: The Math That Explains Why Nobody Prunes

Agent instruction files , CLAUDE.md, AGENTS.md, and their variants , are following the same lifecycle as every config file before them: they grow until they collapse. New research puts numbers on why this pattern is nearly unavoidable, and what the failure modes look like when nobody intervenes.

The Asymmetry That Explains Everything#

Appending a rule to an instruction file costs nothing. You add one line, the agent reads it on the next turn, done. Deleting a rule safely is a different problem. Each rule can be depended on by other rules, interact with model defaults, and suppress or enable behaviors that will only surface under specific task conditions. The paper "Why Does CLAUDE.md Keep Growing? Catastrophic Remembering in Agentic Coding" analyzes 247,694 instruction lifetimes across real repositories and formalizes the cost: appending is O(1), while safe deletion without regression is O(2^|D|), exponential in the number of dependent rules.

That asymmetry is not a discipline failure. It is the correct local optimization for a team with finite time. Every individual append is rational. The accumulated result is not.

What the Population Data Shows#

A SCAM 2026 study from the IEEE Source Code Analysis and Manipulation conference examined 100 popular open-source repositories and cataloged configuration smells in their CLAUDE.md and AGENTS.md files. Only 9 of 100 files were smell-free. Lint Leakage appeared in 62% of repos, Context Bloat in 42%, Skill Leakage in 35%.

Separately, a deterministic analysis of roughly 30,000 public repositories carrying agent instruction files found only 27% of the average file is doing actual instruction work. The other 73% is scaffolding: headings, restated context, prose that arranges the file without telling the model to do anything. The same analysis found that 89.9% of agent configs carry at least one instruction that never names a concrete construct , a rule like "keep the code clean" that reads fine to a human and binds nothing in the model.

Two data sets, two methodologies, converging on the same picture: nearly every instruction file in production is mostly noise, and almost none have been audited for internal contradiction.

How Conflicts Resolve Silently#

The specific failure mode here is worse than bloat. When two rules in a file contradict each other, modern models do not surface the conflict. According to the Reporails analysis, when two instructions conflict, Claude Opus 5 follows the latest rule in the set and drops the other , silently. The losing rule reads as flakiness rather than a diagnosable conflict. Teams add another rule to fix the behavior they observe, which may itself conflict with something upstream. The file grows. The contradictions multiply.

Anthropic's own engineering noted the same problem internally: transcripts showed "several conflicting messages in a single request," with the system prompt saying DO NOT add comments while a skill said leave documentation as appropriate. The model resolves the conflict , spending capacity on reconciliation before it starts the actual task.

An ETH Zürich study of repository context files found that descriptive overviews , exactly the scaffolding that accumulates , do not improve results and add over 20% to inference cost. That cost is paid on every turn.

The Coverage Gap Nobody Accounts For#

One detail that compounds the problem: not every agent reads the instruction file. Amit Kothari's July 2026 analysis documents that Claude Code's built-in Explore and Plan subagents skip CLAUDE.md entirely. Anthropic's subagents documentation states this rule, and there is no setting to change it. The answer never appears in the session transcript, so teams have no audit trail showing which agents operated without which rules.

A file that two agents skip is not a file. It is a partial configuration with unknown coverage and no visibility into the gaps.

Why This Is a Code Governance Problem#

The lint config parallel is exact. .eslintrc files follow the same path: one rule per incident, added by whoever debugged that session, never removed when the underlying issue changes. The difference with agent instruction files is that a stale lint rule produces a warning. A stale or contradictory instruction produces behavior that looks like model flakiness , hard to attribute, easy to paper over with another rule.

The correct treatment is the same as for any production configuration: version every change, check for contradictions statically (not by running the model against itself), and prune on a defined schedule. Boris Cherny, the engineer who built Claude Code, recommended at a Y Combinator event in August 2026 that teams delete their CLAUDE.md every six months and observe what the model does without it. That advice is operationally sound for individual developers. For a team with shared configuration and compliance requirements, wholesale deletion cannot tell you which rules were load-bearing, and learning by failure in production is not a governance strategy.

The Reporails analysis puts the specific problem with delete-and-observe clearly: a low-specificity rule does not break when removed, it underperforms silently. A conflicting rule resolves silently. Deletion only reaches the third defect, bloat. The other two require a static read of the file's structure.

What Governed Instruction Files Look Like in Practice#

Hyrax's code quality scans already surface the contradiction patterns this creates , rules that cannot simultaneously hold, instructions scoped to paths that no longer exist, duplicated directives across configuration layers. The same reasoning that applies to dead code and stale API contracts applies here. An instruction file is code. It has dependencies. It can contain dead paths. It goes stale.

Practically, governed instruction files share four properties: they are committed to version control with the same review process as production configuration, they are checked for internal contradictions by a deterministic tool rather than by asking the model to grade itself, they distinguish between instructions the model needs to override default behavior and documentation the model can derive from the codebase, and they are pruned on a schedule rather than only when pain peaks. The WotAI team brought a 1,204-line monorepo CLAUDE.md to 151 lines using a structured pruning pass in August 2026. The reduction was not the point. Knowing what was removed, and why, was.

The math in the arXiv paper does not change. Appending stays cheap. But cheap appends compound into expensive contradictions, and contradictions resolve silently. Static analysis of instruction files belongs in CI alongside every other configuration check.

Hyrax is live at hyrax.dev.