一条规则一个落点,否则副本已经对不上
公开的开发者 issue 里,同一个项目事实常常被抄进两三处,甚至四处,副本却已经互相矛盾。当前答案只能有一个落点。沿革应该放在别处。
公开的开发者 issue 里,经常出现的并不是缺文件,而是一种更不容易察觉的失败:当前的事实已经写下了,而且写了不止一处,各处的副本却已经对不上。还有一种情况是,当前的结论从来没有被单独写下来,于是下一个 agent 每个回合都要从代码里重新推一遍,有时还会推错。
副本已经对不上了
在 cycling 项目的一份公开 issue 里,Patrik 记录了对 main(5e8284b0)的一次核对:每份文档都通读了一遍,大约 420 条事实陈述拿去和代码对照。问题不在篇幅。真正的问题有三个。
这个仓库里,agent 读的是 AGENTS.md、docs/ 和 .agents/。同一条规则出现在两处到四处,副本已经互相矛盾。每个 PR 都往文档里追加一段实现细节或沿革,本来该写「现在怎么做」的文档,慢慢写成了 changelog。还有几份文档,写的仍是旧产品。
对不上的地方很具体。README 里写内置训练课程有 9 个,代码里是 16 个。一份简报和一份标签说明里点名的标签,仓库里根本不存在。有份文档写转向会在「提前 30 秒(150 到 400 米)」播报,代码里是固定的 300 米。还有几处,两份文档彼此就不一致,只有其中一份和代码相符。
issue 里记下的决定也很直接。文档和代码不一致时,以代码为准;如果看起来是代码错了,就另开 bug,而不是在这次清理里改行为。每条规则只放一个落点,其他地方只保留链接。文档写现在的状态:不要写「以前怎样」,不要用 PR 编号当解释,也不要把过时的决定写在下一读者会当成现行规则的段落里。沿革放在 git 和 issue 里。
「现在是什么」不该靠搜索来猜
还有一种情况:当前值其实写在文件里,却埋在一连串「曾经是怎样」的叙述中。
在 codegraph 的一份 issue 里,GRAPH_FORMAT_VERSION 在同一次会话中从 6 改到了 10。代码是一致的,常量就是 10。但一份给使用者读、用来决定要不要清空 .graph-cache 的文件没有跟上。文件里还留着好几段互不相关的「从 X 升到 Y」的沿革,每一段在当时都是对的,合在一起,想确认「现在是多少」就变成了先搜索再推断。
提出的改法是:用一句写清当前状态;所有历史叙述改成过去时,这样后人扫到旧数字时,不会把它当成现在的值。
没写成当前答案,agent 就会再推一遍
当前答案如果缺了,代价不只是不一致。agent 会把这一回合花在重新推演上。
在 kiln 的两次用户测试里,一个只读的 Copilot 助手缺少对若干事实的既定规则,而这些事实当时已在其他 issue 里补齐。它每个回合都要从 plan.py、cli.py 和各 family 文件里,重新拼出「v0.1 能做什么、不能做什么」:哪些 family 可以训练,原生实例会在计划阶段停下,哪些命令还只是计划中。这一步每次要花 29 到 248 秒。有一次,它还把 V-Pred 用户带到了 eps 模型的页面,并且没有说明项目把 prediction type 记在哪里。
他们打算改成:把当前说明写成一小段,只写一次;这段如果和 family 文件对不上,检查就失败。这份 issue 目前还开着。测试只有两次会话,不是大规模研究。但已经能看出缺当前答案的代价:下一个 agent 会把调研再做一遍,而且仍有可能指错地方。
这是老问题。现在读这些副本的,是 agent。
Google 的文档实践指南说得很直白:一小份新鲜、准确的文档,好过一大堆处于各种失修状态的「文档」。同一份指南在「Duplication is Evil」下还有一条短规则:已有的指南不要再自己写一份,去链接原处;如果原处是错的,就去改原处。
Software Engineering at Google 里,Tom Manshreck 写的文档一章也是这个主张。不同所有者写下的文档仍可能互相冲突。这时要指定一份权威文档:先确定主来源,把其他相关文档并进去,或者废弃重复的那几份。
这套做法讲的是一般工程文档。它不是针对 coding agent 的对照实验,也没有测量 agent 跟着过时副本走的频率。上面这些公开 issue,才是眼下的第一手例子。变化在于读者。同事发现两页对不上,多半会再去看代码。agent 则常常把读到的第一句「听起来像现行规则」的话,直接当成规则。
只保留一个当前答案
可以这样拆:
- 每条现行的事实、决策或约束,只放一个落点。 其他文件只保留链接,不要再复述一遍。
- 写成现在的答案。 你们是怎么走到这一步的,放在 git、issue,或一条只增不改的时间线里,不要写进下一次会话会当成现行规则的那段文字。
- 如果下一个 agent 每个回合都要从代码里重新推这条事实,说明当前答案还没写下来。 写一次,写在下一次会话真正会读到的那个落点。
- 文档和代码不一致时,以代码为准,除非你要另开 bug。然后只改那一个落点。
- 用检查保证当前答案仍和它的来源一致,比指望有人碰巧发现漂移更可靠。
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,以及任何能读文件的工具,都可以用。
这是跨会话、跨工具的决策记忆。如果当前答案只有一个落点,昨天的沿革也不再写在同一段里,下一次会话才更有机会读到同一份真相。