Why a growing CLAUDE.md stops working

Every team that runs Claude Code long enough grows a CLAUDE.md. It starts as twelve lines. Six months later it is the onboarding doc, the billing policy, the deploy ritual, and the paragraph someone pasted from a Slack argument in March.

You feel it first as noise. The file is in the prompt on every call. A line about refund windows is in the context of a CSS change. A line about CSS is in the context of a refund. There is no off switch for a paragraph that no longer applies to this task, because the file has no idea what this task is.

Chroma tested 18 frontier models and watched accuracy fall as the input grew. They called it context rot. A CLAUDE.md that only ever gets longer is a context-rot machine you maintain by hand. For where to stop, see how long CLAUDE.md should be.

The objection writes itself. If a context file barely helps and costs a fifth more, a context product that pipes more of the same file through a nicer search box should not help either. The study measured a whole file served on every run and did not test serving less, so subtraction is our inference from it, not its finding. We think it is the move that is left.

Harbor picks the few facts that fit this task and leaves the rest out. It does not win by stuffing the prompt. Two facts out of hundreds is the claim the home page draws as two rules served out of a longer list; a growing instruction file is the thing that picture is arguing with.

That is not a smaller bill. In our one test, the token bill came out about even. What changed was how often the agent got it right the first time.

A file also cannot expire a line. The billing policy from March stays in the prompt until a person deletes it, and stale rules are followed with the same confidence as live ones. They are also one reason why Claude ignores CLAUDE.md. Harbor flags a rule when it stops being true. That is a different claim from “we retrieve better.”

What a file cannot do at all is tell you which of those lines the agent used. That is served vs cited.