AGENTS.md 不是變更日誌

AGENTS.md 會在每次 session 開始時被載入。團隊把 PR 敘述和量測結果不斷追加進去,檔案就只會變長,真正的規則反而被埋住。指令要短,歷史紀錄不該放在這份檔案裡。

·1 分鐘閱讀

公開的開發者 issue 和討論裡,經常會談到怎麼維護 AGENTS.md。本月稍早,我們寫過規則為什麼會過時,也寫過規則檔為什麼不是決策日誌。還有一個常見問題:檔案只會越來越長。

沒有人想要一份更長的指令。大家是在避免這份每次都會被載入的檔案,變成一本日記。

一份只會變長的檔案

AGENTS.md 有用,是因為 agent 一開始 session 就會載入它。也正因為如此,檔案一旦沒有上限,代價就很高:多出來的每一段,明天還要再付一次。

在一份公開 issue裡,作者寫到自己在一個私有的 production repo 裡看到的情況。六份 AGENTS.md,再加上根目錄那一份,一共 9,243 行。根目錄檔案本身有 1,792 行,有一份按區域劃分的檔案有 2,659 行。Agent 開工前會先載入根目錄檔案和這份區域檔案,一次 session 就要讀進 2,000 到 4,000 行指令。一天的 agent 工作裡,又追加了 218 行,多半是已經寫在 PR 描述和 commit message 裡、帶日期的量測紀錄。原因很眼熟:有一項檢查會標記「文件沒有跟著更新」,agent 就追加一段事發經過,卻從來沒有檢查要求刪掉任何一行。

另一份公開 issue裡,有一份 698 行的 AGENTS.md,每次 agent 開工都會被完整載入。大約 500 行是這個專案自己的規則,約 130 行是「如何使用 AI 工具」這類通用建議,約 70 行和其他文件裡已有的內容重複。快取指令、驗證檢查這些真正要緊的規則,被埋在其餘內容裡。這個團隊希望把檔案壓到 350 行以內,重複的部分改成連結。

還有一場討論問得很直接:把變更歷史放在每次 session 都會載入的指令檔裡,到底有什麼價值?說的是 CLAUDE.md。這份檔案已經漲到 47,000 個字元,每次 session、每個專案 agent 都會被注入進去。

情況都一樣。規則檔成了追加「剛剛發生了什麼」最方便的地方。歷史紀錄本身有價值,只是不該放在每次都會被完整載入的那份指令裡。

更長的指令,並不是更好的指令

這已經不只是喜好問題。工具自己已經在限制檔案的體積。

官方 AGENTS.md 網站把這份檔案稱作給 agent 看的 README。建置步驟、測試和慣例放在這裡,才不會把給人看的 README 擠亂。Cursor 的 規則文件 寫得很清楚:每條規則控制在 500 行以內,過長的規則要拆成更集中的檔案,引用其他檔案,不要把內容複製進來。這樣,每次都會載入的文字才能保持簡短,也不會隨著程式碼改動而過時。OpenAI 在 Codex 的 AGENTS.md 自訂指令 裡寫得更具體。Codex 會從專案根目錄一路拼接到目前工作目錄下的 AGENTS.md,合計大小一到 project_doc_max_bytes(預設 32 KiB)就停止新增。指令被截斷是文件裡已經寫明的故障。建議的做法是提高這個上限,或把大檔案拆開,好讓關鍵指引還能完整保留。Anthropic 的 Claude Code 文件也說明會讀取 repo 裡的 AGENTS.md,並建議每個指令檔控制在 200 行以內。更長的檔案會佔用更多上下文,遵守程度也會下降。1

