過時的當前狀態,會把下一輪 agent 帶偏
公開的 issue 和討論裡,agent 常常把已經過時的「當前狀態」當成事實。狀態應該去查活的來源。決策和約束,則要放在能留下來的地方。
公開的開發者 issue 和討論裡,經常出現同一種情況:檔案裡還寫著「當前狀態」,事實卻已經變了。下一輪 agent 仍會讀到這行字,並把它當成現在的情況。
狀態還寫在那裡,事實已經不是那樣了
在 eidolon 的一份公開 issue 裡,timlawrenz 記錄了對「Current state」一節的核對。檔案裡還寫著 z_g 的高範數尾部問題仍未關閉:exp/zg-validity 實驗已經獲批,但還沒跑。repo 裡的記錄卻是:這項實驗在 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 說,他在多個 repo 裡都遇到過這種情況。讓 Opus 理解程式碼時,它常常先讀文件,再圍著文件來理解。文件卻不一定是新的。他抓到過完全錯誤的解釋:模型信了一份舊的 Markdown,而沒有去看程式碼實際在做什麼。他在考慮兩個辦法:repo 裡的文件乾脆不再維護,或者明確告訴 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,而且是一次無人值守的功能任務,指令檔從一開始就是過時的。它不是對真實生產 repo 的抽樣調查。但它呈現出的傾向,和 waishnav 遇到的是同一類:寫下來的那一行,往往比程式碼更有分量,即便 agent 已經發現兩者不一致。
指向活的狀態,不要把它寫死
有用的拆法,不是「多寫一些狀態」,也不是「把文件全刪掉」。而是不要把會變動的狀態,寫死在下一輪 agent 會當真的說明裡。
回覆 waishnav 時,Carlos Granier 說,他機器上的 agent 以前會先讀一份 3 月的庫存快照,而且那份快照已經過時。後來他改了做法:在兩份工具說明後面放一個檔案,先讓 agent 跑兩條命令,一條看目前任務看板,一條看服務健康狀況。用他的話說,這是指向狀態,而不是描述狀態,並把狀態從文件裡拿掉。
ECUST_AIgalgame 的一份公開 issue 裡,也有類似的處理。huaaaji 寫到,任務狀態同時出現在記憶檔、Issue、PR 和 Git 歷史裡,已經對不上。PR #72 的本地交接裡,檔案頂部還寫著待複審,分支條目卻已經記了複審通過。他的建議是:進行中的工作放到 GitHub Issue 裡追蹤;repo 檔案只保留穩定的規則、契約,以及離線時用的入口。
可以這樣拆:
- 會隨著看板、發版或健康檢查變化的內容,不要寫死在常駐說明裡。 指向活的來源,讓下一次 session 自己去查。
- 決策、約束和理由變化得更慢。 寫在下一次 session、下一個工具真正會讀到的地方。
- 寫下來的當前狀態只是一份快照。 它和程式碼、紀錄或看板不一致時,以活的來源為準,然後改掉或刪掉那一行。
- 告訴 agent 先核對程式碼會有幫助,但替代不了一件更基本的事:已經做完的工作,就不要再讓說明繼續用現在式去講。
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 會讀到的大腦裡。不要讓一行過時的當前狀態,把下一個 agent 帶偏。