研究与体感在同一个方向上收敛
Theo 先引用研究结果，Agent MD / Claude MD 在多个模型上会稳定拉低表现，然后用自己 20% 左右的额外成本和更差结果去呼应。这个一致性很有说服力。
AI Engineer 2026 · Video Notes 05
Theo：很多人以为自己在调教 agent，其实只是在用过期文档给模型制造幻觉
Theo 比 Matt 更进一步，他不只说 repo 文档会浪费上下文，还说很多时候你该修的不是提示文件，而是代码库本身。
Theo 这条视频更像一次“上下文管理总复盘”。他援引研究，也给出自己的实测，结论非常直白，CLAUDE.md / AGENT.md 往往让模型表现更差，而且代价不仅是 token 变贵，还包括错误引导、注意力分散，以及维护一份注定过期的伪 source of truth。
核心观点提炼
如果信息在代码里，就别再写一遍
他对某个 agent MD 样本的拆解很狠，commands、架构、数据流状态、目录说明，几乎都被判定为“代码里已经有”。重复描述只会把模型往错误方向 steer。
真正高杠杆的动作是修 codebase，而不是堆文档
Theo 一个很有意思的点是，把 agent 的困惑当作 codebase design feedback。它卡住的地方，往往说明你的结构、命名、边界或 discoverability 有问题。
故意让 agent 暴露误解，可以帮助你改系统
他甚至会有意通过 agent MD 暴露模型卡点，但目标不是长期保留这些提示，而是借此观察，再去调整架构。
站在 2026 AI engineer 的学习点
- 把 agent 的困惑视为 repo 可维护性信号，而不是单纯 prompt 问题。
- 不要把会变动的工作流摘要写成“常驻真理”，它们很快就会和代码脱节。
- context、cost、latency 是同一个约束面的不同表现。
- 最好的 agent 体验，很多时候来自可发现、可推断、命名清晰的 codebase，而不是更长的规则文件。
- 如果你非要写 AGENT.md，就把它当临时实验工具，而不是永久配置中心。
内容脉络与时间线
开场
先用研究结果拆穿共识
Theo 先把“每个 repo 都该有 CLAUDE.md”这类流行信条打碎。
前半段
分析为什么这些文件会把模型带偏
他把问题归结到 context management，不必要的 steer 会让模型偏离真正该看的源头。
中段
现场拆解一个具体 Agent MD
commands、architecture、workflow states 等条目被逐一否定，因为它们并非高价值常驻信息。
后半段
把 agent 的误解转化为架构改进信号
Theo 说明自己很多时候只 merge 少量 agent 改动，但会利用其余输出去改进代码库。
结论
该优化的是 repo 与 discoverability，不是继续堆文档
这把“prompting”问题重新定位回软件工程本身。
值得反复咀嚼的句子
“If the info is in the codebase, it probably doesn’t need to be in the agent MD file.”
这是整条视频最值得记住的一句。
“Agent MD files will go out of date.”
不是可能会，而是几乎必然会。
“I merge less than a fifth of the changes it proposes, but the other four out of five I use to make the codebase better.”
Theo 最强的洞察在这里，agent 不只是写代码机器，还是暴露系统缺陷的探针。
我的结论
Theo 把问题讲得更彻底，很多人把 agent 失误归咎于“没写好提示文件”，但真正的病灶常常在 repo 本身。对 2026 年的 AI engineer 来说，最有价值的能力不是写更长的 CLAUDE.md，而是把代码库做成一个 agent 自然读得懂、走得通、改得动的环境。