Stop Using /init for AGENTS.md

Addy Osmani · article · 2026-02-23 source ↗ Reader 🖥️

practical · argumentative — Builds an evidence-based case against a widespread practice (/init-generated AGENTS.md) and argues for a specific alternative practice (treat AGENTS.md as a diagnostic, friction-tracking artifact; move toward a layered, selectively-loaded context architecture).

Structure

Key terms

• pink elephant problem
  The anchoring effect of merely mentioning something in a context file: once stated, it occupies every subsequent prompt's context and biases the agent toward it, because the model cannot distinguish 'this is what we used to do' from 'this is what you should do.'
• discoverability filter
  The practical test for whether a line belongs in AGENTS.md: can the agent find this itself by reading the code? If yes, it's noise and should be deleted.
• protocol file (Layer 1)
  What AGENTS.md should actually be: not a codebase overview or style guide, but a routing document — available personas/skills and when to invoke them, available MCP connections, and only the minimum facts the agent genuinely cannot discover.
• AGENTS.md as living list of friction
  A diagnostic artifact: every line added is a signal that something in the codebase is confusing enough to trip an agent (and likely a new human), to be investigated and fixed in the code itself, after which the line should be deletable.

Propositions

• explicitA paired experiment on 124 real GitHub PRs (Lulla et al., ICSE JAWs 2026) found that the presence of an AGENTS.md file reduced median wall-clock runtime by 28.64% and output token consumption by 16.58%, holding task, repo, and agent constant.conf: high
  supportsAudit your Agent files · p4 — Both find context files don't cleanly improve correctness at scale (audit-your-agent-files: 288 runs, no clear gain; here: efficiency gain measured but correctness untested) — convergent caution against assuming AGENTS.md helps output quality.
• explicitA separate ETH Zurich study found that LLM-generated (auto-generated) context files reduced task success by 2-3% while increasing cost by over 20%, whereas developer-written files improved success by about 4% while increasing cost by up to 19%.conf: high
• explicitAuto-generated context content is not inert but actively redundant: when the ETH Zurich team stripped all existing documentation from repos before testing, the same LLM-generated files then improved performance by 2.7%, showing the content itself has value but duplicates what the agent could already find in the repo.conf: high
  supportsThe Anatomy of an Agent Harness · p5 — Both cite the same context-degradation research lineage (Lost in the Middle / Levy et al.) to argue that adding content, even accurate content, has a real attention cost distinct from whether the content is 'wrong.'
• explicitMerely stating a fact in AGENTS.md (e.g. a legacy tech-stack detail) biases the agent toward that pattern on every future prompt, because the model does not distinguish 'this is what we used to do' from 'this is what you should do' — an anchoring cost independent of the fact's accuracy.conf: high
• explicitThe ETH Zurich paper found that /init-style auto-generation is overwhelmingly codebase-overview content: 100% of Sonnet 4.5's and 99% of GPT-5.2's auto-generated context files contained codebase overviews — exactly the content an agent discovers anyway by listing directories and reading READMEs.conf: high
• explicitThe right inclusion test for an AGENTS.md line is whether it is non-discoverable from the codebase, operationally significant, and impossible to guess by convention (e.g. 'use uv, not pip' — which raised per-task tool usage from under 0.01 to 1.6 when stated) — not whether it is true or helpful to a human reader.conf: high
  supportsYour AGENTS.md might be a big problem · p7 — 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).
• explicitA flat, static context file cannot condition on task type, so instructions irrelevant to the current task (e.g. 'always run the full test suite' during a documentation-only change) are still applied, wasting tokens and time — a structural limitation that no amount of content pruning fixes.conf: high
  extendsYour AGENTS.md might be a big problem · p6 — 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.
• explicitThe correct architecture is layered and selectively loaded: a thin routing/protocol file (minimum undiscoverable facts, available personas/skills/MCP connections), focused persona or skill files loaded only for the relevant task type, and a maintenance subagent whose sole job is keeping the protocol file accurate as the codebase evolves.conf: high
• explicitNo major coding agent currently exposes the lifecycle hooks needed to build the three-layer architecture cleanly; it can only be approximated today with sub-agents and scoped context.conf: high
  extendsThe Intent Debt · p18 — Osmani's own later piece reframes AGENTS.md specifically as an 'intent ledger' of non-discoverable why; this article's 'Layer 1 protocol file... minimum essential facts the agent genuinely cannot discover' is the same move stated architecturally rather than philosophically.