就算檔案還裝得進上下文視窗,更長的上下文也不是免費的。2025 年 7 月 14 日,Kelly Hong、Anton Troynikov 和 Jeff Huber 在 Chroma 發布了 Context Rot: How Increasing Input Tokens Impacts LLM Performance。他們評估了 18 個模型,包括 GPT-4.1、Claude 4、Gemini 2.5 和 Qwen3。任務被有意保持簡單,只改變輸入長度,用的是擴充後的 Needle in a Haystack、一組對話式問答(LongMemEval),以及重複單字的抄寫任務。模型並沒有均勻地使用上下文。條件已經盡量簡單,輸入一變長,表現還是越來越不穩定。作者也寫了,這項評估並不能涵蓋所有真實場景,而 agent 任務通常更複雜,長度的影響在實際使用中可能會更明顯。

一份 2,000 行、每次都要載入的指令,並不是更完整的專案記憶。它只是一個更大的乾草堆。當前那條規則,每個 session 都要重新從裡面找出來。

把規則編譯出來,不要把故事追加進去

想追加的衝動很好理解。出了問題,你做了量測,希望下一個 agent 知道。錯在把故事留在了規則該待的位置。

2026 年 11 月的一篇預印本,把另一種做法講得很清楚。Nima Vahdat 和 Pashootan Vaezipoor(Georgian AI Lab)發布了 Decision Context: Persistent Behavioral Learning for AI Agents。他們的系統 forge_dc 會把人工糾正,以及模型自我評估出的工具呼叫失敗,編譯成祈使句式的規則指令,再在這些規則適用的決策點注入,而不是去檢索原始歷史。測試用的是 DC-Bench:71 個場景、9 個行為維度,基於真實執行過的 agent 軌跡,運行在確定性的模擬工具環境中。forge_dc 的遵守率達到 95%,樸素檢索是 55%,每個查詢注入的 token 大約少了十倍。

這些結果來自模擬工具基準,不是 repo 裡的 AGENTS.md。衡量的也是對編譯後規則的遵守程度,不是端到端的軟體品質。但它仍能說明問題:把昨天的敘述倒進每次都會載入的檔案,就是那種樸素檢索。更省、也更可靠的做法,是更新當前的規則,把故事放在可以事後查閱、卻不必每次都注入的地方。

可以這樣分:

  • 讓 AGENTS.md 只承擔當前的指令。 建置、測試、lint 和執行的命令,不要碰的目錄,PR 該怎麼開,以及其他今天對照 repo 就能核實的事實。
  • 如果一次改動產生的量測或事發紀錄已經寫在 PR 或 commit 裡,就不必再追加到 AGENTS.md。 下一個 agent 不需要那份帶日期的流水帳。它需要的是規則;如果已經有檢查來執行這條規則,把檢查留下就行。
  • 如果某一節在 docs/ 裡已經有了,就連過去。 這和 Cursor 的建議一致:引用檔案,不要把內容貼上。指令才能保持簡短,長文件更新時也不會一起腐爛。
  • 檔案變長時,要壓縮或拆分,而不只是追加。 如果「如何使用 AI 工具」這類通用建議已經佔了一百行,它多半不該繼續佔用這個 repo 的指令篇幅。
  • 留意工具實際在用的預算。 根目錄檔案如果已經有數千行,就會撞上 Codex 預設的 32 KiB 上限,還可能把目前目錄裡更具體、巢狀的指引擠出去。

當前的答案,加上一條時間線

歷史仍然需要一個位置。這和決策日誌其實是同一套做法:一份可以整段重寫的當前答案,再加上一條只增不改的軌跡,記錄你們是怎麼走到這一步的。帶日期的量測、後來的撤銷、事發說明,都屬於這條軌跡。下一次 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,以及任何能讀檔案的工具,都可以用。

AGENTS.md 可以保持簡短。大腦負責裝決策,時間線負責裝歷史。下一次 session、換一個工具,都會從當前的理解開始,而不是從一份 2,000 行、記著上週 PR 的日記開始。

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

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

如果你注意到的第一件事是,這份指令仍然讀得下去,而且昨天的量測結果沒有再被貼進去,那它就生效了。

Footnotes

  1. Anthropic,How Claude remembers your project。 ↩

分享到