AGENTS.md 不是决策日志

这一周，MindMux 团队阅读了一批公开的开发者讨论、issue 和评论，看人们实际上是怎么维护 AGENTS.md 和 agent 记忆的。这不是一项正式调查，我们也没有附上无法核验的数字。下面写的是这些讨论里反复出现的模式（不提及具体姓名），再加上两篇近期论文，以及一套把 AGENTS.md 和决策日志分开的实用做法。

大家用的词出奇地一致。人们在说 AGENTS.md 同步、过时的 AGENTS.md、每次新对话都要重新解释已经做过的决定，以及需要唯一的真实来源。他们要的不是一份更长的规则文件，而是一个决策能住进去、又不会慢慢腐烂的地方。

Agent 会遵守你忘了更新的那一行

AGENTS.md 之所以有用，是因为 agent 真的会读。这也正是一行过时内容代价很高的原因。

2026 年 11 月 6 日，Tural Mehtiyev、Biruk Tadesse、Lawrence Arkoh 和 Wesley Assunção（北卡罗来纳州立大学）发布了预印本 When Instruction Files Go Stale: Documentation Debt and Hidden Cost in Coding Agents。他们从根目录含有 AGENTS.md，或在他们测量的部分案例中含有 CLAUDE.md 的活跃开源仓库里，深入研究了三条真实过时指令：一条测试命令、一处代码位置，以及一套添加组件的步骤。Agent 在同一条指令的三个版本下修复 22 个维护任务——保持过时、改成正确，或直接删掉——代码和任务保持不变。作者分析了两个模型（Claude Haiku 5.5 和 Claude Sonnet 5.5）的 732 条轨迹，精确到每一次工具调用。

只要这条过时指引和任务相关，agent 就会跟着走，有时仓库里别处已经有正确信息，也照样跟着走。在过时的测试命令上，Claude Sonnet 5.5 平均每次要多两次工具调用，比使用更正后的命令多出约三分之一。任务通常还是做完了，测试也过了。它们靠搜索代码库自己绕了过去。但在全部 732 次运行里，没有任何一次去改那份指令文件。把过时的那一行改正，可以消除对已失效路径的操作；删掉它，则能阻止其中的大部分。只看任务是否成功，这笔成本就被藏起来了：过时的那一行留在仓库里，等着下一次会话再次被加载。

这项研究是一次聚焦实验，作者自己也这样写。它用的是同一家厂商的两个模型、同一套运行环境、三类过时上下文和 22 个任务。这 732 次运行是在重复这几个案例，而不是对大量彼此独立的文档债做抽样。额外耗时被明确测到的，主要是 Sonnet 在过时测试命令上的表现；在其他情况下，作者未能检测出工具调用或 token 上的差异。

这仍然和我们本周在公开讨论里反复看到的情况对得上。有开发者审查了一份很长的常驻指令文件，发现里面已经有多处写错：运行时版本过时了，项目早已不用的支付服务商还写在里面，还引用了已经不存在的 migrations。Agent 仍然按文件行事，而不是按代码。另有团队的 AGENTS.md 是从一份更早的、绑定特定工具的文件查找替换出来的，于是两套工具读到的项目说明并不一样，连模型名都写错了。还有人眼看着同一套指引的副本在一天之内就漂开了，因为改动只落进了其中一处。有人在好几个仓库之间来回复制同一份 AGENTS.md，然后开始问项目级覆盖该怎么做。真正去测量哪些行还在起作用的团队，往往会大幅砍短文件，并问出一个更好的问题：文件越长，是不是就过时得越快？

一份每次会话都会被加载的 AGENTS.md，每次会话都会被遵守——包括那些已经不再正确的行。而且 agent 不会替你修好这份文件。

AGENTS.md 不是决策日志

AGENTS.md 有自己的职责：告诉 agent 在这个仓库里该怎么干活。该跑哪些命令，哪些目录不要碰，PR 该怎么开。

这和记住「为什么选 cookie session 而不是 JWT」、某个支付服务商已经被替换、或者上个月的裁定已经推翻了文件里还留着的那条规则，不是同一件事。

这些判断如果没有别处可去，就会漏进错误的地方。在我们读到的讨论里，有些长期有效的决定只活在某个模型的记忆里，于是下一次会话又把团队早已拍板的问题重新抛出来。有人准备开始手写架构决策记录，因为仓库里没有任何地方装着那个结论。也有团队承认，没有书面的决策日志，同样的事每周都要重新决定一遍。还有 agent 自己写下的记忆，和经过人工审阅的 AGENTS.md 互相冲突，于是项目里出现了两套「我们相信什么」，开始打架。

第二篇论文把底层问题讲得很清楚。2026 年 11 月 10 日，Yukyeong Lee、Yumin Choi、Jinheon Baek 和 Sung Ju Hwang（KAIST 与 DeepAuto.ai）发布了 Don't Just Trust Your Memory: Evidence-Linked Memory Reduces Memory-Induced Degradation in LLM Agents，并提出了 WikiTrace。他们观察的是：agent 在没有记忆时能稳定做对、加上记忆后反而做错的那些任务。这类失败里，有 52% 可以追溯到 agent 遵从的某一条记忆，而且常常是一条错误的记忆。经验是从过往运行里提炼出来的，交出去时却没有附上它来自哪一次轨迹，agent 也就无从核对。把每条经验链接回它来源的那次运行之后，在五个 agent 基准、八组套件上的平均得分从 87.0（同样的 insights，但没有来源）提升到 90.2，这类回退也从 6.5% 降到 4.5%。

