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.
Top comments (3)
I ended up treating the main instruction file like boot code. It gets only rules needed on every run. Everything else has to move into task-loaded files, and the cleanup gate is boring on purpose. If a new rule does not delete or replace an old one, I assume I am just adding another future contradiction.
Treat it like a position limit. The file should hold stable invariants and sharp exceptions, while the day-to-day preferences move into dated notes or small task files. Once everything is in the constitution, the agent starts overfitting to old trades.
This is a problem I’ve seen repeatedly with agent-driven codebases: the instruction file slowly becomes a second codebase, except without the compiler, tests, or clear ownership.
I strongly agree with your “change means delete” principle. An instruction file should represent current executable policy, not institutional memory. Once obsolete rules remain alongside newer ones, you create ambiguity for both the agent and the humans maintaining it.
The 45 KB gate is also a good idea, but I’d go one step further: measure instruction quality, not just size. A smaller file can still contain contradictory, duplicated, or low-value rules. We’ve found a useful structure is:
CLAUDE.md / AGENTS.md → always-required constraints
Task-specific skills → procedures and workflows
Path-scoped rules → repository/component conventions
docs/ → reference and architectural context
Changelog → historical decisions and rationale
The important distinction is retrieval versus inheritance. If every session inherits every rule, context inevitably becomes expensive and noisy. If the agent retrieves instructions based on the task and touched files, the main instruction file can remain intentionally small.
For multi-contributor teams, I’d also recommend treating agent instructions like production code: PR review, ownership, tests, and explicit provenance. A personal preference should never become a permanent rule simply because someone appended it to CLAUDE.md.
One additional safeguard I’d consider is a CI check for contradictory instructions and duplicate rules, not just file size. That could catch the dangerous situation where the file is only 20 KB but contains two rules telling the agent to behave differently.
The bigger question for me is: should agent instruction files eventually be treated less like documentation and more like executable configuration—with schemas, validation, ownership, and automated linting?
That seems like the natural next step as autonomous agents become responsible for increasingly large codebases.