Agent Builder Foundations

Appending an instruction costs one line. Safely deleting one requires proving it will not reintroduce the failure it was added to prevent. Once that reason is forgotten, the proof means reasoning about how the instruction interacts with every other instruction in the file, a cost that grows exponentially with file size. Nobody pays it, so the file only grows. Writing the rationale as a comment next to each rule is the one intervention shown to reverse this. Surviving rules also rot: agents act on a stale path or command and never fix the file.

Model an instruction file as an append-only log with hidden debt, not a document you tidy now and then. Every rule added without its *why* is a future deletion decision that gets more expensive as the file grows. "Clean sweep" rewrites reset the size but not the asymmetry, so growth resumes on the next commit. The fix has to change the cost of deletion, not the current size.

Append is cheap; verified delete is exponential. Adding instruction |D|+1 is O(1). Removing an old instruction whose purpose is lost means checking whether any subset of the other instructions depends on it, which is O(2^|D|) in the worst case. The rational default becomes "leave it in."

Real repositories show the signature. The catastrophic-remembering study tracked 247,694 instruction lifetimes and found files growing +226% over their lifetime, adding a net +4.9 instructions per commit. The older an instruction is, the less likely anyone removes it.

The bottleneck is the missing rationale, not the count. A comment stating what an instruction guards against turns "why is this here" from a reconstruction-by-testing problem into a fact you can read and re-check. In the paper's controlled test, rationale comments cut excess instructions from +211.3% to +1.4% over the known-optimal set and improved real-world instruction-following by up to 23.1%. The comments change whether the agent follows instructions correctly, not just file size.

Kept rules go stale, and agents obey them. In a 732-trajectory study, agents followed a stale instruction whenever it was relevant to the task, sometimes even with the correct path visible elsewhere. They usually recovered from the immediate failure, so the task still passed, but none repaired the file. A stale test command cost about a third more tool calls on every run.

It generalizes beyond CLAUDE.md. Any accreting instruction surface an agent or team treats as authoritative, such as system prompts, runbooks, or review checklists, has the same asymmetry.

"Safe to delete" means checking instruction A's effect across every combination of the other instructions still present, because instruction B might only matter *because* A exists. A set of size n has 2^n subsets, so the check grows exponentially:

• 10 instructions: 1,024 combinations.
• 30 instructions: over a billion.

Neither a person nor an agent can run that check without a stated reason for each instruction. A rationale comment replaces the exponential search over hidden interactions with a linear read of stated dependencies: for each rule, is the reason it was added still true?

• Write the why next to every new rule in CLAUDE.md, AGENTS.md, or a system prompt: the failure it prevents or the constraint it enforces. Brevity and better organization were not the measured fix; rationale comments were.
• Delete rules whose stated reason is stale first. A documented rationale turns a combinatorial guess into one fact-check.
• Track net instructions added per commit on any file agents read as instructions. Steady upward drift with no deletions is the growth signature.
• Treat old, undocumented rules as your highest-risk debt. Deletion likelihood falls with age, so the longer an unexplained rule survives, the less likely it is ever reconsidered.
• Check instruction files against the code in CI. Assert that every path and command the file names still exists or runs; a stale rule costs every later session.
• Delete a stale rule you cannot fix right away. Removal prevented most obsolete-path operations; only correction prevented all.

• Deleting an old, undocumented rule on a hunch, triggering the regression it silently prevented and making the team afraid to delete anything again.
• Fixing for shorter instructions instead of documented reasons.
• Judging an instruction file by task success, which hides the extra tool calls a stale rule adds.
• Expecting the agent to repair a stale rule it tripped over; none did.
• Citing the 99.3% bloat reduction or 23.1% gain as replicated results rather than one preprint's figures.
• Confusing this with session context bloat: this is a persistent file growing across commits, not a conversation growing turn by turn.

See agent memory for how agents retain and lose information, and context compaction for shrinking context without losing what matters. agent-context-lifecycle covers the sibling problem of a single session's context cost growing quadratically.