Overhauling Bloated AGENTS.md: 3-Stage Subagent Prompt for Token Optimization
Matt Pocock shares a prompt to cut AGENTS.md token bloat by removing no-ops, using progressive disclosure, and splitting coding standards across three subagents
On October 6, 2026, TypeScript educator and developer Matt Pocock (@mattpocockuk) shared a prompt technique designed to resolve token bloat and inefficiency in project AGENTS.md instruction files. Framed as a "Prompt of the day," the pattern orchestrates three subagents of increasing radicalism to trim unnecessary instructions, enforce progressive disclosure, and deliver a cleaner architecture in a single pull request.
As AI coding assistants—including Claude Code, Cursor, Windsurf, and Codex—become standard fixtures in software engineering workflows, having an AGENTS.md or CLAUDE.md in the repository root has become common practice for guiding agent behavior. Over time, however, these instruction files frequently accumulate rambling style guidelines, historical edge-case fixes, and obvious restatements of compiler rules. Rather than enhancing the agent's capabilities, an uncontrolled instruction document turns into a major token bottleneck.
1. Token Inefficiency and Context Bloat in Monolithic AGENTS.md Files
In his post, Matt Pocock identified the core issue bluntly: "AGENTS.md is the most common source of token inefficiency. This prompt kills it dead."
Whenever an agent harness initializes a session or processes an instruction turn, it injects the root AGENTS.md into the active context window. When this file inflates to hundreds of lines of unstructured directives, several distinct failure modes emerge:
- Context Window Depletion and Compounding Costs: Loading thousands of static tokens on every turn rapidly consumes context budgets and escalates API usage costs, even for simple single-file edits or quick exploratory questions.
- Attention Degradation: In a monolithic file crammed with dozens of disparate imperatives, models struggle to allocate attention properly. Relevant constraints for the immediate task get lost among unrelated background rules, increasing hallucination rates and missed directives.
- Accumulation of Redundant No-Ops: Platitudes that LLMs already follow by default, or mechanical rules already enforced by linters and compilers, get repeatedly appended, diluting the file's information density.
2. Matt Pocock's Verbatim AGENTS.md Refactoring Prompt
Below is the complete prompt shared by Matt Pocock, structured to be executed under a /writing-for-agents command or agent skill trigger:
Prompt of the day:
/writing-for-agents my AGENTS.md is a hot mess, propose a series of restructurings that:
- Remove no-ops
- Use progressive disclosure
- Move instructions to CODING_STANDARDS.md
Apply your work over three subagents, each more radical than the last. Create a single PR.
AGENTS.md is the most common source of token inefficiency. This prompt kills it dead.
Rather than requesting generic prose cleanup, the prompt prescribes three concrete structural principles and distributes the audit across three progressive subagents before consolidating the final changes into a single pull request.
3. The Three Core Restructuring Directives
The prompt defines three architectural principles that align with modern best practices for agent configuration:
- Remove No-Ops: Vague advice such as "write clean, readable code," "do not introduce bugs," or "name variables descriptively" provides zero actionable signal to an advanced reasoning model while continuously consuming token space. Similarly, rules already enforced mechanically by formatters, ESLint, or the TypeScript compiler are treated as no-ops and purged from text instructions.
- Use Progressive Disclosure: Rather than maintaining an encyclopedic megadoc in the repository root, the root
AGENTS.mdis converted into a concise table of contents and router. Domain-specific knowledge, deployment checklists, and specialized procedures are migrated into dedicated markdown documents or on-demand skills that the agent inspects only when a specific task requires them. - Move Instructions to CODING_STANDARDS.md: Project operational conventions (e.g., how to run tests, use custom CLI commands, or manage branches) are isolated from stylistic coding preferences. Extracting syntax conventions and patterns into
CODING_STANDARDS.mdensures that baseline tool execution remains lightweight without dragging entire style manuals into non-coding workflows.
4. Multi-Agent Staging and Single-PR Delivery
The defining operational insight of Pocock's prompt lies in distributing the refactoring work across three subagents with escalating degrees of intervention:
- Progressive Radicalism (Each More Radical Than the Last): Rather than pre-scripting rigid sub-tasks, the prompt directs the agent to escalate the degree of intervention across iterations, pushing the model beyond superficial cleanup into deeper architectural restructuring:
- Initial stage: conservative housekeeping, eliminating obvious redundancies and dead no-ops.
- Intermediate stage: structural modularization, separating coding standards and tightening verbose prose.
- Final stage: aggressive optimization, stripping the root document down to a lean router and establishing a strict progressive disclosure hierarchy.
- Consolidation into a Single Pull Request: Instead of scattering uncoordinated edits across divergent branches, the three-stage process culminates in a single unified pull request. This allows human developers to review the cumulative git diff with complete clarity and merge the optimized agent configuration safely.
A bloated instruction file works against an agent rather than assisting it. Matt Pocock's multi-stage refactoring prompt provides a pragmatic and repeatable pattern for development teams seeking to trim token overhead and improve instruction compliance across AI-assisted codebases.