04 · 為什麼 AGENTS.md 能改變 Codex 行為 · AI 程式設計教學中文版

📖 本篇術語速查表

英文 / 縮寫	中文	一句話解釋
AGENTS.md	—	專案與 Agent 的協作介面檔案，定義約定、命令和邊界。
介面	interface	AGENTS.md 的本質：告訴 Agent 這個專案怎麼協作的約定層。
發現順序	discovery order	Codex 查詢 AGENTS.md 的路徑優先順序。

不想讀完？把下面這段提示詞丟給 AI 幫你跑完——幫你為專案起草一份 AGENTS.md（專案與 Codex 的協作介面）。

你是 AGENTS.md 起草顧問，幫我為專案寫一份讓 Codex 更穩定的 AGENTS.md。

【角色】
你理解 AGENTS.md 本質是專案和 Agent 的協作介面，知道它的發現順序和三層內容（專案約定 / 命令 / 邊界），能幫新手從零寫出可維護的版本。

【輸入】
- 專案型別和技術堆疊：___
- 關鍵命令（構建 / 測試 / 啟動 / 檢查）：___
- 必須遵守的約定（程式碼風格 / 目錄規則 / 禁改區）：___
- 哪些操作必須人工確認：___

【工作流程】
1. 按三層內容組織：專案背景與約定、常用命令、行為邊界
2. 把關鍵命令寫成 Codex 可直接執行的形式
3. 標出禁改區和須人工確認的高風險操作
4. 給一個精簡、可維護的初版，不堆無用內容

【輸出規範】
▌一、AGENTS.md 初稿（含專案約定 / 命令 / 邊界三層）
▌二、放在哪個路徑（按發現順序）
▌三、哪些該寫、哪些不該寫進去
▌四、後續怎麼維護（什麼時候更新）

【硬約束】
- 初稿要精簡可維護，不堆砌用不到的內容
- 命令必須真實可執行，不編造專案裡沒有的命令
- 禁改區和高風險操作必須明確寫出
- 不替我假設技術堆疊，資訊不全先問我

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

下個月仍然有效的規則寫進 AGENTS.md；只對這次任務有效的細節寫進 prompt。

AGENTS.md

官方說明如何發現、合併和使用 AGENTS.md。

Rules

專案規則頁講全域、專案、巢狀和排障。

Context engineering

AGENTS.md 是長期上下文，不是一次性任務說明。

它本質上是介面

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

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

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

發現順序

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

Global scope：Codex home 下的 AGENTS.override.md 或 AGENTS.md。
Project scope：從專案根一路到目前目錄，逐層讀取 AGENTS.override.md、AGENTS.md 或設定裡的 fallback 檔名。
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 的具體性，而不是繼續堆更多提示詞。

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