这些结果来自模拟文本世界和工具使用环境，而不是仓库里的指令文件，部分失败原因也由 LLM 评判器标注。即便如此，它仍然是一条有用的警告：一条没有「为什么」的规则，只是传闻。决策日志既要保存当前的答案，也要保存得出这个答案的证据，包括后来的撤销。

一份真实来源，跨工具、跨仓库

只要不止一个工具在用，同步问题就会变得更糟。

在我们读到的讨论里，同时使用 Claude Code 和 Codex——有时还有 Pi——的开发者会问，怎样用一份 AGENTS.md 在不同工具之间携带同一套前提，免得换工具时再把项目讲一遍。维护许多客户仓库的团队，正在头疼 AGENTS.md 和其他文档到底该怎么分工、怎么保持同步。有的团队已经在用一个协调仓库，只要克隆一个地方，就能让 agent 跨项目工作；而最常见的第一句回应往往是：这份文件很快就会过时。还有人不希望记忆被锁在某一家厂商的产品里。他们希望每个 agent 读到的是同一份记录。

整个行业也在朝共享上下文走，原因是一样的。2026 年 11 月 10 日，Cursor 的文章 Projects is now multiplayer（Aryaman Khandelwal）写得很直接：在一个对话里做出的决定，Project 里的每个 agent 都能读到。这个方向是对的。过去 agent 的上下文是按人隔离的，但团队是一起做决定的。这些知识仍然应该属于项目本身——用任何工具都能读、能在 PR 里审查、下个月换了 agent 也还找得到的形式保存下来。

这里说的是已经做出的决策，如何在跨会话、跨工具时被记住。

怎么审查 AGENTS.md，以及决策该放在哪里

开始做这件事，并不需要先上一套新工具。真正有用的分界是：agent 在这个仓库里该怎么干活，以及项目里已经决定了什么。

先审查 AGENTS.md。 打开这份文件，包括其他仓库或子目录里的副本。对每一条命令，实际跑一遍，或至少确认路径还在。对每一个目录或文件名，检查它是否仍然存在。对运行时、版本、服务商和支付提供方，核对仓库是否还在用它们。如果同一份指引出现在不止一处，就把它们 diff 一遍：只改了一边，就已经是漂移。凡是在回答「我们为什么选这个」或「我们否定了什么」的内容，都是决策，不是常驻规则——把它们移出去。

让 AGENTS.md 保持简短。 它适合放构建、测试、lint 和运行的命令，不要碰的目录或文件，PR 该怎么开，以及其他容易对照仓库核实的当前事实。它不该是存放「为什么」的地方。

把决策写进日志。 每条记录都需要当前答案、日期、简短理由，以及状态——如果后来的决定推翻了更早的决定，还要写明它取代了什么。下面是一个示意例子，不是某个真实项目的记录：

# Auth strategy

Status: active
Supersedes: JWT for the desktop app (2026-09-02)

Current answer: Cookie-backed sessions in the existing SQLite store.
The app is local-first and has no hosted backend.

- 2026-10-19 — Chose sessions over JWT. There is no server component
  that would justify JWT.
- 2026-09-02 — Evaluated Auth.js and Lucia; deferred. JWT looked like
  the default and did not fit a local-first app.

审查之后，改正或删除过时的行。在上面那项研究里，改正过时指令消除了对已失效路径的操作，删除它则阻止了其中的大部分。不要等 agent 来修这份文件。那 732 次运行里，没有一次它会去改。

MindMux 做了什么

MindMux 本身也在做这个领域的产品，所以这里如实说明今天它实际做了什么。

MindMux 会从你们已经在和 agent 进行的对话里——就是那些聊天——整理出背景、决策和约束，写成一份 Markdown 项目大脑，让 agent 在开始任务之前通过 MCP 读到。它的开源、本地对应物 brain.md，是仓库里的一个 brain/ 目录，外加一个小巧的 CLI（@mindmux/brain-md）。每个页面都保留一层 compiled_truth——当前的答案——以及一条只增不改的 timeline，记录你们是怎么走到这里的。它原生属于 git，也不绑死在某个 agent 上：Claude Code、Codex、Cursor，以及任何能读文件的工具，都可以用。

AGENTS.md 可以保持简短。大脑负责装决策。当结论发生变化，旧的判断会留在记录里。下一次会话、下一个工具，都会从同一份理解开始——而不是从昨天刚刚漂开的那份复制过来的 AGENTS.md 开始。

这是跨会话、跨工具的决策记忆。

如果这正是你遇到的问题：

• MindMux： mindmux.ai
• brain.md： projectbrain.md

如果你注意到的第一件事是，某个决定不用再解释一遍，或者两个工具终于读到了同一份决定，那它就生效了。

参考文献

• Tural Mehtiyev、Biruk Tadesse、Lawrence Arkoh、Wesley Assunção，When Instruction Files Go Stale: Documentation Debt and Hidden Cost in Coding Agents，arXiv 预印本，2026 年 11 月 6 日。
• Yukyeong Lee、Yumin Choi、Jinheon Baek、Sung Ju Hwang，Don't Just Trust Your Memory: Evidence-Linked Memory Reduces Memory-Induced Degradation in LLM Agents，arXiv 预印本，2026 年 11 月 10 日。
• Aryaman Khandelwal，Cursor Projects is now multiplayer，2026 年 11 月 10 日。