论文实际测量了什么
指令文件是主要的文档交互界面
细分来看，这 60.5% 包含两个类别。Agent 指令文件是“最频繁使用的文档类型（1,074 次事件，占比 35.4%）”，并且“是 Agent 拉取请求中最频繁修改的文件之一”。Agent 工作笔记——包括计划、thoughts/ 目录、验证日志——占了 25.1%。
相比之下，API 参考文档仅获得 40 次事件，占文档交互的 1.3%。论文自身对这一差距的总结是：指令文件获得的交互次数大约是 API 参考文档的 27 倍。
作者得出的建议非常具体且实用：“对于分配有限文档资源以支持 Agent 贡献者的项目，这一差异表明应优先考虑指令文件的正确性和清晰度。”这并不是说“停止编写 API 文档”——那些文档服务于人类和本研究未观察的工具。只是说，如果你在决定如何为 Agent 花费一小时的时间，AGENTS.md 才是流量聚集的地方。
Agent 不会点击你的链接
这一条悄无声息地颠覆了几乎所有工具给出的建议。“阅读文档后通常会进行进一步的阅读（转移概率为 0.270），而‘遵循引用链接（Follow-reference）’则完全没有被证实。”
“完全没有被证实”意味着在观察中，Agent 从一个文档跳转到另一个文档的引用实例为零。作者的结论非常谨慎：“这种模式促使我们去研究具有本地可检索结构的自包含文档，而不是假设 Agent 会在具有丰富交叉链接的文档中导航。然而，这并不能证明保持链接整洁对行为没有任何影响。”
如果你的指令文件大部分都是指针，那么这一点非常值得深思。“参见 docs/architecture.md 以了解其背后的推理”可能是一个格式良好的句子，但没有任何东西会去执行它。
查阅文档与编辑代码是解耦的
在这方面，论文对其自身的不确定性非常严谨，诚实的总结是，这种耦合是“未解决的”而非“不存在的”。从阅读文档到编辑代码的相邻转移概率为 0.002。未调整的三事件提升度（lift）为 1.05——基本上微乎其微。阶段调整后的模型将其置于 1 以上，即 OR 1.33 [1.09, 1.62]。文档的创建则相反：未调整的提升度升至 1.67，但“其调整后的区间包含了 1”。正如作者所说，“这两种关联在不同的规范中都不一致。”
因此，Agent 会阅读，然后大部分时间它们会进行推理或再次阅读。在查阅环节中，最强的转移是重新阅读自身，概率为 0.270 (CI 0.232–0.307)；其最强的向外转移是进行推理，概率为 0.245 (CI 0.205–0.295)。
没有人根据文档进行验证，查阅文档与减少测试相关
“未观察到任何显式的基于文档的验证序列，且查阅文档与减少即时测试相关（提升度 0.23，聚类 CI 0.08–0.45；调整后 OR 0.39 [0.25, 0.60]）。”在其他地方，论文直截了当地指出：“验证事件为零。”
这是观察数据中的相关性，而非因果关系声明，作者也没有做出此类声明。但这意味着，目前流行的“应该编写文档以便 Agent 可以对照其检查工作”的观点，描述的完全是这里根本没有发生过的事情。
Agent 阅读文档是因为它们主动选择，而不是因为它们卡住了
查阅文档有 70.2% 的情况是自主发起的，而因失败驱动的仅占 7.5%；在失败事件中，文档反馈到查阅环节的比例仅为 5.4%。而且文档滞后于代码，而不是引导代码：“在同时修改两者的多提交拉取请求中，先修改代码的频率是先修改文档的 4.7 倍。”
作者自己的解释才是最有趣的部分
在发现了一个与文献中描述的人类开发者不匹配的循环后，他们提出了两种候选机制，但拒绝做出选择：
“Agent 可能会将推理外包到文件中，因为它们的上下文窗口是有限的，这使得文档成为一种工作记忆的形式，而不是参考资料；计划和 thoughts/ 目录的突出存在与这种可能性是一致的。或者，它们可能不会根据文本进行验证，因为它们直接调用了成本更低的验证工具（测试套件）。在这两种情况下，我们都没有观察到文本发挥规范（specification）的作用。”
这单一的假设重新定义了整个 60.5%：Agent “阅读”的大部分内容可能是它们十分钟前自己写的笔记，因为没有其他地方可以存放。这产生了一个目前没有任何工具可以解决的问题。“计划、thoughts/ 目录和验证日志作为持久产物在仓库中累积。仓库整理工具、代码审查清单和文档质量指标目前对它们没有任何分类。”
这确立了什么，又没有确立什么
理清边界比看标题更重要，而这篇论文自身的局限性部分异常直接。
这 60.5% 是文档交互的比例，而不是 Agent 阅读的所有内容的比例。 分母是 94,813 个开发事件中的 3,033 个文档交互。它不是“Agent 阅读内容的 60.5%”。任何将其引用为 Agent 总活动比例的人都篡改了这一声明。
该数据中有四分之一是明确临时性的。 这是大多数二手总结都忽略的警告，作者在文中写道：“agent_working_note 类别——占文档事件的 25.1%，也是我们的主要发现之一——依赖于语言模型对 500 个模糊路径（占模糊事件的 98.4%）的分类，其中有 27 个路径退回到关键字规则。尚未对这些标签进行人工验证……在此之前，该类别的精确比例应被视为临时性的。”他们补充说，定性发现比数字更稳固：无论确切百分比如何，Agent 编写的工作文档都是“一个庞大且此前未分类的类别”，在原始路径中清晰可见。
绝对比率是下限。 “文档是通过文件路径识别的。Docstring、行内注释和嵌入在源文件中的文本对我们的检测工具是不可见的。”偏好源内文档的项目代表性不足，作者也指出了这一点。
没有测量 Agent 为什么要阅读。 “目的未被测量……在设计上，我们不分析 Agent 阅读特定文档的原因。”该研究报告了触发因素、交互类型和结果，而不是意图。
这是观察性的，所以这里没有任何内容表明改变你的文档会改变行为。 特别是在可操作性方面：“这些分析没有为这种耦合提供一致的行为证据，我们的观察性设计无法表明提高可操作性会改变行为。”
作者拒绝了对他们来说最容易被引用的对比。 “我们明确拒绝得出基于文档的恢复更有效的结论，尽管它具有最高的值估计（63.6%）。由于仅有 11 个事件具有可观察的结果，区间跨度为 35.4–84.8%，并且与每个替代方案重叠。”这是一个研究团队放弃了一个博眼球的标题，而这正是其余内容值得信赖的原因。
而且它与其他指向不同方向的研究并存。 其他 2026 年的研究测量了上下文文件对性能的影响，发现其影响微弱或为负；另一条研究路线测量了精选检索带来的收益，这些收益随着模型能力的提升而扩展——这正是你应该给 AI Agent 多少记忆中的立论基础。本文两者都没有测量，它测量的是行为。调和这两者是一项开放性的工作，而两天前的一篇论文指出我们的测量学科还没有为此做好准备——这在Agent 记忆真的能提高性能吗中有所讨论。
MemoryLake 未参与此项研究。 这里的任何内容都没有评估记忆层，无论是我们的还是其他任何人的。
人们会从中得出什么误解，以及为什么不应该
“Agent 忽略了你的指令文件。” 这与研究发现恰恰相反。指令文件是目前阅读量最大的文档交互界面。薄弱的是阅读与下一步行动之间的联系——这是一个不同的主张，也是我们之前在为什么 Agent 会忽略你编写的指令文件中指出的区别：加载不等于遵守。这篇论文强化了这一点。它们加载了，也被大量阅读了，但阅读仍然无法可靠地决定行为。
“所以文档并不重要。” 论文指出，在此语料库中，有两个特定的主张缺乏行为支持——可操作性和可验证性。它并没有说文档毫无用处，并且明确建议在指令文件的正确性上进行投入。
“Agent 在卡住时会阅读文档。” 仅有 7.5% 是由失败驱动的。这一信念与触发因素分布最为直接地相矛盾。
“交叉链接毫无意义。” 在这些运行轨迹中，“遵循引用链接”未被证实，且作者拒绝得出链接整理没有后果的结论。这是不同的陈述。
“这证明了 Agent 需要一个记忆系统。” 它完全没有证明这一点。它只是观察到 Agent 编写了类似于工作记忆的文件，并将其作为行为模式的两种候选解释之一。
解决方案：将笔记视为记忆，并给它们一个比你的仓库更好的去处
如果工作记忆假设是正确的，那么这些 thoughts/ 目录和计划文件的一部分就是 Agent 在用它唯一的工具——你的 git 仓库——进行记忆管理。你的审查流程中没有任何类别适用于这些文件。随之而来的是三件事。
审计正在累积的内容。 在你的仓库中搜索计划文件、thoughts/ 目录和 Agent 创建的验证日志。针对每个目录，决定每个文件是持久产物还是临时草稿。大多数团队会发现，他们在不知不觉中把这两者都提交了。
将优化指令文件的时间花在流量聚集的地方。 在这里投入正确性和清晰度，比在 Agent 仅打开 1.3% 时间的 API 参考文档上投入同样的精力回报更高。而且由于“遵循引用链接”未被证实，对于任何必须落地的规则，应优先选择自包含的陈述，而不是指针。
将引导与记忆分离。 指令文件是常驻的，并且受到读取它的每个工具的限制，因此持久知识——决策、约束、被否决的方法——会首先被挤出。然后 Agent 通过编写计划文件来重建它。
最后一点正是 MemoryLake 的用武之地：将记忆作为你可以读取、纠正和删除的条目，在相关时进行查询，而不是作为副作用提交到你的仓库中。设置只需三个步骤。
步骤 1：创建 API 密钥
登录 MemoryLake 并创建一个 API 密钥。一个凭证即可跨越你连接的所有工具。
步骤 2：上传你的第一批记忆
简短的条目，每条包含一个主张。编写目前最终会进入计划文件或无处安放的材料：
带有强制约束的决策。 指令文件通常将其声明为规则，但丢弃了原因。
在此已被否决的方法及其原因。 书面的否决可以阻止新的会话重新推导它们——而重新推导正是那些 thoughts/ 文件所记录的工作。
没有任何通知的环境事实。 仅在 CI 中失败的测试、未记录的速率限制、两个迁移之间的顺序要求。
你给出过不止一次的纠正。 如果一个人不得不说两次，它应该存在于可检索的地方，而不是存在于已经结束的对话中。
步骤 3：连接你的 AI 和 Agent
连接你使用的工具。MemoryLake 可以通过 MCP 和 API 访问，因此 MCP 原生 Agent——包括 Claude Code、Codex 和 OpenClaw——可以通过指向 MCP 服务器进行连接，而其他助手则通过 API 读取相同的记忆。你检索的内容不会使常驻的指令文件膨胀，也不会进入你的提交历史记录。
三个诚实的限制，第一个也是本文的重点。MemoryLake 未参与此项研究，且本论文并非记忆层改变 Agent 行为的证据——其设计是观察性的，作者明确指出它无法表明改进文档会改变 Agent 的行为。它只保存你或你的 Agent 写入其中的内容。而且它不会清理你的仓库：审计 Agent 已经提交的计划文件是一项手动工作。
这在实践中改变了什么
指令文件晋升为一等文档。 它们是阅读量最大的交互界面，但在大多数仓库中，它们获得的审查比 README 还要少。
Agent 编写的笔记成为审查类别。 目前它们没有任何审查机制——没有整理工具，没有清单行，没有陈旧度指标。
指针不再是内容的替代品。 “遵循引用链接”未被证实。如果一个约束很重要，请在需要的地方直接声明它。
文档不再是你的失败恢复计划。 Agent 是主动查阅文档，而不是在卡住时才查阅——因此它更接近于引导说明，而不是手册，应该以这种方式来编写。
编写 Agent 真正使用的文档的最佳实践
将你最宝贵的一小时投入到指令文件中。 它是语料库中阅读量最大的文档类型，大约是 API 参考文档的 27 倍。
使每个陈述自包含。 未观察到对引用的跳转。假设读者在打开的文件处就停止了。
给 Agent 工作笔记一个归宿和生命周期。 决定什么是持久的，什么是临时的，以及什么根本不应该被提交。
不要依赖文档作为验证界面。 观察到的验证事件为零。测试才是 Agent 真正寻求的权威验证工具。
不要将推理留在常驻文件中——每个工具都会限制它们，而推理会首先被裁剪，这就是为什么 RAG 不是记忆中提到的问题——并且将分散的笔记整合为可查询的内容，即将项目文档转化为 AI 记忆的形式。
将单一语料库的行为发现视为临时性的。 两个数据集、通过路径识别的文档、一个被作者标记为未验证的工作笔记类别。很有用，但尚未尘埃落定。
结论
编码 Agent 究竟在读什么？根据 557 个会话和 33,097 个拉取请求的证据：绝大多数是为它们编写的文件。Agent 指令文件和 Agent 工作笔记占文档交互的 60.5%，传统技术文档占 10.6%，API 参考文档占 1.3%。
但顺序比比例更重要。Agent 是主动查阅文档，而不是在卡住时才查阅；它们在阅读和推理中循环，而不是转向代码；它们从不跳转到另一个文档的引用，也从未被观察到根据文本验证其工作。作者自己的理解是，这其中很大一部分可能根本不是在寻找参考资料——受限的上下文窗口促使 Agent 将推理外包到文件中，“使得文档成为一种工作记忆的形式，而不是参考资料”。
如果这是正确的，那么实际的结论就不是“写更好的文档”。而是你的仓库已经悄然成为了 Agent 的草稿纸，而没有任何审查流程意识到这一点。在指令文件上进行投入，因为那是阅读量所在的地方。使陈述自包含，因为没有任何东西会点击你的链接。并且给持久的知识——决策、约束、已被排除的方法——一个归宿，而不是一个有字节限制的常驻文件或一个无人审查的 thoughts/ 目录。