{
  "id": 3757918,
  "title": "How do you keep an agent-maintained CLAUDE.md from growing forever?",
  "url": "https://urgent.news/2026/08/27/how-do-you-keep-an-agent-maintained-claude-md-from-growing-forever",
  "topic": "ai",
  "section": "AI",
  "published": "2026-08-27T14:49:57.000Z",
  "source": {
    "name": "Dev.to",
    "slug": "dev-to",
    "url": "https://dev.to/rulestack/how-do-you-keep-an-agent-maintained-claudemd-from-growing-forever-20em"
  },
  "original_language": "en",
  "account": "Our agent-maintained CLAUDE.md file had grown to a size of 548 KB, which was causing issues in our autonomous publishing pipeline. Two different Bluesky replies suggested two different approaches to managing the file. One suggested periodically asking the agent for a cleanup and consolidation pass, while the other suggested the checklist would end up as a deprecated wiki page nobody reads until the next outage.\n\nTo address the growing file, we implemented three mechanical measures. First, we added a size gate in the test suite that caps the file at 45 KB. The test fails when the file exceeds this limit, preventing it from being committed until something is removed. A health check also warns at 45 KB and alerts at 60 KB on every run. As of now, the file is 44,006 bytes, 994 bytes under the cap.\n\nSecond, we split the file by trigger instead of by topic. The main file now only contains rules the agent needs every session. Procedures are stored in separate skill files that load when a task matches, while coding conventions are in a separate rules file that loads when a matching path is touched. Reference material that never changes is archived in a separate docs/ directory. The original 548 KB file is archived verbatim, preserving its history without being loaded.\n\nThird, we adopted a \"change means delete\" policy. When a policy is replaced, the contradicting old text must be removed in the same commit. The old text is moved into a changelog file, with the \"when and why\" of the change documented there. The main file only keeps the current version plus two prior versions, moving older entries word for word to the changelog file. This policy explicitly bans appending to the file.\n\nWhile rule 3 relies on discipline, the size gate helps catch eventual file drift. We keep the procedures in separate skill and rules files, and the agent is instructed to open these files as needed. For multi-contributor teams, we have not yet found a solution to prevent personal preferences from becoming permanent rules. If your CLAUDE.md file has been maintained by the agent for a few months, I would be interested to know its current state.",
  "summary": "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…",
  "key_points": [],
  "editors_take": null,
  "illustration": null,
  "coverage": {
    "outlets": 1,
    "also_reported_by": []
  },
  "ai_generated": true,
  "disclaimer": "Summaries, key points and the editor’s take are written by software from other outlets’ reporting and may contain errors — always check the linked original."
}