一條規則一個落點,否則副本已經對不上
公開的開發者 issue 裡,同一個專案事實常常被抄進兩三處,甚至四處,副本卻已經互相矛盾。當前答案只能有一個落點。沿革應該放在別處。
公開的開發者 issue 裡,經常出現的並不是缺檔案,而是一種更不容易察覺的失敗:當前的事實已經寫下了,而且寫了不只一處,各處的副本卻已經對不上。還有一種情況是,當前的結論從來沒有被單獨寫下來,於是下一個 agent 每個回合都要從程式碼裡重新推一遍,有時還會推錯。
副本已經對不上了
在 cycling 專案的一份公開 issue 裡,Patrik 記錄了對 main(5e8284b0)的一次核對:每份文件都通讀了一遍,大約 420 條事實陳述拿去和程式碼對照。問題不在篇幅。真正的問題有三個。
這個 repo 裡,agent 讀的是 AGENTS.md、docs/ 和 .agents/。同一條規則出現在兩處到四處,副本已經互相矛盾。每個 PR 都往文件裡追加一段實作細節或沿革,本來該寫「現在怎麼做」的文件,慢慢寫成了 changelog。還有幾份文件,寫的仍是舊產品。
對不上的地方很具體。README 裡寫內建訓練課程有 9 個,程式碼裡是 16 個。一份簡報和一份標籤說明裡點名的標籤,repo 裡根本不存在。有份文件寫轉向會在「提前 30 秒(150 到 400 公尺)」播報,程式碼裡是固定的 300 公尺。還有幾處,兩份文件彼此就不一致,只有其中一份和程式碼相符。
issue 裡記下的決定也很直接。文件和程式碼不一致時,以程式碼為準;如果看起來是程式碼錯了,就另開 bug,而不是在這次清理裡改行為。每條規則只放一個落點,其他地方只保留連結。文件寫現在的狀態:不要寫「以前怎樣」,不要用 PR 編號當解釋,也不要把過時的決定寫在下一讀者會當成現行規則的段落裡。沿革放在 git 和 issue 裡。
「現在是什麼」不該靠搜尋來猜
還有一種情況:當前值其實寫在檔案裡,卻埋在一連串「曾經是怎樣」的敘述中。
在 codegraph 的一份 issue 裡,GRAPH_FORMAT_VERSION 在同一次 session 中從 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 目前還開著。測試只有兩次 session,不是大規模研究。但已經能看出缺當前答案的代價:下一個 agent 會把調研再做一遍,而且仍有可能指錯地方。
這是老問題。現在讀這些副本的,是 agent。
Google 的文件實踐指南說得很直白:一小份新鮮、準確的文件,好過一大堆處於各種失修狀態的「文件」。同一份指南在「Duplication is Evil」下還有一條短規則:已有的指南不要再自己寫一份,去連結原處;如果原處是錯的,就去改原處。
Software Engineering at Google 裡,Tom Manshreck 寫的文件一章也是這個主張。不同所有者寫下的文件仍可能互相衝突。這時要指定一份權威文件:先確定主來源,把其他相關文件併進去,或者廢棄重複的那幾份。
這套做法講的是一般工程文件。它不是針對 coding agent 的對照實驗,也沒有測量 agent 跟著過時副本走的頻率。上面這些公開 issue,才是眼下的第一手例子。變化在於讀者。同事發現兩頁對不上,多半會再去看程式碼。agent 則常常把讀到的第一句「聽起來像現行規則」的話,直接當成規則。
只保留一個當前答案
可以這樣拆:
- 每條現行的事實、決策或約束,只放一個落點。 其他檔案只保留連結,不要再複述一遍。
- 寫成現在的答案。 你們是怎麼走到這一步的,放在 git、issue,或一條只增不改的時間線裡,不要寫進下一次 session 會當成現行規則的那段文字。
- 如果下一個 agent 每個回合都要從程式碼裡重新推這條事實,說明當前答案還沒寫下來。 寫一次,寫在下一次 session 真正會讀到的那個落點。
- 文件和程式碼不一致時,以程式碼為準,除非你要另開 bug。然後只改那一個落點。
- 用檢查保證當前答案仍和它的來源一致,比指望有人碰巧發現漂移更可靠。
MindMux 本身也在做這個方向的產品。
MindMux 會從你們已經在和 agent 進行的對話裡,整理出背景、決策和約束,寫成一份 Markdown 專案大腦。Agent 開始任務前,會透過 MCP 讀到它。要把 Claude Code 或 Codex 接到這份大腦,安裝 @mindmux/cli,在專案裡執行 mmx setup。不想登入 Cloud、只要本地 Brain,用 mmx setup --local。開源、可在本地使用的對應產品是 brain.md:repo 裡的一個 brain/ 目錄,加上一個小的 CLI(@mindmux/brain-md)。每個頁面都保留一層 compiled_truth,也就是當前的答案,以及一條只增不改的 timeline,記錄你們是怎麼走到這一步的。它就放在 git 裡,也不綁死在某個 agent 上。Claude Code、Codex、Cursor,以及任何能讀檔案的工具,都可以用。
這是跨 session、跨工具的決策記憶。如果當前答案只有一個落點,昨天的沿革也不再寫在同一段裡,下一次 session 才更有機會讀到同一份真相。