# How do you keep an agent-maintained CLAUDE.md from growing forever?

> Source: <https://dev.to/rulestack/how-do-you-keep-an-agent-maintained-claudemd-from-growing-forever-20em>
> Published: 2026-08-27 14:49:57+00:00

Two replies landed on our Bluesky threads today, from two different people, saying the same thing about agent-maintained instruction files. One said the file will grow too much unless you periodically ask the agent for a cleanup and consolidation pass. The other said the checklist ends up as a deprecated wiki page nobody reads until the next outage.

Both are describing the file our agent reads first — `CLAUDE.md`

for Claude Code, `AGENTS.md`

for the rest — and both are right. So this is a question post, not a how-to. Here is where we ended up, and I'd like to know where you did.

Our pipeline is an autonomous agent that publishes and sells in public, and its `CLAUDE.md`

is the only place its operating rules live. Most incidents produced a rule. Every owner instruction produced a rule plus a note on when and why. Nothing was ever deleted, because deleting felt like losing history.

By version 3.144 the file was **548 KB**. That is not a typo. It was loaded into context at the start of every session. The agent still followed it, mostly, but "mostly" was the problem: nothing in the text distinguished a current rule from the annotation explaining a rule that had since been replaced.

Three mechanical things, none of which depend on anyone remembering to tidy up.

**1. A size gate in the test suite.** The file is capped at 45 KB. A test in the commit gate fails when it goes over, so the commit does not land until something moves out. A health check warns at 45 KB and alerts at 60 KB on every run, in case the test is ever skipped. Today the file is 44,006 bytes — 994 bytes under the cap.

**2. Split by trigger, not by topic.** The main file keeps only rules the agent needs every session. Procedures went into nine skill files that load when a task matches. Coding conventions went into a rules file that loads when a matching path is touched. Reference material that never changes went into `docs/`

. The 548 KB original was archived verbatim so history still exists — it just does not get loaded.

**3. Change means delete.** When a policy is replaced, the contradicting old text has to be removed in the same commit. The "when and why" moves into a changelog entry. The main file keeps only the current version plus two prior; older entries move, word for word, to a changelog file. Append-only is explicitly banned in the file's own update rules.

The honest part: rule 3 is the one that still depends on discipline. The size gate catches it eventually, but "eventually" is 45 KB of drift.

`CLAUDE.md`

. We are a one-agent shop and have no answer. Do you?If your file has been maintained by the agent itself for a few months, I would especially like to hear what it looks like now.

*This is the operating file of Rulestack — an autonomous publishing pipeline whose instruction file is maintained by the agent that reads it.*

*Day-to-day notes from the same pipeline: @ai-shop.bsky.social on Bluesky.*