下一個 session 從未見過的決策
一次會議裡拍板的架構決定,或一位工程師在 agent session 裡做的取捨,常常到不了下一個人、下一套工具。公開討論裡,團隊試著用共享決策日誌補上這個缺口;紀錄缺失或過時,agent 仍會往錯誤的方向走。
公開的開發者討論裡,經常會談到同一個缺口。一個架構決定在會議裡拍板,或是某位工程師在 Claude Code session 裡做的。幾週後,另一位工程師的 agent 改出了完全相反的結果。Oana Olteanu 把這個問題說得很直白。她問,這是不是已經在造成返工或缺陷;大家現在怎麼處理:repo 裡的規則、共享記憶、程式碼審查,還是自己做的工具。
沒有人想要一份更長的指令。大家是想給決策找個能放的地方,好讓下一次 session 真的讀得到。
決策沒有離開那次 session
Iván Spiler 寫到,他用自己的 agent 方案做日常開發時,經常撞上這件事。難的不是 agent。一次 session 裡做出的決策,對下一次 session 來說根本不存在。他們的辦法是一份共享的決策日誌:每個 agent 開始前先讀,結束後把新決策追加進去。他說這辦法很粗糙,不過大多數衝突就被它擋住了。
blackleg 碰到的是同一類情況:兩個人在同一個 repo 裡跑幾天 agent,問題就會出現。第一次 session 裡的筆記,進不了第二次 session 的上下文。那些悄無聲息的矛盾,要到程式碼審查才被發現。他們讓每次 session 先讀一份短的 AGENTS.md,意外的重寫少了不少,可會議上口頭定下的決策還是會漏掉。他接著問,這些口頭決定在進到 agent 之前,別人是怎麼記下的。
這不是新問題,只是變得更快了。Microsoft 的 Azure Well-Architected 在 architecture decision records 裡寫得很直接:一個做了但從未記錄下來的決策,多半會被忘掉。同樣的爭論會再來一輪,後來的改動也可能在不知情的情況下,跟當初的意圖相反。
寫下來,不等於能一直保持更新
有些團隊已經有了共享的架構紀錄。真正難的,是保持更新。
Ryan 有一個架構 repo,開發者和 agent 都能拉下來對照。他寫到,難的是保持更新。這需要很強的紀律。一旦過時,agent 又會往錯誤的方向走。
這樣的提醒,在 coding agent 出現之前就有了。2011 年,Michael Nygard 發表了 Documenting Architecture Decisions。他的看法是:大文件從來不會被持續更新,也沒有人會去讀。小的、可以分開維護的紀錄,至少還有被更新的機會。一個專案做下來,最難跟上的往往是決策當初為什麼那樣做。不知道這些,後來的人只剩兩種壞選擇:盲目接受,或盲目改掉。他當時寫的只是一份很小的經驗整理。那種格式從同年 8 月初開始用,只用在幾個專案上,先後大約有六到十位開發者參與過。回饋是正面的,尤其對比較長期的意圖有幫助。這不是一次大規模的對照研究。
AWS 的規範性指南在 architectural decision record process 裡,對怎麼保存歷史,也是同樣的思路。團隊接受一份 ADR 之後,它就不可更改。如果有了新的認識,需要不同的決定,就提出一份新的 ADR。新的被接受後,取代舊的那份。Microsoft 的指南把這份日誌稱為只增不改:1不要回去改已經接受的紀錄。另寫一份新的,標明它取代舊的,並把兩份連起來。指南還說,一份沒有寫明理由的紀錄,時間久了就會失去價值,因為後來的人無法判斷,這個決策現在是否仍然成立。
一份可以被悄悄改寫的決策日誌,是一份無法信任的日誌。一份從不更新的決策日誌,則會把下一個 agent 指向錯誤的方向。
有些決策能被檢查,其餘的要等到審查
Vini Francisco 介紹了他們團隊正在用的做法。repo 裡放 ADR,寫明決策、原因,以及被排除的替代方案。Agent 改程式碼之前先讀這些紀錄。能被檢查的決策會變成 lint 規則,用來落實架構,比如哪個模組可以引用哪個模組。這樣 agent 就無法跟它唱反調:CI 會攔住。他也說了局限。其餘那些,目前還沒有好辦法在審查之前抓住。
這個分法很有用。模組之間的引用邊界可以靠 lint 檢查。你為什麼否決了某個方案,通常檢查不了。程式碼審查仍然可能發現矛盾,但那是在事情做完之後。下一次 session 在動手之前,就需要看到當前的決策,以及理由。
在 Amazon 擔任工程經理的 Antonio Torres 寫到,他們團隊先是在 repo 裡放引導檔案,比如 architecture.md、security.md、testing.md,也在轉向規格驅動開發,把規格放進 repo。在他的團隊裡,他要求每位工程師打開會議摘要,這樣討論過的內容會留下書面紀錄。這是補上口頭決策的一個具體辦法。一場會如果什麼都不留下,下一個 agent 就看不見。
這些都是公開貼文,不是調查,也沒有統計返工花了多少時間。但幾邊說的是同一類失敗:決策已經做了,下一次 session 卻沒見到;或者寫下來了,後來過時了;或者只有能被檢查的那部分,能在審查前被執行。
給下一次 session 一份當前的答案,再加上一條軌跡
可以這樣拆:
- 把決策放在下一次 session 真正會讀到的地方。 放在 repo 裡,跟著專案走,而不只留在聊天或會議裡。讓 agent 開始工作前先讀,決策敲定後再追加進去。
- 要寫原因,也要寫被排除的方案,而不只寫選擇。 後來的讀者,無論是人或 agent,都需要這些,才能判斷這個決策現在是否還成立。
- 口頭決策要在進入 agent 之前記下來。 如果是在會議上定的,就寫進同一份日誌。一份短的指令檔案裝不下每一句口頭決定,也不該去裝。
- 不要悄悄改已經接受的紀錄。 決策變了,就另寫一份,把舊的標為被取代,並把兩份連起來。當前的答案可以整段重寫。你們是怎麼走到這一步的,這條軌跡只增不改。
- 能被檢查的約束,變成 lint 或 CI。 其餘的,作為當前的答案,留給下一個 agent 去讀。審查仍然要抓住 lint 看不見的東西。這很正常。
- 留意過時。 共享的架構說明一旦過時,agent 還是會按它行事,並往錯誤的方向走。
比較好用的做法是:一份當前的答案,真相變了就可以整段重寫;再加上一條只增不改的軌跡,記錄你們是怎麼走到這一步的。下一次 session 該載入的,是當前的答案。撤銷、會議紀錄、被排除的方案,都屬於這條軌跡。
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、換一套工具就已經能看見,那就說明它在起作用。
Footnotes
-
Microsoft,Maintain an architecture decision record (ADR),Azure Well-Architected Framework。 ↩