AGENTS.md 只該留下看不見的坑
最近看到 Addy Osmani 整理 AGENTS.md 研究，裡面有一個數字蠻值得記住。124 個真實 PR 的配對實驗中，開發者維護的 AGENTS.md 讓中位執行時間下降 28.64%，輸出 token 也少了 16.58%。這代表一份寫得好的 context file 確實有用，但重點在「寫得好」，不在檔案越長越完整。
另一組結果就比較讓人警醒了。LLM 自動生成的 context file 讓成功率下降 2 到 3%，成本增加超過 20%；人工撰寫的檔案大約提升 4% 成功率，成本卻最高增加 19%。我自己的判斷是，AGENTS.md 應該只記錄 agent 從 repo 本身推不出來，卻會直接影響執行結果的規則。
例如團隊偏好用 uv，不用 pip；測試一定要用某個 wrapper 執行，直接跑 pytest 會漏掉必要環境；修改 schema 後要先跑哪支 migration 檢查。這些事情光看目錄和既有程式碼不一定猜得到，寫進去很合理。
相反地，專案使用 Python、src 在哪裡、測試放在 tests，通常 agent 讀幾個檔案就能知道。把這些再抄一次，短期看起來很有秩序，長期只會增加搜尋範圍，還可能讓真正重要的限制埋在段落裡。
我會建議把 AGENTS.md 當成失敗紀錄的索引來維護。每次 agent 做錯事，先問三個問題：它是否真的無法從 repo 推斷？錯誤是否會重複發生？修正規則後，是否能用測試、linter 或目錄設計把問題永久消掉？只有第一題和第二題都答得肯定，才新增一條；第三題若有答案，就優先修 codebase。
可以用一個很小的追蹤表驗證，不靠感覺決定內容。記錄規則、觸發的錯誤、近 20 次任務命中幾次，以及最近一次修改日期。某條規則連續 20 次任務都沒有命中，先移到候選刪除區；同一種錯誤出現 3 次，才值得提高優先級。刪除後若錯誤重新出現，再補回去，並寫清楚觸發條件。
假設 agent 每次都把測試指令跑錯，連續出現 3 次，AGENTS.md 可以先寫明唯一入口。若團隊接著補上一個可執行的 make test，並讓 CI 檢查它，這條文字就該在一段時間後刪掉。能被工具強制的規則，留在工具裡比較可靠。
AGENTS.md 的用途其實很窄。它更像一張貼在機房門口的地雷圖，只標出看不見、踩到會出事，而且目前還沒有被程式防住的地方。每季清一次，刪掉已經可推斷或已經被自動化吸收的內容，應該比持續追加段落更有價值。
作者：承翰