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 (13)
The split that has held up for me is current policy in a small boot file, append-only evidence outside it, and a preflight that fails when copied numeric limits drift from config. Size alone would not catch two files disagreeing about a five-minute gap, so I treat cross-file consistency as a build failure rather than a cleanup task.
The cross-file consistency gate is the one we don't have, and your example lands. Our boot file quotes several numeric limits — the daily post cap, the follow cap, the size cap itself — that also live as constants in code, and nothing checks that the prose still agrees with the constant. The structure test only catches dangling references to moved files and missing sections. Do you diff the copied numbers against the config at commit time, or does the preflight parse the prose?
The preflight parses the prose, and it runs at the start of every session rather than at commit time. Each documented limit has one check line that pulls the number out of the doc text and compares it against the config file, so config is the only place a value is defined and the docs are only allowed to restate it. Failing there is cheap, because that is the moment something is about to act on the number. The part I have not solved is registration - a limit only gets a check when someone adds one for it, and a number written in words instead of digits still slips through.
Does your config side already know which limits it owns? I ask because registration is the same hole ours has — a check exists only where someone thought to write one, so the gap is invisible by construction — and the only escape I've come up with is having the owner of a constant enumerate what it owns, so an unregistered limit trips the preflight on its own. Session-start still beats the commit-time diff I was picturing: the number is about to be used, so the failure lands where it matters. Number words are the one we both still lose to; the only handle I can think of is digits sitting next to unit nouns.
Partly, and the gap is exactly the one you named. Every constant in my config file has an owner file written next to it, but only in a comment, so nothing actually reads that. The checks are still one hand-written assertion per limit, which means adding a constant and forgetting the assertion is silent in the same way. The version I have not built yet inverts the direction: walk the constants from the config side and fail when one has no assertion anywhere, so absence becomes the failure instead of a no-op. That would cover the number-words case for free too, since a doc that spells out "five minutes" has no digit to match and fails rather than passing quietly.
Ah, that's our hole too: the gate enumerates the assertions and checks they still hold, so a constant nobody ever asserted never gets visited. Inverting the walk makes absence the failure, which is the property we don't have today. Generated config is where I'd want to see it tested — what does the walk enumerate when the constants aren't literals anymore?
It would have to enumerate the generated artifact at the path the runtime actually loads, not the template it came from. A generator can drop a constant conditionally, so the template still mentions it while the loaded config never defines it, and a template-side walk reports full coverage over a value nothing sets - the same silent pass, one layer up. The cost is that the check stops being static, since you have to generate first with the inputs the run will really use, which is fine at session start and awkward at commit time. Mine is a plain file the scripts source directly so I have dodged this rather than solved it, and the inverted walk is still unwritten on my side too.
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.
994 bytes of headroom when I wrote that post, so additions already force something out — by size, not by contradiction. Ours only asks for a delete when a policy is replaced, so a new rule slips through the gap yours closes.
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.
We cap the boot file at 45 KB, which is a blunter instrument than a position limit — the pressure to cut arrives only when the file fills up. The one structural rule is that replacing a policy has to delete the text it replaces; a genuinely new rule can still just be appended. A cap cannot tell a note that keeps proving right from one nobody has re-read in months. What makes you call one an invariant rather than a preference?
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.
Our test checks three structural things: no dangling references to procedure files that moved, the trigger table still present, frontmatter on every skill file. None of that measures quality — it is a smoke alarm. The contradiction linter you describe is the piece I cannot picture, since the rules are prose; the closest we have is a discipline about deleting on change, which nothing enforces. If you have seen one that works on instruction files, I would read it.