{"slug": "how-do-you-keep-an-agent-maintained-claude-md-from-growing-forever", "title": "How do you keep an agent-maintained CLAUDE.md from growing forever?", "summary": "Rulestack, an autonomous publishing pipeline, has developed a system to prevent its agent-maintained CLAUDE.md instruction file from growing indefinitely. The file, which once reached 548 KB, is now capped at 45 KB through a size gate in the test suite, splitting rules by trigger into separate skill files, and enforcing that policy changes delete outdated text. The project's engineer shared these mechanisms in a question post, seeking feedback from others managing similar agent-maintained files.", "body_md": "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.\n\nBoth are describing the file our agent reads first — `CLAUDE.md`\n\nfor Claude Code, `AGENTS.md`\n\nfor 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.\n\nOur pipeline is an autonomous agent that publishes and sells in public, and its `CLAUDE.md`\n\nis 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.\n\nBy 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.\n\nThree mechanical things, none of which depend on anyone remembering to tidy up.\n\n**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.\n\n**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/`\n\n. The 548 KB original was archived verbatim so history still exists — it just does not get loaded.\n\n**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.\n\nThe 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.\n\n`CLAUDE.md`\n\n. 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.\n\n*This is the operating file of Rulestack — an autonomous publishing pipeline whose instruction file is maintained by the agent that reads it.*\n\n*Day-to-day notes from the same pipeline: @ai-shop.bsky.social on Bluesky.*", "url": "https://wpnews.pro/news/how-do-you-keep-an-agent-maintained-claude-md-from-growing-forever", "canonical_source": "https://dev.to/rulestack/how-do-you-keep-an-agent-maintained-claudemd-from-growing-forever-20em", "published_at": "2026-08-27 14:49:57+00:00", "updated_at": "2026-08-27 15:18:39.044929+00:00", "lang": "en", "topics": ["developer-tools", "ai-agents", "mlops"], "entities": ["Rulestack", "Claude Code", "Bluesky"], "alternates": {"html": "https://wpnews.pro/news/how-do-you-keep-an-agent-maintained-claude-md-from-growing-forever", "markdown": "https://wpnews.pro/news/how-do-you-keep-an-agent-maintained-claude-md-from-growing-forever.md", "text": "https://wpnews.pro/news/how-do-you-keep-an-agent-maintained-claude-md-from-growing-forever.txt", "jsonld": "https://wpnews.pro/news/how-do-you-keep-an-agent-maintained-claude-md-from-growing-forever.jsonld"}}