Your AGENTS.md might be a big problem

Matt Pocock (AI Hero) · email · 2026-07-03 Reader 🖥️

Agent Context Files (CLAUDE.md / AGENTS.md)Coding Agents Context Engineering Progressive Disclosure

A reactively bloated AGENTS.md degrades an AI coding agent because it spends the model's finite instruction-following budget on every request, so you should keep the root file to 3-5 essentials and push everything else into nested files the agent loads only when relevant.

practical · argumentative — Practical: it argues for a concrete change in how you author agent config files. Argumentative in form — it states a problem, supplies a causal mechanism (limited instruction budget), and prescribes an action (progressive disclosure). The piece is a short email teaser for a fuller article; the editorial prose carries a complete miniature argument, while the bulleted 'you'll discover' list previews the full article's scope.

Structure

Part	Role
Problem statement	claim
Diagnosis of how bloat forms	context/evidence
Causal mechanism ('instruction budget')	evidence
Prescription (progressive disclosure)	conclusion
Teaser bullet list	context

Key terms

instruction budget Progressive Disclosure
The finite number of directives (~150-200) a frontier LLM can reliably follow before instruction-following degrades; treated as a scarce resource every rule draws down.
progressive disclosure Progressive Disclosure
A config-architecture pattern where the root AGENTS.md stays minimal and detailed rules live in separate nested files the agent pulls in only when a task needs them.

Propositions

explicitdevelopedA bloated AGENTS.md degrades coding-agent performance rather than improving it.conf: high
extends ←Audit your Agent files · p1 — Adds the temporal/model-improvement dimension to why bloat degrades performance: it's not just size, it's that instructions written for an older model/harness state go stale as the underlying system improves.
explicit⚡ disputed & corroboratedAGENTS.md bloat forms reactively and invisibly — developers append a rule after each agent failure until the file sprawls.conf: high
supports ←Audit your Agent files · p2 — Same reactive rule-by-rule accretion mechanism identified independently — a failure prompts one more rule, and the file only ever grows.
contradicts ←Claude Code: Best practices for agentic coding · p18 — This guide actively recommends the #-key habit of appending a rule to CLAUDE.md after issues arise; Pocock identifies exactly this reactive accretion as the mechanism that produces performance-degrading AGENTS.md bloat — a genuine tension between knowledge accretion and instruction-budget discipline.
explicitFrontier LLMs can reliably follow only about 150-200 instructions before performance gets 'fuzzy'.conf: medium
explicitcorroboratedEvery rule in AGENTS.md consumes instruction budget on every request, whether or not it is relevant to that request.conf: high
supportsAgent Skills · p11 — Every AGENTS.md rule consumes instruction budget on every request whether relevant or not, confirming that progressive disclosure is necessary.
supports ←When AI Writes the Code, Specifications Need an Exit Strategy · p9 — Same context-budget mechanism (every rule/instruction costs attention on every request) applied here to specifications and change briefs generally, not only to AGENTS.md rules.
implicitThe root AGENTS.md is loaded wholesale into the model's context on every request, which is why irrelevant rules still cost budget.conf: high
implicitcorroboratedAgents can and will selectively pull in nested files only when a task needs them, so nesting genuinely defers the cost.conf: medium
supports ←Claude Code: Best practices for agentic coding · p17 — The guide documents the exact loading mechanism — child-directory CLAUDE.md files pulled in only on demand — that grounds Pocock's claim that nesting genuinely defers instruction-budget cost.
extends ←Stop Using /init for AGENTS.md · p7 — Pocock's piece shows nested files defer cost by loading selectively; this article generalizes that into a full three-layer architecture (protocol file, task-gated persona/skill files, maintenance subagent) as the structural fix for the static-file problem.
implicitestablishedFewer, well-chosen instructions produce better agent outcomes than a larger, exhaustive rule set — quality of attention beats coverage.conf: medium
supports ←Audit your Agent files · p9 — Both converge on 'fewer, well-chosen instructions beat exhaustive coverage' — here operationalized as moving hard constraints into tests/hooks/permissions rather than prose.
supports ←Claude Code: Best practices for agentic coding · p3 — The guide's warning that adding extensive content without iterating is a common mistake anticipates Pocock's thesis that fewer, well-chosen instructions beat a larger exhaustive rule set.
supports ←The Orchestrator's Tax · p11 — Both argue that a standing instruction file should be judged by whether each line earns a recurring cost, not by exhaustiveness — 'quality of attention beats coverage' matches this piece's 'does this earn a place in the orchestrator's context.'
supports ←Stop Using /init for AGENTS.md · p6 — Both converge on the same editorial principle — fewer, well-chosen, non-discoverable instructions beat exhaustive coverage — from independent evidence (usage-rate data here, instruction-budget limits there).

