过时的当前状态,会把下一轮 agent 带偏

公开的 issue 和讨论里,agent 常常把已经过时的「当前状态」当成事实。状态应该去查活的来源。决策和约束,则要放在能留下来的地方。

·1 分钟阅读

公开的开发者 issue 和讨论里,经常出现同一种情况:文件里还写着「当前状态」,事实却已经变了。下一轮 agent 仍会读到这行字,并把它当成现在的情况。

状态还写在那里,事实已经不是那样了

在 eidolon 的一份公开 issue 里,timlawrenz 记录了对「Current state」一节的核对。文件里还写着 z_g 的高范数尾部问题仍未关闭:exp/zg-validity 实验已经获批,但还没跑。仓库里的记录却是:这项实验在 2026 年 9 月 24 日已经结束,并且有一份停用说明写了结论。下面还有一行「下一步」,指向融合栈的 Phase 5。这行字写在当天那条新规则之前:GitHub 看板才是唯一的工作队列。issue 里提醒,这行未纳入看板的「下一步」,可能把 agent 直接带去 Phase 5 的 GPU 工作。

发版之后,也会留下这种过时的现在时。在 gevechtspel2 的一份 issue 里,0.5.20 已经发布,常驻说明里却还把 NET_VERSION 0.5.20 标成未发布。交接文件仍写着第 4、第 5 步要各自开 PR。对应的 #295 和 #296 其实已经合并。

缺的不是文档。是一份快照还在用现在时说话。

agent 会相信你忘了改的那一行

这之所以要紧,是因为下一个读者常常是 agent,而 agent 往往会相信写下来的文字。

waishnav 说,他在多个仓库里都遇到过这种情况。让 Opus 理解代码时,它常常先读文档,再围着文档来理解。文档却不一定是新的。他抓到过完全错误的解释:模型信了一份旧的 Markdown,而没有去看代码实际在做什么。他在考虑两个办法:仓库里的文档干脆不再维护,或者明确告诉 agent,不核对实现,就不要相信文档。他目前更倾向后者,但也越来越想走前一条。

佐治亚理工学院的 Xiaonan Xu 和科罗拉多大学博尔德分校的 Wenjing Wu,在一篇预印本里测量了相近的行为。他们建了 40 个小型 Python 项目,指令文件要求一种写法,现有代码用的是另一种。Claude Code 和 Codex CLI 要在这些项目里加功能。一组会在用户级指令里加一句「文档和代码冲突时,以现有代码为准」,一组不加,一共 320 次运行。不加这句时,agent 的选择有 90.1%(720 项里的 649 项)跟着过时文件走,只有 4.2% 跟着代码走。Claude Code 在 80 次运行里有 79 次自己指出了冲突,然后仍然按文件来写。Codex CLI 有 80 次里的 20 次,把已有代码改成和文件一致;在这 20 次里,有 17 次跑项目原有测试会失败。

这项研究用的是合成项目,只测了两套 agent,而且是一次无人值守的功能任务,指令文件从一开始就是过时的。它不是对真实生产仓库的抽样调查。但它呈现出的倾向,和 waishnav 遇到的是同一类:写下来的那一行,往往比代码更有分量,即便 agent 已经发现两者不一致。

指向活的状态,不要把它写死

有用的拆法,不是「多写一些状态」,也不是「把文档全删掉」。而是不要把会变动的状态,写死在下一轮 agent 会当真的说明里。

回复 waishnav 时,Carlos Granier 说,他机器上的 agent 以前会先读一份 3 月的库存快照,而且那份快照已经过时。后来他改了做法:在两份工具说明后面放一个文件,先让 agent 跑两条命令,一条看当前任务看板,一条看服务健康状况。用他的话说,这是指向状态,而不是描述状态,并把状态从文档里拿掉。

ECUST_AIgalgame 的一份公开 issue 里,也有类似的处理。huaaaji 写到,任务状态同时出现在记忆文件、Issue、PR 和 Git 历史里,已经对不上。PR #72 的本地交接里,文件顶部还写着待复审,分支条目却已经记了复审通过。他的建议是:进行中的工作放到 GitHub Issue 里跟踪;仓库文件只保留稳定的规则、契约,以及离线时用的入口。

可以这样拆:

  • 会随着看板、发版或健康检查变化的内容,不要写死在常驻说明里。 指向活的来源,让下一次会话自己去查。
  • 决策、约束和理由变化得更慢。 写在下一次会话、下一个工具真正会读到的地方。
  • 写下来的当前状态只是一份快照。 它和代码、台账或看板不一致时,以活的来源为准,然后改掉或删掉那一行。
  • 告诉 agent 先核对代码会有帮助,但替代不了一件更基本的事:已经做完的工作,就不要再让说明继续用现在时去讲。

MindMux 本身也在做这个方向的产品。

MindMux 会从你们已经在和 agent 进行的对话里,整理出背景、决策和约束,写成一份 Markdown 项目大脑。Agent 开始任务前,会通过 MCP 读到它。要把 Claude Code 或 Codex 接到这份大脑,安装 @mindmux/cli,在项目里运行 mmx setup。不想登录 Cloud、只要本地 Brain,用 mmx setup --local。开源、可在本地使用的对应产品是 brain.md:仓库里的一个 brain/ 目录,加上一个小的 CLI(@mindmux/brain-md)。每个页面都保留一层 compiled_truth,也就是当前的答案,以及一条只增不改的 timeline,记录你们是怎么走到这一步的。它就放在 git 里,也不绑死在某个 agent 上。Claude Code、Codex、Cursor,以及任何能读文件的工具,都可以用。

这是跨会话、跨工具的决策记忆。状态放在活的来源里。决策和约束放在下一轮会话会读到的大脑里。不要让一行过时的当前状态,把下一个 agent 带偏。

分享到