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.