• explicitAutomated prompt-optimization of CLAUDE.md instructions (Arize AI's generator/evaluate/feedback/meta-prompt loop) outperformed manually written instructions by +5.19% accuracy cross-repo and +10.87% in-repo, because what a human finds obviously useful and what actually helps the model navigate a codebase are often different things.conf: high
• explicitAGENTS.md should function as a diagnostic log of unfixed codebase friction: an agent's repeated mistake should first be investigated as a codebase problem (confusing directory structure, an easy-to-grab deprecated dependency, a missing automated check) and fixed in the code or build pipeline; only if that's not possible should the fix remain as a prose instruction, which should then be deletable once the underlying problem is addressed.conf: high
  supportsAudit your Agent files · p9 — Both argue that an always-true rule belongs in a test/hook/build-pipeline check rather than as prose competing for instruction budget — convergent on 'encode it, don't just write it down.'
• explicitInstructions essential to a context file today lose value over a few months as underlying models improve at codebase navigation on their own, so a well-tuned AGENTS.md can become net overhead by the next quarter purely from model improvement, independent of codebase or content changes.conf: medium
• implicitThe widespread practice of onboarding a coding agent like a new human hire (office tour, org chart, architecture walkthrough) misapplies a model of discovery cost that doesn't hold for agents, which can grep an entire codebase before a human finishes typing a prompt.conf: medium
• implicit'Can the agent discover this' is treated as a binary possible/impossible test, but discovery is not free — it costs tool calls, reasoning tokens, and time even when something is technically findable, so the real inclusion criterion is a discovery-cost threshold the article never makes explicit or quantifies.conf: medium

Arguments

Narratives

• A Cloudflare engineer's critique that the ETH Zurich study's one-time /init files don't represent thoughtfully maintained context files, which the author concedes is fair — but reframes as evidence the failure mode is comprehensiveness, not staleness.
  → Pre-empts the obvious rebuttal ('the study just caught a sloppy best case') and uses it to sharpen the real diagnosis: auto-generation optimizes for coverage, and coverage itself is the problem.

Questions addressed

• ✅ Does AGENTS.md help or hurt coding-agent performance?
  Both, depending entirely on content: auto-generated/redundant content hurts (cost up, success down); human-written, non-discoverable content helps (cost up some, success up, runtime/tokens down in the efficiency-only study).
• ⭕ Does AGENTS.md improve the correctness of agent output, not just its speed/cost?
  The efficiency-focused Lulla paper explicitly does not measure correctness; a full correctness evaluation is named as future work.
• ⭕ What architecture would let context be loaded selectively per task type, rather than as one flat file?
  Sketched (three-layer protocol/persona-skill/maintenance-subagent model) but explicitly not solvable cleanly today because no major agent exposes the needed lifecycle hooks.

Gaps

• incompleteNeither underlying paper tests the hierarchical, selectively-loaded architecture (the author's own proposed Layer 1/2/3 structure); both only evaluate the flat monolithic file. The article's central architectural recommendation is therefore not itself empirically validated by the evidence it marshals against /init.
  Read next: Look for benchmark studies specifically comparing a layered/on-demand context architecture (e.g. nested AGENTS.md, skill-gated loading) against a flat file, holding task and model constant.
• incompleteThe article proposes 'can the agent discover this?' as a clean binary filter but never grapples with discovery cost (tool calls, reasoning tokens, latency) as a continuum — the Arize result, which shows manual human judgment about what helps a model is often wrong, undercuts the article's own closing advice to apply this filter by intuition rather than by measurement.
  Read next: Look for guidance or tooling that quantifies discovery cost per fact (not just possible/impossible) to make the discoverability filter operational and auditable rather than another intuition-based judgment call.

Closes gaps elsewhere

• Encoding Team Standards · g1 — Supplies exactly the measured instruction-budget/bloat evidence that gap called for: two 2026 studies quantify how AGENTS.md content competes for context/instruction budget and silently degrades (cost +20%+, success -2-3% for auto-generated/redundant content), confirming that 'encoding a standard as an executable instruction' is not reliably executed at scale once the file grows — it degrades the same way bloated context files do.

Related documents

• Audit your Agent files
  Agent Skills Agent Context Files (CLAUDE.md / AGENTS.md) Progressive Disclosure
• Charlie Hills 🦩's Post
  Agent Skills Agent Context Files (CLAUDE.md / AGENTS.md) Context Rot & Context Limits
• Lessons from building Claude Code: How we use skills
  Agent Skills Context Engineering Progressive Disclosure
• How Claude Code works in large codebases: Best practices and where to start
  Agent Skills Agent Context Files (CLAUDE.md / AGENTS.md) Progressive Disclosure
• Encoding Team Standards
  Agent Skills Agent Context Files (CLAUDE.md / AGENTS.md) Intent Debt
• Externalization in LLM Agents: A Unified Review of Memory, Skills, Protocols and Harness Engineering
  Agent Skills Context Engineering Intent Debt
• The Orchestrator's Tax
  Agent Context Files (CLAUDE.md / AGENTS.md) Context Engineering Context Rot & Context Limits
• Agent Skills
  Agent Skills Context Rot & Context Limits Progressive Disclosure
• No Vibes Allowed: Solving Hard Problems in Complex Codebases – Dex Horthy, HumanLayer
  Context Engineering Context Rot & Context Limits Progressive Disclosure
• Harness engineering: leveraging Codex in an agent-first world
  Agent Context Files (CLAUDE.md / AGENTS.md) Intent Debt Progressive Disclosure