AGENTS.md 不是決策日誌

這一週，MindMux 團隊閱讀了一批公開的開發者討論、issue 和留言，看人們實際上是怎麼維護 AGENTS.md 和 agent 記憶的。這不是一項正式調查，我們也沒有附上無法核驗的數字。下面寫的是這些討論裡反覆出現的模式（不提及具體姓名），再加上兩篇近期論文，以及一套把 AGENTS.md 和決策日誌分開的實用做法。

大家用的詞出奇地一致。人們在說 AGENTS.md 同步、過時的 AGENTS.md、每次開新對話都要重新解釋已經做過的決定，以及需要唯一的真實來源。他們要的不是一份更長的規則檔，而是一個決策能住進去、又不會慢慢腐爛的地方。

Agent 會遵守你忘了更新的那一行

AGENTS.md 之所以有用，是因為 agent 真的會讀。這也正是一行過時內容代價很高的原因。

2026 年 11 月 6 日，Tural Mehtiyev、Biruk Tadesse、Lawrence Arkoh 和 Wesley Assunção（北卡羅來納州立大學）發布了預印本 When Instruction Files Go Stale: Documentation Debt and Hidden Cost in Coding Agents。他們從根目錄含有 AGENTS.md，或在他們測量的部分案例中含有 CLAUDE.md 的活躍開源儲存庫裡，深入研究了三條真實過時指令：一條測試命令、一處程式碼位置，以及一套新增元件的步驟。Agent 在同一條指令的三個版本下修復 22 個維護任務——保持過時、改成正確，或直接刪掉——程式碼和任務保持不變。作者分析了兩個模型（Claude Haiku 5.5 和 Claude Sonnet 5.5）的 732 條軌跡，精確到每一次工具呼叫。

只要這條過時指引和任務相關，agent 就會跟著走，有時儲存庫裡別處已經有正確資訊，也照樣跟著走。在過時的測試命令上，Claude Sonnet 5.5 平均每次要多兩次工具呼叫，比使用更正後的命令多出約三分之一。任務通常還是做完了，測試也過了。它們靠搜尋程式碼庫自己繞了過去。但在全部 732 次執行裡，沒有任何一次去改那份指令檔。把過時的那一行改正，可以消除對已失效路徑的操作；刪掉它，則能阻止其中的大部分。只看任務是否成功，這筆成本就被藏起來了：過時的那一行留在儲存庫裡，等著下一次 session 再次被載入。

這項研究是一次聚焦實驗，作者自己也這樣寫。它用的是同一家廠商的兩個模型、同一套執行環境、三類過時上下文和 22 個任務。這 732 次執行是在重複這幾個案例，而不是對大量彼此獨立的文件債做抽樣。額外耗時被明確測到的，主要是 Sonnet 在過時測試命令上的表現；在其他情況下，作者未能檢測出工具呼叫或 token 上的差異。

這仍然和我們本週在公開討論裡反覆看到的情況對得上。有開發者審查了一份很長的常駐指令檔，發現裡面已經有多處寫錯：runtime 版本過時了，專案早已不用的支付服務商還寫在裡面，還引用了已經不存在的 migrations。Agent 仍然按檔案行事，而不是按程式碼。另有團隊的 AGENTS.md 是從一份更早的、綁定特定工具的檔案用尋找並取代產生的，於是兩套工具讀到的專案說明並不一樣，連模型名稱都寫錯了。還有人眼看著同一套指引的副本在一天之內就漂開了，因為改動只落進了其中一處。有人在好幾個儲存庫之間來回複製同一份 AGENTS.md，然後開始問專案層級覆蓋該怎麼做。真正去測量哪些行還在起作用的團隊，往往會大幅砍短檔案，並問出一個更好的問題：檔案越長，是不是就過時得越快？

一份每次 session 都會被載入的 AGENTS.md，每次 session 都會被遵守——包括那些已經不再正確的行。而且 agent 不會替你修好這份檔案。

AGENTS.md 不是決策日誌

AGENTS.md 有自己的職責：告訴 agent 在這個儲存庫裡該怎麼做事。該跑哪些命令，哪些目錄不要碰，PR 該怎麼開。

這和記住「為什麼選 cookie session 而不是 JWT」、某個支付服務商已經被替換、或者上個月的裁定已經推翻了檔案裡還留著的那條規則，不是同一件事。

這些判斷如果沒有別處可去，就會漏進錯誤的地方。在我們讀到的討論裡，有些長期有效的決定只活在某個模型的記憶裡，於是下一次 session 又把團隊早已拍板的問題重新拋出來。有人準備開始手寫架構決策紀錄，因為儲存庫裡沒有任何地方裝著那個結論。也有團隊承認，沒有書面的決策日誌，同樣的事每週都要重新決定一遍。還有 agent 自己寫下的記憶，和經過人工審閱的 AGENTS.md 互相衝突，於是專案裡出現了兩套「我們相信什麼」，開始打架。

第二篇論文把底層問題講得很清楚。2026 年 11 月 10 日，Yukyeong Lee、Yumin Choi、Jinheon Baek 和 Sung Ju Hwang（KAIST 與 DeepAuto.ai）發布了 Don't Just Trust Your Memory: Evidence-Linked Memory Reduces Memory-Induced Degradation in LLM Agents，並提出了 WikiTrace。他們觀察的是：agent 在沒有記憶時能穩定做對、加上記憶後反而做錯的那些任務。這類失敗裡，有 52% 可以追溯到 agent 遵從的某一條記憶，而且常常是一條錯誤的記憶。經驗是從過往執行裡提煉出來的，交出去時卻沒有附上它來自哪一次軌跡，agent 也就無從核對。把每條經驗連結回它來源的那次執行之後，在五個 agent 基準、八組套件上的平均得分從 87.0（同樣的 insights，但沒有來源）提升到 90.2，這類回退也從 6.5% 降到 4.5%。

