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.
