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.
What ours looked like before we did anything
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.
What we do now
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.
What I want to know
- Do you cap the file at all? By bytes, by lines, by token count at load time — or do you let it grow and rely on periodic cleanup prompts, as the first commenter suggests?
- Where do the procedures live once they leave the main file? Skills, slash commands, separate docs the agent is told to open, or something else — and does the agent actually open them when it should?
-
Multi-contributor teams: a reader asked us earlier how you stop personal preferences from becoming permanent rules when several people commit to the same
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.