AGENTS.md 檔案用來告訴程式設計 Agent 如何在程式碼儲存庫中工作。每次工作階段 都會把它載入上下文，這表示你加入的每一行，都會在每項任務中產生 Token 成本， 也會與使用者真正的要求爭奪 Agent 的注意力。

光是這一點，就足以解釋下面大多數的建議。

只寫無法透過查看儲存庫發現的內容

如果 Agent 能透過查看儲存庫得知某件事，就不要把它寫進檔案。目錄結構、使用的 框架、測試檔案的命名方式——這些都能直接從儲存庫看出來，不需要重複說明。

真正無法直接發現的是意圖與限制：

  • 執行測試的指令，尤其是在指令並不直觀時
  • 程式碼尚未全面遵循的慣例
  • 看起來像錯誤、其實是刻意設計的行為
  • 禁止編輯的目錄，以及禁止編輯的原因

保持簡短，讓人能夠完整讀完

檔案超過大約一百行後，就會開始變成沒人閱讀的文件。埋在第 180 行的指示很難 可靠地改變 Agent 的行為，因為它還得與檔案裡的其餘內容爭奪注意力。

如果你的檔案已經變得很長，更有用的問題不是「如何讓 Agent 遵守這些指示？」， 而是「這些內容中，哪些真正改變過結果？」

明確寫出具體指令

含糊的指引只會產生含糊的行為。比較下面兩種寫法：

Run the tests before committing.

以及：

Run `pnpm test -- --run` before committing. It takes about 40 seconds.
Do not run `pnpm test` without `--run`; it starts watch mode and hangs.

第二種寫法能避免一個具體且反覆發生的問題。第一種寫法只是在表達態度。

解釋原因，而不只是寫規則

附帶原因的規則能應對陌生情況；單純的禁令則做不到。「不要編輯 src/generated/」會讓人在第一次覺得直接修改比較方便時選擇破例。「不要編輯 src/generated/——它會被 pnpm codegen 覆寫，你的修改會消失」則不會。

在檔案不再發揮作用時重新檢視它

把這個檔案視為會隨時間逐漸失效的內容。當 Agent 反覆做出你不想要的行為時， 這反映的是檔案本身的問題，而不只是模型的問題。要不是缺少了某條指示，就是 已有指示正被三百行已經不再重要的內容淹沒。