Your CLAUDE.md is code, and it rots like code

This series asks where design intent, the record of why a system is shaped the way it is, can live so an agent honours it. So far: a document that stopped giving one answer, then the pipeline, which made a guard unnecessary. This post is about the file in between: what the agent reads before it touches your code.

I opened a PR titled trim-down-claude-md. No feature, no bug fix: it deleted 190 of 550 lines of instructions. The description said “to help with claude-ing for longer.” I had been reading the usual advice: a leaner file spends fewer tokens and gets better answers. That is when the file stopped being documentation and became a resource I spent.

TL;DR:

• One PR on 2026-02-28 cut the backend repo’s CLAUDE.md from 550 to 360 lines, about 35%, to make sessions last longer.
• Five weeks later a second PR deleted 5 rule files for a claimed 37% cut to what the agent loads. The rules had kept accumulating.
• A rule you never read still costs you, because it dilutes the context around it. An instruction file is the sharp case: it is read every turn, so it has a budget, and that is what makes it code.
• A rule lives in one of three places: always loaded, path-scoped, or compiled into a build check. Only the third one stops coming back.
• The catch: the review that noted the 37% cut also found the pre-commit hook did not enforce one of the five deleted rules.
• The lesson: prove the guardrail works before you delete the prose rule, and put it somewhere that always runs.

A document you pay for

Unread rules dilute the context around them: noise on the way to what matters, and legacy nobody has audited. An AGENTS.md file is the sharpest case. It loads every turn, before the agent reads any of your code, whether the task touches its subject or not. A rule that only matters occasionally still pays rent on every unrelated task.

The same rules written shorter means fewer tokens spent before any work starts, so sessions get cheaper and faster. That is arithmetic, not a finding.

The cost of an instruction file is arithmetic. The benefit is a guess until you instrument it.

Three places a rule can live

Where the rule lives	Cost per turn	Runs when	How it fails quietly
🔴 Always-loaded instruction file	Every turn, relevant or not	Only if the agent reads and complies	Grows back until sessions get short
🟡 Path-scoped rule file	Only on matching edits	Only when a matching file is touched	A wrong glob never loads, and nothing errors
🟢 A check in the build	Near zero	Every build, laptop and CI	Never written, or hides in a hook nobody installed

Trimming does not last. The 35% cut bought room, then had to be repeated: five weeks later a second PR deleted rule files for another 37%. Nobody had done anything wrong in between. Rules pile up because writing one down is the cheapest available response to a mistake.

Path-scoping fails silently. One rule file was scoped to src/main/resources/db/** while the instruction file describing it said db/**. Copilot caught the mismatch in review. A wrong glob does not error, it just never arrives, and you keep believing the agent read it.

Moving a rule into code can be bookkeeping. The second PR deleted five rule files as “now enforced by pre-commit hook.” Copilot pointed out the hook did not appear to enforce the guidance from one of them. Prose gone, check absent.

A note on precision: what I measured, and what I didn't

Every number is self-reported in a PR description or changelog. The source is a catalogue of merged PRs and 5,833 Copilot review comments, February to May 2026. I never measured tokens: line count is a rough proxy for context cost. The 37% is a changelog claim, not an instrumented reading. It shipped in a 16-file PR carrying two unrelated features, so nothing isolates its effect. No evals ran during daily use. Whether a shorter file makes the agent follow the rules better is a separate claim, and nothing here measures it. The tempting story is “we trimmed the file and the agent improved.” I have no evidence for it, so I am not making it.

The takeaway

Treat the instruction file like code, which mostly means stop hand-guarding it. Continuous integration settled this for source long ago. DORA lists continuous testing as a capability precisely because a check a human remembers to run is not a check. On Monday:

• Pick each rule’s home by how often it must be true. Always true goes in the build. True for one directory goes in a path-scoped file. True occasionally is a note, and a note is not a rule.
• Confirm the guardrail works before you delete the prose rule. The build is a good home for it because it always runs, the same way on a laptop and on the pull request. One definition, no opt-in.
• Put a line-count guard on the instruction file itself. “Keep CLAUDE.md short” is a prose rule nobody enforces, which is the whole problem in miniature. Fail the build past a threshold and the budget defends itself.

What would change my mind

The claim is that only the third option holds. Testable on any repo with an instruction file: add the line-count guard, convert your five most-repeated prose rules into build checks, leave it a quarter. If the file still needs a manual trim by then, the budget was never the constraint. The rule-writing habit is, and shrinking the file was treating a symptom. I will run it here and report either way.

A rule in the instruction file is advice you pay for every turn. A rule in the build costs almost nothing and runs anyway. The file gets shorter the moment you stop keeping rules in it.

Next in this series: teaching the agent what it learned yesterday. Memory and retros are the tier between a static rule and an executable one, which is a polite way of saying they rot differently.