问题不在于有没有文档，而在于常驻上下文里塞了什么
他把焦点放在 context window 预算。system prompt、工具说明、MCP、项目文档都要抢上下文，如果你把 package.json 命令、框架栈、目录结构这种“可自行发现”的内容也常驻进去，就是在浪费 agent 的注意力。
AI Engineer 2026 · Video Notes 04
Matt Pocock：别迷信 /init，自动生成的 AGENTS.md 往往不是资产，而是上下文税
这条视频的价值，在于它不是简单反对文档，而是把文档放回一个更准确的位置，只有不易发现、稳定、最小化的信息，才配常驻上下文。
Matt 的核心判断很锋利，而且我认为是对的。对 coding agent 来说，最昂贵的不是“缺一份规则文件”，而是把本来能从代码库自行发现的信息，重复塞进常驻上下文里。/init 自动生成的 CLAUDE.md 或 AGENTS.md，常常就在做这件事。
核心观点提炼
可发现信息不该重复描述
Matt 反复举例，像 scripts、React Router、SSR、effect imports 这类事实，agent 直接读代码比读一份过期摘要更靠谱。文件系统本身就是一种低摩擦、高保真的提示结构。
最危险的不是无用，而是腐烂
一旦 AGENTS.md 开始写具体文件、实现细节、架构解释，它就会很快与真实代码漂移。漂移后的上下文不是“帮助”，而是主动误导。
真正该保留的是最小且难发现的约束
从视频脉络看，他不是主张完全零文档，而是主张只保留那些不容易从代码库推断、但又对正确实现很关键的约束。
站在 2026 AI engineer 的学习点
- 先问一遍，这条信息 agent 能不能通过读代码、跑命令、看目录自己发现。能发现，就别写进常驻文件。
- AGENTS.md 应该像 schema，不该像 README。写稳定约束，不写随时会变的实现摘要。
- 上下文预算是硬资源，任何常驻 token 都要证明自己值得。
- 目录结构、命名和 source of truth 文件，本身就是给 agent 的隐式提示系统。
- “自动初始化文档”默认该被怀疑，而不是默认被信任。
内容脉络与时间线
开场
先抛结论：不要运行 /init
Matt 直接挑战社区默认做法，认为自动生成的 CLAUDE.md / AGENTS.md 通常弊大于利。
前半段
用上下文预算解释为什么它有害
他把 agent 工作拆成 system prompt、探索、实现、测试等阶段，说明常驻文档会压缩后面更宝贵的探索与实现空间。
中段
逐项拆解 init 生成内容
commands、architecture、stack 描述等内容被逐条批判，因为这些都能从代码库直接发现。
后半段
引出真正该写什么
不易发现但稳定的要求，才值得进 CLAUDE.md；其他内容应该回到代码、脚本和目录结构本身。
结论
把文档从“默认全写”改成“最小必要”
这实际上是在重新定义 repo-level context file 的职责边界。
值得反复咀嚼的句子
“If you need to discover what commands are available, you can actually look at the source of truth.”
source of truth 优先于重复文档，这是整条视频的底层逻辑。
“Anything that you put in your claw.md is going to make this bigger and bigger and bigger.”
他把 repo 文档问题准确翻译成 context budget 问题。
“This will rot really, really fast.”
腐烂速度，决定了很多“好心文档”最终会变成坏上下文。
我的结论
Matt 这条最值得拿走的，不是“删掉所有 AGENTS.md”，而是一个更硬核的判断标准，凡是 agent 可自发现的信息，都不该长期占用它的认知带宽。2026 年会写 agent 文档的人，首先应该会删文档。