這些結果來自模擬文字世界和工具使用環境，而不是儲存庫裡的指令檔，部分失敗原因也由 LLM 評判器標註。即便如此，它仍然是一條有用的警告：一條沒有「為什麼」的規則，只是傳聞。決策日誌既要保存當前的答案，也要保存得出這個答案的證據，包括後來的撤銷。

一份真實來源，跨工具、跨儲存庫

只要不只一個工具在用，同步問題就會變得更糟。

在我們讀到的討論裡，同時使用 Claude Code 和 Codex——有時還有 Pi——的開發者會問，怎樣用一份 AGENTS.md 在不同工具之間攜帶同一套前提，免得換工具時再把專案講一遍。維護許多客戶儲存庫的團隊，正在傷腦筋 AGENTS.md 和其他文件到底該怎麼分工、怎麼保持同步。有的團隊已經在用一個協調儲存庫，只要 clone 一個地方，就能讓 agent 跨專案工作；而最常見的第一句回應往往是：這份檔案很快就會過時。還有人不希望記憶被鎖在某一家廠商的產品裡。他們希望每個 agent 讀到的是同一份紀錄。

整個產業也在朝共享上下文走，原因是一樣的。2026 年 11 月 10 日，Cursor 的文章 Projects is now multiplayer（Aryaman Khandelwal）寫得很直接：在一個對話裡做出的決定，Project 裡的每個 agent 都能讀到。這個方向是對的。過去 agent 的上下文是按人隔離的，但團隊是一起做決定的。這些知識仍然應該屬於專案本身——用任何工具都能讀、能在 PR 裡審查、下個月換了 agent 也還找得到的形式保存下來。

這裡說的是已經做出的決策，如何在跨 session、跨工具時被記住。

怎麼審查 AGENTS.md，以及決策該放在哪裡

開始做這件事，並不需要先上一套新工具。真正有用的分界是：agent 在這個儲存庫裡該怎麼做事，以及專案裡已經決定了什麼。

先審查 AGENTS.md。 打開這份檔案，包括其他儲存庫或子目錄裡的副本。對每一條命令，實際跑一遍，或至少確認路徑還在。對每一個目錄或檔名，檢查它是否仍然存在。對 runtime、版本、服務商和支付提供方，核對儲存庫是否還在用它們。如果同一套指引出現在不止一處，就把它們 diff 一遍：只改了一邊，就已經是漂移。凡是在回答「我們為什麼選這個」或「我們否定了什麼」的內容，都是決策，不是常駐規則——把它們移出去。

讓 AGENTS.md 保持簡短。 它適合放建置、測試、lint 和執行的命令，不要碰的目錄或檔案，PR 該怎麼開，以及其他容易對照儲存庫核實的當前事實。它不該是存放「為什麼」的地方。

把決策寫進日誌。 每條紀錄都需要當前答案、日期、簡短理由，以及狀態——如果後來的決定推翻了更早的決定，還要寫明它取代了什麼。下面是一個示意例子，不是某個真實專案的紀錄：

# Auth strategy

Status: active
Supersedes: JWT for the desktop app (2026-09-02)

Current answer: Cookie-backed sessions in the existing SQLite store.
The app is local-first and has no hosted backend.

- 2026-10-19 — Chose sessions over JWT. There is no server component
  that would justify JWT.
- 2026-09-02 — Evaluated Auth.js and Lucia; deferred. JWT looked like
  the default and did not fit a local-first app.

審查之後，改正或刪除過時的行。在上面那項研究裡，改正過時指令消除了對已失效路徑的操作，刪除它則阻止了其中的大部分。不要等 agent 來修這份檔案。那 732 次執行裡，沒有一次它會去改。

MindMux 做了什麼

MindMux 本身也在做這個領域的產品，所以這裡如實說明今天它實際做了什麼。

MindMux 會從你們已經在和 agent 進行的對話裡——就是那些聊天——整理出背景、決策與約束，寫成一份 Markdown 專案大腦，讓 agent 在開始任務之前透過 MCP 讀到。它的開源、本地對應物 brain.md，是儲存庫裡的一個 brain/ 目錄，外加一個小巧的 CLI（@mindmux/brain-md）。每個頁面都保留一層 compiled_truth——當前的答案——以及一條只增不改的 timeline，記錄你們是怎麼走到這裡的。它原生屬於 git，也不綁死在某個 agent 上：Claude Code、Codex、Cursor，以及任何能讀檔案的工具，都可以用。

AGENTS.md 可以保持簡短。大腦負責裝決策。當結論發生變化，舊的判斷會留在記錄裡。下一次 session、下一個工具，都會從同一份理解開始——而不是從昨天剛剛漂開的那份複製過來的 AGENTS.md 開始。

這是跨 session、跨工具的決策記憶。

如果這正是你遇到的問題：

• MindMux： mindmux.ai
• brain.md： projectbrain.md

如果你注意到的第一件事是，某個決定不用再解釋一遍，或者兩個工具終於讀到了同一份決定，那它就生效了。

參考文獻

• Tural Mehtiyev、Biruk Tadesse、Lawrence Arkoh、Wesley Assunção，When Instruction Files Go Stale: Documentation Debt and Hidden Cost in Coding Agents，arXiv 預印本，2026 年 11 月 6 日。
• Yukyeong Lee、Yumin Choi、Jinheon Baek、Sung Ju Hwang，Don't Just Trust Your Memory: Evidence-Linked Memory Reduces Memory-Induced Degradation in LLM Agents，arXiv 預印本，2026 年 11 月 10 日。
• Aryaman Khandelwal，Cursor Projects is now multiplayer，2026 年 11 月 10 日。