Every rule you never delete outlives the reason you added it.
TL;DR: Audit your AGENTS.md and skills on a schedule, or you keep paying context rent on rules the model has outgrown.
Common Mistake ❌
Every time the AI does something wrong, you add a rule to stop it.
You never remove one.
Not even the one from two model versions ago that stopped mattering the week you wrote it.
Six months later your AGENTS.md is a thousand lines long, half of it fixing problems last year's model doesn't have anymore.
You are still loading all of it, every session, forever, a text-file god object that knows about every mistake anyone ever made.
You treat the file like a rulebook that only grows, when the whole point of running /init in the first place was to give the AI a curated second brain, not an archive.
Problems Addressed 😔
- A June study found 62% of popular repositories had lint-related leakage in their agent files, 42% had context bloat, and 35% had skill leakage nobody had cleaned up.
- Files creep past the recommended 200-line target, and every extra line is a line the model reads before it reads your actual code.
- Rules you added to patch a weaker model persist after a stronger one ships, because deleting a rule that seems to work feels riskier than keeping a useless one, and nobody ever got promoted for deleting eight lines nobody reads.
- Personalized skills built from one developer's history perform about as well as a generic skill borrowed from someone else, so a hoarded personal preference is often dead weight dressed up as customization.
- Forgotten skills, from experiments you don't remember running, still load their name and description into every prompt's listing budget, quietly billing you rent for an idea you abandoned months ago.
- A vague, generic rule telling the model to write clean code teaches it nothing it doesn't already know, while the real conventions of your codebase only live in the code itself.
How to Do It 🛠️
Run /doctor on a schedule, every few weeks or once a month, and read what it flags: unused skills, dead MCP servers, stale plugins, slow hooks.
For each rule in AGENTS.md, ask if it fired in the last month, and if you can't remember the last time it mattered, cut it.
Test the deletion before you commit to it: ask the agent to complete a task while ignoring your local skills and instructions, using only the raw model and harness, and if the result holds up, the rule wasn't pulling weight.
Keep what survives short: expensive operations, code the AI shouldn't touch, project-specific safety rules, and conventions that aren't visible from the code, and skip generic advice the model already knows.
Treat what's left the same way you treat any other code you own: something you refactor on purpose, not just append to, since a rule nobody tidies up rots the same way an unrefactored function does.
Split what's left into modular skills instead of one growing file, so each one loads only when it's relevant, or into nested AGENTS.md files when different rules apply to different folders.
If a rule must always hold, no exceptions, don't leave it as prose the model can forget, 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 so the failure mode itself gets documented once, not repeated as a growing list of bans, though a pile of bad examples still doesn't replace telling the model why the rule exists.
Review /memory on its own pass, since auto-saved memory outlives a cleaned-up project file, and a stale preference can survive the audit you just did.
Re-run the audit after every major model upgrade, and assume some of your rules just became dead weight overnight, because the behavior they were patching may not exist anymore.
Benefits 🎯
Lower token cost per session: A shorter file means more of your context budget goes to your actual code, not to instructions.
Fewer contradictions: A pile of reactive rules accumulates conflicts nobody notices; a pruned file doesn't.
Trust in the current model: You stop patching around old limitations the model shipped six versions ago.
Faster onboarding: A new teammate, human or AI, reads a briefing in a minute instead of an archive in twenty.
Cleaner audits: Enterprise security reviews increasingly check agent configuration; a small file is easier to defend than a thousand-line one nobody can explain.
Context 🧠
Anthropic removed more than 80% of Claude Code's system prompt for its newest generation of models, with no measurable loss on internal coding evaluations.
That's not a rounding error.
That's most of the instructions turning out to be dead weight the model had already outgrown, and nobody threw a goodbye party for any of them.
A separate study ran 288 sessions across 17 real tasks to see whether AGENTS.md and CLAUDE.md files actually improved correctness.
They didn't make a clear difference.
What they did change was efficiency instead.
A file warning that the test suite was slow led the agent to run narrower, targeted tests, saving time without touching the quality of the fix.
That's the real job of a context file to serve as operational guidance, not design judgment replacement.
When researchers asked models 45 behavioral questions about a codebase, prose summaries answered 4 of them correctly.
The source code itself answered 27.
Summaries smooth over the small details that matter, and a rule copied from a summary carries that same blur into your AGENTS.md.
Community skills compound the same way: try a few out of curiosity, and one developer who finally sat down to audit them went from 250 skills to 25.
Nobody plans to end up with 250 skills.
It happens one reasonable-sounding install at a time, because installing a useful skill and keeping it forever are separate decisions.
Skipping that second decision is how the number gets that high before anyone notices.
How Do You Know a Rule Still Earns Its Place?
You don't, until you test it.
A rule that fixed a real, recurring failure earns a permanent home.
A rule you wrote once, after a single bad session, and never saw fire again, is a guess wearing the costume of a policy.
Personalization research backs this up: a skill built from one developer's own history performed about as well as a generic one borrowed from a stranger, except when the same preference kept recurring across similar tasks.
One-off corrections don't deserve a permanent line.
Recurring ones do.
Team-wide and organizational rules are the exception: they compound, because they encode culture, compliance, and internal tooling quirks that don't change every time a model does.
The bar isn't whether you felt strongly about it once.
It's whether it kept happening.
Prompt Reference 📝
Bad Prompt 🚫
The AI keeps adding a trailing comma the wrong way.
Add a permanent rule to AGENTS.md telling it never to do that again.
Don't ever remove anything from this file.
It doesn't matter how old the rule gets or how the model changes.
Here is the current skill list, for context.
247 skills loaded, six more pending review.
Skill `tabs-not-spaces`: MANDATORY REQUIRED CRITICAL.
Never use spaces.
No exceptions, ever.
Skill `always-plural-vars`: MANDATORY REQUIRED.
Variable names must always be plural.
Skill `hate-semicolons`: CRITICAL MANDATORY REQUIRED.
Semicolons are forbidden.
Don't use them, period.
Skill `love-semicolons`: MANDATORY CRITICAL REQUIRED.
Semicolons are mandatory.
Always use them, no exceptions.
Skill `defect-2023-react-hook-fix`: REQUIRED MANDATORY.
This patches a defect the framework fixed two years ago.
Skill `my-friends-color-palette`: CRITICAL REQUIRED.
Use these exact colors.
He'll notice if you don't.
Add one more skill on top of these instead of fixing any of them.
Good prompt 👉
Before you add a new rule to AGENTS.md
Check for an existing one first.
See whether it already covers this case.
If this is the first time it happened, fix it in this session only.
Don't touch the file yet.
If it's the second time, add one short line.
Set a reminder to test whether it's still needed next month.
Considerations ⚠️
Pruning isn't the same as deleting blind.
Test the removal before you trust it, and keep a copy of what you cut in git history, not just in your memory that it was probably fine.
This tip pulls in the opposite direction from a pitfalls file, which grows on purpose every time you document a new failure mode.
Neither instinct is wrong by itself: pruning and accumulating are both correct in their own place, so the real work is finding the tradeoff between the two instead of applying either one everywhere.
Nobody's throwing you a parade for a smaller AGENTS.md, but the model reading it every session will thank you in tokens.
Type 📝
[X] Semi-Automatic
Limitations ⚠️
This tip reduces bloat you already have.
It doesn't stop you from writing the next reactive rule the same way you wrote the last one, because old habits don't read audit logs.
Audit cadence only works if you actually run it; a /doctor command nobody invokes is just another unread file.
Some rules genuinely need to stay prose, because no test or hook can express a warning as specific as a client's legacy system needing this one weird thing.
/doctor is a Claude Code command, not a feature every AI assistant ships.
This audit step doesn't transfer to every tool the same way.
Level 🔋
[X] Intermediate
https://coderlegion.com/9307/ai-coding-tip-001-commit-before-prompt
https://coderlegion.com/10515/ai-coding-tip-004-use-modular-skills
https://coderlegion.com/11538/ai-coding-tip-006-review-every-line-before-commit
https://coderlegion.com/13655/ai-coding-tip-009-compact-your-context
https://coderlegion.com/13150/ai-coding-tip-011-initialize-agents-md
https://coderlegion.com/13394/ai-coding-tip-012-understand-all-your-code
https://coderlegion.com/13837/ai-coding-tip-013-use-progressive-disclosure
https://coderlegion.com/14016/ai-coding-tip-014-use-nested-agents-md-files
https://coderlegion.com/14690/ai-coding-tip-015-force-the-ai-to-obey-you
https://coderlegion.com/14905/ai-coding-tip-016-feed-your-pr-lessons-into-the-ai-brain
https://coderlegion.com/17320/ai-coding-tip-019-tell-the-ai-why-not-just-what
https://coderlegion.com/18160/ai-coding-tip-020-create-a-second-brain
https://coderlegion.com/19374/ai-coding-tip-022-give-ai-a-harness-to-work-with
https://coderlegion.com/20462/ai-coding-tip-024-force-a-criteria-check-before-the-task-ends
https://maximilianocontieri.com/ai-coding-tip-025-pair-every-skill-with-a-pitfalls-file
https://coderlegion.com/22224/ai-coding-tip-027-force-code-standards
https://coderlegion.com/23029/ai-coding-tip-028-build-a-company-brain
https://coderlegion.com/24053/ai-coding-tip-030-script-your-skills-not-your-prompts
https://coderlegion.com/24306/ai-coding-tip-031-stop-over-prompting-reasoning-models
Conclusion 🏁
Adding a rule is free.
Carrying it forever isn't.
Audit your AGENTS.md and your skills on a schedule, test what you're about to cut, and encode the rules that must never break as tests and hooks instead of prose.
The model you're patching around today won't be the model reading the patch next month.
https://addyo.substack.com/p/audit-your-agent-files
https://claude.com/blog/the-new-rules-of-context-engineering-for-claude-5-generation-models
https://docs.anthropic.com/en/docs/claude-code/overview
https://agents.md/
https://docs.anthropic.com/en/docs/claude-code/skills
https://docs.anthropic.com/en/docs/claude-code/memory
Also Known As 🎭
- Agent-Config-Pruning
- Context-File-Debt
- Skill-Hoarding
The /doctor command inside a Claude Code session, not the claude doctor shell command, which only prints installation diagnostics and won't judge you for the fifty skills you forgot you installed.
Disclaimer 📢
The views expressed here are my own.
I am a human who writes as best as possible for other humans.
I use AI proofreading tools to improve some texts.
Most AI detectors will flag this article as AI-generated. That's expected. It's a technical article. It has a rigid format and clear steps to follow.
That's exactly the pattern those tools are trained to catch. I've apparently been "writing like an AI" for decades, long before AI existed. This is a technical article, not a novel.
I welcome constructive criticism and dialogue.
I shape these insights through 30 years in the software industry, 25 years of teaching, and writing over 500 articles and a book.
This article is part of the AI Coding Tip series.
https://coderlegion.com/12469/ai-coding-tips