Arguments

Keep the root AGENTS.md ruthlessly small (3-5 items) and move everything else into nested, on-demand files (progressive disclosure). strength: medium

Explicit premises:

LLMs have a limited instruction budget (~150-200 instructions) beyond which they lose focus.
Every rule in AGENTS.md is spent from that budget on every single request, relevant or not.
Bloated AGENTS.md files therefore hurt performance and waste tokens.

Implicit premises:

The whole root AGENTS.md is injected into context on each request (so there is no per-request filtering of its contents).
Nested files are retrieved only when relevant, so relocating rules there actually frees budget rather than just hiding it.
Instruction-following degradation scales with instruction COUNT, roughly independent of each rule's individual quality.

Inferences:

If instruction budget is the true constraint, then ALL persistent context — system prompt, tool definitions, memory, other config — competes for the same budget, so the optimization should be holistic, not AGENTS.md-only.
The same reactive rule-accumulation dynamic will simply migrate into the nested files unless the underlying authoring discipline changes; progressive disclosure treats a symptom of doc governance, not its cause.

Narratives

A developer who adds one rule every time the coding agent misbehaves, and months later is left with a sprawling AGENTS.md that quietly hurts more than it helps.
→ Cautionary vignette that makes the bloat feel emergent and self-inflicted rather than a design choice — priming the reader to recognize their own file in it.

Questions addressed

✅ Why might my AGENTS.md be making my coding agent worse rather than better?
Because it has grown reactively and every rule spends the model's finite instruction budget on every request, diluting focus.
✅ How should I structure AGENTS.md instead?
Minimal root (3-5 items) plus progressive disclosure into nested on-demand files — though the concrete criteria live in the linked article, not the email.
⭕ How does an agent decide WHICH nested files to pull in, and how reliable is that retrieval?
⭕ By what criteria do you choose the 3-5 things that earn a place in the root file?

Gaps

incompleteThe '150-200 instructions' ceiling is asserted with no citation and no definition of what counts as one 'instruction' (a bullet? a sentence? a constraint?), so it can't be checked or applied precisely.
Read next: Anthropic/OpenAI docs and papers on instruction-following degradation with prompt length; the 'context rot' / lost-in-the-middle literature quantifying how many constraints models reliably honor.
incompleteThe whole solution depends on agents reliably discovering and loading nested AGENTS.md files only when relevant, but the email never explains that retrieval mechanism — if the agent loads all nested files anyway, progressive disclosure saves nothing.
Read next: The AGENTS.md spec and Claude Code / Cursor docs on how nested AGENTS.md / CLAUDE.md files are discovered, scoped, and injected (directory-tree vs. explicit-reference loading).
closed byClaude Code: Best practices for agentic coding — Pocock's progressive-disclosure remedy depends on agents loading nested files only when relevant, but leaves the retrieval mechanism unexplained. This canonical Anthropic guide documents it directly: CLAUDE.md files in parent directories are pulled into context automatically at session start, while files in child directories are pulled in only on demand when Claude works with files in those subtrees — confirming that nested placement genuinely defers cost rather than loading everything.
illogicalThe piece conflates two distinct costs — dollar/token spend and attentional dilution — treating 'burns tokens' and 'loses focus' as the same problem. A short file can still be badly written, and a long file can be cheap but confusing; the levers are related but not identical.
Read next: Work separating context-window cost/latency from instruction-following quality; prompt-engineering guidance on signal-to-noise vs. raw length.
incompleteIgnores that nested files reintroduce the same reactive-accretion risk and add a governance/discoverability burden across a distributed doc set — the same 'messy docs' failure mode at a smaller granularity.
Read next: John Cutler on institutionalized overload and messy docs (TBM 411/412); documentation-governance and information-architecture practices for keeping distributed config coherent.

Closes gaps elsewhere

Jacob Langvad Nilsson's Post · g2 — Provides the missing failure case for the structure-over-prompting thesis: instruction files degrade agent performance once they exceed the ~150-200 instruction budget, showing when more structure hurts.