An Agent becomes less effective, usually because it has too much to read, too much of it is outdated, and the material is too disorganized. This pass is about subtraction only: consolidate, delete, and enforce limits—no new features.
Before making changes in each step, show the user a list of the proposed changes and wait for approval before proceeding. Deleted content is still available in Git, so confirm that nothing references it before removing it.
1. Keep Each Rule in One Place Only
Find every place where business rules—such as whether someone counts as late, how prices are calculated, and who can view what—are written. If the same rule appears in more than one place, consolidate it into one location and point the other locations to it. Code may look similar but govern different concerns, so keep those separate.
Definition of done: every business rule has exactly one source, and the tests still pass.
2. Remove the Clutter
- Dead code: files, functions, and exports that nothing references. Search to confirm this, then delete them.
- Comments: delete comments that merely restate the code; keep those that explain “why”; if a comment no longer matches the code, update it to match.
- Outdated documentation: drafts, plans, and older documentation for work that has been completed or made obsolete.
3. Install a File-Size Hook
Use a Git pre-commit hook: reject the commit if a file being committed exceeds 5,000 tokens (bytes ÷ 4, roughly 20 KB). The error should state the file's size and instruct the user to split it into several files based on functionality. Skip files the Agent will not read, such as lockfiles, generated code, and build artifacts. If the project already uses a tool such as husky, lefthook, or pre-commit, add the check to that existing setup.
After installation, test it with an oversized file: the commit must be blocked, and after the file is split, the commit must pass. List files that are already over the limit for the user; do not split them as part of this step.
Then add two lines to AGENTS.md: If a commit is rejected by the hook, split the file as directed by the error and try again; before writing a new function or rule, search the project for an existing one.
4. Slim Down AGENTS.md and Tooling
- Reduce AGENTS.md to around 100 lines: Keep what the project does, project-specific gotchas, and pointers to . Delete information that can be learned at a glance from the directory listing, , or ; move lengthy details into and leave a one-line pointer in AGENTS.md.
- Tooling: List globally installed MCP servers, skills, and plugins that this project does not need, and recommend enabling them only in projects that need them. Leave global configuration changes for the user to make.
- Recurring mistakes: If the Agent makes the same mistake at least twice, add a lint rule or test to prevent it instead of adding a reminder to AGENTS.md.
- Memory plugin: Recommend turning it off while writing code; the latest code and Git history are the memory.
5. Report the Results
Rules consolidated: <rule> → <path> (previously N locations)
Deleted: N files, N lines
Hook: <installed in>; oversized file blocked; passes after splitting
AGENTS.md: N lines → N lines
Tools recommended for disabling: …; "None" if there are none
Files still over the limit and unsplit: …; "None" if there are none
Finally, tell the user to adopt three habits from now on: delegate code reading and research to a sub-agent and bring back only the conclusions; use /compact when the conversation gets long; clear the conversation when switching tasks and start a new one.