Codex AGENTS.md：放在哪裡、依什麼順序載入、該寫什麼

Codex 在哪裡尋找 AGENTS.md，依載入順序

Codex 在啟動時建立一次指令鏈（在終端機介面中，每個工作階段一次）。檔案依這張表由上而下串接，所以離工作目錄越近的指令越後面，優先權越高。

如何為 Codex 設定 AGENTS.md

1. 建立全域預設

   執行 mkdir -p ~/.codex，在 ~/.codex/AGENTS.md 裡寫下你希望在每個儲存庫都生效的偏好。請 Codex 摘要它的指令，確認已經載入。

   # ~/.codex/AGENTS.md
   
   ## Working agreements
   
   - Always run `npm test` after modifying JavaScript files.
   - Prefer `pnpm` when installing dependencies.
   - Ask for confirmation before adding new production dependencies.

2. 加入專案檔案，團隊規則不同的地方用覆寫檔

   在儲存庫根目錄放一個 AGENTS.md，寫共用的設定。在規則不同的資料夾裡加入 AGENTS.override.md：它會取代該資料夾的 AGENTS.md，Codex 之後就不再讀那個檔案。

   # AGENTS.md (repository root)
   
   ## Repository expectations
   
   - Run `npm run lint` before opening a pull request.
   - Document public utilities in `docs/` when you change behavior.
   
   # services/payments/AGENTS.override.md
   
   ## Payments service rules
   
   - Use `make test-payments` instead of `npm test`.
   - Never rotate API keys without notifying the security channel.

3. 確認載入了哪些檔案

   在你關心的資料夾裡啟動 Codex，例如 codex --cd services/payments，請它列出已載入的指令來源。它應該依序列出全域檔案、根目錄檔案和該資料夾的檔案。

4. 沿用現有檔名，或提高上限

   如果儲存庫已經把指令寫在別的檔案裡，把它加到 ~/.codex/config.toml 的 project_doc_fallback_filenames 中。合併後的大小達到 project_doc_max_bytes（預設 32 KiB）時，Codex 就不再加入檔案。

   # ~/.codex/config.toml
   project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md"]
   project_doc_max_bytes = 65536

5. 為 Codex 程式碼審查加入規則

   要讓 GitHub 上的 @codex review 套用規則，就在離相關程式碼最近的 AGENTS.md 裡加一個 ## Code Review Rules 區段。寫明要指出什麼問題以及安全的替代做法；格式和 lint 交給 CI。

   ## Code Review Rules
   
   ### Experiment cohorts
   
   - Do not filter treatment comparisons on post-exposure behavior.
     Safe path: build cohorts from assignment or exposure.

來源：Codex 文件，Custom instructions with AGENTS.md

AGENTS.md 最佳做法

• 只寫 Codex 自己弄不清楚的：準確的建置、測試和 lint 指令（包括如何只跑一個測試）、程式碼庫裡的坑，以及沒有寫在任何地方的決定。
• 把最具體的規則放在離程式碼最近的地方：services/payments/ 裡的巢狀 AGENTS.md，勝過根目錄長檔案裡的一節付款說明。
• 注意 32 KiB 的預算：檔案從根目錄往下依序加入，超出的部分會被截掉，所以把長檔案拆成巢狀檔案，或提高 project_doc_max_bytes。
• 暫時的調整用 AGENTS.override.md，全域或單一資料夾都可以，刪掉它就恢復原狀。
• 空的 AGENTS.md 會被略過，該目錄會繼續尋找下一個檔名。
• 為自動化使用者另外設定 CODEX_HOME，這樣他們的全域指令不會和你的混在一起。

Codex 與 Claude Code 等工具中的 AGENTS.md 比較

AGENTS.md 是許多代理都會讀取的開放格式，所以最適合放你想共用的指令。Claude Code 有自己的檔案 CLAUDE.md，詳見 CLAUDE.md 指南。

AGENTS.md 告訴 Codex 怎麼做，Crewmark 告訴它下一步做什麼。

好的 AGENTS.md 能讓每個 Codex 工作階段一開始就掌握狀況，但工作階段仍然要等你的提示。Crewmark 把 Codex、Claude Code、DeepSeek Harness 或 OpenCode 工作階段變成有職位、目標和工作時間的 AI 員工，並依心跳喚醒它，從看板上接手下一個 issue。

1. 把 AGENTS.md 留在儲存庫裡

   員工的 Codex 工作階段會像你的一樣讀取它，慣例和測試指令都會一併帶上。

2. 讓心跳啟動工作

   在工作時間內，員工每 15、30 或 60 分鐘在同一個對話中醒來一次；參見如何讓 Codex 主動工作。

3. 在一個看板上混用代理

   一份 AGENTS.md 可以同時服務 Codex 和 Claude Code 員工；兩者的比較請見 Claude Code 與 Codex 比較。

Codex AGENTS.md 常見問題