04 · 為什麼 AGENTS.md 能改變 Codex 行為

AGENTS.md 能改變 Codex 行為，是因為它把“每次都要重複交代的話”變成了任務開始前就會進入上下文的專案規則。

它本質上是介面

flowchart LR
    Repo["專案事實"] --> Agents["AGENTS.md"]
    Team["團隊約束"] --> Agents
    Agents --> Codex["Codex 行為"]
    Codex --> Work["讀檔案 / 改程式碼 / 跑驗證"]

README 主要解釋專案給人看。AGENTS.md 主要約束 Agent 怎麼幹活。兩者互補，不互相替代。

沒有專案規則時，Codex 只能猜包管理器、目錄職責、測試命令和禁止事項。有了 AGENTS.md，它能先知道專案真實約定，再開始做事。

發現順序

Codex 啟動時會構建 instruction chain。官方規則可以理解成三層：

1. Global scope：Codex home 下的 AGENTS.override.md 或 AGENTS.md。
2. Project scope：從專案根一路到當前目錄，逐層讀取 AGENTS.override.md、AGENTS.md 或配置裡的 fallback 檔名。
3. Merge order：越靠近當前工作目錄的規則越晚進入上下文，因此更能覆蓋上層規則。

這意味著：

• 全域性檔案適合個人穩定習慣。
• 根目錄檔案適合全倉共同規則。
• 子目錄檔案適合模組規則。
• override 檔案適合臨時強覆蓋，但不能濫用。

什麼該寫進去

適合寫：

• 專案用途。
• 技術堆疊。
• 包管理器。
• 目錄職責。
• 啟動、測試、構建、lint 命令。
• 禁止事項。
• 受保護路徑。
• 驗收要求。

不適合寫：

• 本次任務細節。
• 臨時想法。
• 長篇背景。
• 金鑰、賬號、私有 token。
• 沒穩定下來的個人偏好。
• 與現有規則衝突的模板。

如果你第二次對 Codex 糾正同一個問題，這就是寫進規則的訊號。

三層內容

第一層是事實：專案用什麼技術堆疊、哪個包管理器、哪些目錄做什麼、哪些命令能驗證。

第二層是約束：哪些檔案不要碰，哪些操作不能預設做，哪些高風險邏輯必須先確認。

第三層是驗收：改完要跑什麼檢查，無法驗證時要怎麼說明，最終交付應該包含哪些證據。

只有事實，沒有約束，就是說明書。只有約束，沒有事實，就是口號。沒有驗收，就無法判斷完成。

新手第一次怎麼寫

不要追求完整。先寫六塊：

• 專案概況：一句話說明專案做什麼。
• 目錄職責：列關鍵目錄，不要逐檔案註釋。
• 開發命令：只列啟動、測試、構建、lint。
• 編碼規則：寫具體可執行的約定。
• 禁止事項：寫不能碰的路徑、命令和依賴。
• 驗收要求：寫不同改動型別怎麼檢查。

寫法要具體。“程式碼要優雅”沒有用，因為 Codex 無法驗證。“修改 API handler 後執行某個測試命令”有用，因為它能執行。

怎麼維護

AGENTS.md 不是一次寫完的文件。它應該隨著專案和團隊實踐迭代。

每次 Codex 犯錯後，先判斷是任務沒寫清，還是專案規則缺失。只有會反覆出現的問題，才沉澱到 AGENTS.md。

團隊專案裡，AGENTS.md 應該像程式碼一樣走 review。它改變的是所有 Agent 進入專案後的行為，不能隨手改。

如果檔案越來越長，先刪除低價值說明，再把區域性規則拆到更靠近對應目錄的位置。

新手常見坑

• 把 README 複製進去：人類介紹太長，Agent 規則不夠清楚。
• 寫一堆抽象要求：無法驗證，無法穩定執行。
• 把任務模板塞進去：每次任務不同，應該寫 prompt。
• 把金鑰、賬號、私有 URL 寫進去。
• 規則互相沖突：根目錄說用 pnpm，子目錄又讓用 npm。
• 沒有驗收要求：Codex 只會說“完成了”。

怎麼驗收

讓 Codex 只讀總結當前載入到的規則。它應該能複述專案用途、命令、禁止事項和驗收要求。

給一個小任務，看它是否先讀相關檔案、是否只改允許範圍、是否按規則跑驗證。

檢查最終回覆是否包含改動檔案、驗證結果、未驗證項和剩餘風險。

如果這些沒有發生，優先改 AGENTS.md 的具體性，而不是繼續堆更多提示詞。

官方資料

• AGENTS.md
• Rules
• Project instructions discovery