本文由 AI 分析生成
建立時間： 2026-09-05 來源： https://addyosmani.com/blog/agents-md/
Summary
Addy Osmani synthesizes two 2026 papers (Lulla et al., ICSE JAWs; an ETH Zurich study) to argue that auto-generated AGENTS.md files (via /init) often hurt agent performance and inflate cost by 20%+, because they duplicate what agents can discover by reading the repo — while human-written files help only when they contain genuinely non-discoverable information (tooling gotchas, non-obvious conventions). He proposes treating AGENTS.md as a living list of “codebase smells you haven’t fixed yet” rather than permanent configuration, and sketches a three-layer architecture (routing protocol file, focused persona/skill files loaded on demand, a maintenance subagent) as the direction the field should move toward.
Addy Osmani 綜合兩篇 2026 年論文（Lulla et al., ICSE JAWs；一篇 ETH Zurich 研究），指出自動生成的 AGENTS.md（透過 /init）經常會降低 Agent 表現、並讓成本增加 20% 以上，因為這些內容只是重複 Agent 本來就能從程式碼中發現的東西——而人工撰寫的檔案只有在包含真正無法被發現的資訊（工具陷阱、非顯而易見的慣例）時才有幫助。他主張把 AGENTS.md 當作「還沒修好的程式碼異味清單」而非永久設定，並勾勒出三層架構（路由協定檔、依任務按需載入的角色/技能檔、負責維護的 subagent）作為未來方向。
Key Points
- Lulla et al.: 124 paired real GitHub PRs, same task/repo/agent with vs. without AGENTS.md — presence reduced median wall-clock runtime 28.64% and token consumption 16.58% (efficiency only, correctness not measured)
- ETH Zurich study: LLM-generated context files reduced task success 2-3% while increasing cost 20%+; developer-written files improved success ~4% but also cost up to 19% more
- Reconciling the two: stripping all existing docs (README, etc.) from repos before testing made LLM-generated AGENTS.md helpful (+2.7%) — the content isn’t wrong, it’s redundant with what the agent can already discover
- “Anchoring effect”: mentioning a legacy pattern (e.g. tRPC) even in passing biases the agent toward it for every future prompt, because LLMs don’t distinguish “this is what we used to do” from “this is what you should do”
- 100% of Sonnet 4.5’s and 99% of GPT-5.2’s auto-generated
/initfiles contained codebase overviews — precisely the discoverable content the paper argues is noise - Concrete signal for what earns a line: mentioning
uvin a developer-written file made agents use it 1.6x/task vs. <0.01x/task unmentioned — non-discoverable, operationally significant, impossible to guess by convention - Proposed 3-layer architecture: (1) protocol file — routing only, personas/skills/MCP available, minimum undiscoverable facts; (2) focused persona/skill files loaded selectively per task type; (3) a maintenance subagent whose only job is keeping layer 1 accurate as the codebase evolves (no major agent currently exposes the lifecycle hooks to do this cleanly)
- The Arize AI automated-optimization angle: an LLM-feedback loop that rewrites CLAUDE.md instructions based on training-task failures beat manual writing by +5-11% accuracy — implies humans often guess wrong about what an LLM actually needs
Insights
- The practical filter Osmani lands on — “can the agent discover this by reading the code? If yes, delete it” — is directly actionable for this vault’s own CLAUDE.md/skill files, which already carry some codebase-map content that could be redundant with what an agent discovers by reading
.claude/vault-codemap.md - The “anchoring effect” (an LLM can’t distinguish past-tense mentions from present-tense instructions) is a subtle failure mode worth checking any of the vault’s own CLAUDE.md/skill instructions against — e.g. stale examples referencing old paths (as found in this vault’s own lint report) could actively mislead an agent, not just fail to help
- Both cited papers measure efficiency, not correctness — worth remembering this is a claim about cost/speed, not proof that lean AGENTS.md files produce better code
Connections
Raw Excerpt
Think of AGENTS.md as a living document of friction you haven’t fixed yet. … You add a line, you investigate why the agent keeps making this mistake, you fix the underlying thing, and then you can probably delete the line.