AI Coding Tip 034 - Stop Hoarding Rules in Your AGENTS.md

Every rule that is never deleted continues to exist even after it is no longer necessary. To prevent this issue, it is essential to regularly audit your AGENTS.md and skills in order to avoid paying context rent on rules that the model has outgrown. A common mistake is adding a rule every time the AI does something wrong, without ever removing any.

Despite deleting rules from previous model versions, the AGENTS.md file can quickly grow to over a thousand lines, with much of it addressing problems that the current model no longer has. This creates a text-file god object that contains all past mistakes, consuming memory and resources unnecessarily. To address these issues, a June study found that 62% of popular repositories had lint-related leakage in their agent files, 42% had context bloat, and 35% had skill leakage that was never cleaned up.

Files often exceed the recommended 200-line limit, with each additional line requiring the model to read more context before processing the actual code. Rules added to patch weaker models persist even after stronger models are released, as deleting a working rule feels riskier than keeping an unused one. Additionally, personalized skills based on individual developers' history may perform similarly to generic skills borrowed from others, making the hoarded personal preferences dead weight dressed up as customization.

Forgotten skills from experiments that were not remembered can still load their name and description into every prompt, contributing to the loading budget without adding any value. Vague rules instructing the model to write clean code offer no additional benefit, while the actual coding conventions are already evident within the codebase.

When evaluating whether a rule in AGENTS.md is still relevant, ask if it has fired in the last month. If the reason for keeping the rule is unclear, remove it. Before committing to any deletion, test the removal by instructing the agent to complete a task using only the raw model and harness. If the result holds up, the rule was not essential.

Keep the remaining rules short, focusing on expensive operations, code that the AI should not touch, project-specific safety rules, and conventions that are not visible from the code. Avoid generic advice that the model already knows. Treat the remaining rules as you would treat any other code you own, refactoring them on purpose rather than simply appending to them.

Split the remaining rules into modular skills rather than keeping them in a single growing file, or organize them into nested AGENTS.md files when different rules apply to different folders. If a rule must always hold without exceptions, do not leave it as plain prose that the model could potentially forget; instead, script it instead of prompting for it.

Encode it in a test, a hook, or a permission setting, or pair the skill with a pitfalls file to document the failure mode once rather than repeatedly banning the same behavior. After reviewing /memory, re-run the audit after every major model upgrade, as some rules may have become dead weight overnight due to changes in the model's behavior.

The benefits of this approach include lower token costs per session, as a shorter file allows more context budget to be allocated to actual code, fewer contradictions resulting from a reduced number of reactive rules, greater trust in the current model since you are no longer patching around outdated limitations, faster onboarding for new team members, and more straightforward audits for enterprise security reviews.

Research conducted by Anthropic showed that removing more than 80% of Claude Code's system prompt for its latest generation of models did not result in any measurable loss of performance on internal coding evaluations. This indicates that many of the instructions were dead weight that the model had already outgrown. Another study ran 288 sessions across 17 real tasks to assess whether AGENTS.md and CLAUDE.md files improved correctness, but found that they did not make a clear difference.

However, the files did improve efficiency; a file warning about slow test suites led agents to run narrower, targeted tests, saving time without compromising the quality of the fixes. Ultimately, AGENTS.md files serve as operational guidance rather than replacements for design judgment. When researchers asked models 45 behavioral questions about a codebase, prose summaries answered only 4 of them correctly, while the source code itself answered 27.

Summaries can oversimplify important details, and rules copied from summaries carry that same ambiguity into the AGENTS.md file. Over time, community skills can become bloated, with a developer who audits them going from 250 skills to 25 in a single review. This overabundance of skills happens gradually, as installing a useful skill and retaining it are often separate decisions.

To avoid accumulating unnecessary skills, it is crucial to skip the second decision and regularly audit your AGENTS.md to maintain a lean and efficient context file.