Codex 怎麼讀 AGENTS.md：全局和項目的讀取順序、override 文件、32 KiB 上限，以及沒生效怎麼排查

本文根據 Codex 官方文檔《Custom instructions with AGENTS.md》和高級配置整理，資料核對於 2026-10-28。只講 Codex 的讀取規則；其他工具怎麼讀規則文件，見站內跨工具文章。配圖為本站整理的示意圖，不是軟件截圖。

適用於誰

• 寫了 AGENTS.md，但不確定 Codex 有沒有讀、讀的是哪個的人；
• 一個倉庫裏有多個子項目，想給不同目錄設不同規則的人；
• 規則很長，擔心被截斷的人。

結論先說

1. Codex 在開始工作前會讀 AGENTS.md。 它在啟動時建一條指令鏈，每次運行建一次（命令行裏通常是每次啟動會話建一次）。
2. 讀取順序：先是全局，在 Codex 主目錄（預設 ~/.codex，設了 CODEX_HOME 就用那個）裏，有 AGENTS.override.md 就讀它，沒有才讀 AGENTS.md，只用第一個非空的；再是項目，從項目根（通常是 Git 根）逐級走到當前目錄，每個目錄依次找 AGENTS.override.md、AGENTS.md、project_doc_fallback_filenames 裏的備用文件名，每個目錄最多包含一個。
3. 合併方式：從根往下拼接，用空行隔開；離當前目錄越近的越靠後，所以優先級越高。
4. 大小上限：Codex 跳過空文件，合併大小到 project_doc_max_bytes（預設 32 KiB）就停止添加，需要時調大，或把指令拆到嵌套目錄。
5. 確認讀了什麼：官方給的辦法是用命令讓 Codex 列出它加載的指令來源。

圖：本站根據 Codex 官方文檔：AGENTS.md 整理的示意圖

一、官方的寫法示例

全局（~/.codex/AGENTS.md），官方示例：

md
# ~/.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.

項目根的 AGENTS.md 寫倉庫的基本規範，比如提交 PR 前運行 npm run lint；子目錄需要不同規則時，放一個 AGENTS.override.md，例如 services/payments/AGENTS.override.md 裏寫 make test-payments 代替 npm test。

驗證，官方給的命令：

shell
codex --cd services/payments --ask-for-approval never "List the instruction sources you loaded."

官方說預期結果是 Codex 先報告全局文件，再是倉庫根的 AGENTS.md，最後是 payments 的 override。Codex 走到你當前目錄就停止搜尋，所以特殊規則要放在離相關工作最近的位置。

二、沒生效，逐項排查

圖：本站根據 Codex 官方文檔：AGENTS.md 整理的示意圖

• 改了文件沒變化：指令鏈每次運行只建一次，重啟會話再試；
• 規則被別的覆蓋了：離當前目錄近的在後面，優先級更高，檢查更深層目錄裏有沒有同名或 override 文件；
• 後面的內容好像沒讀到：合併大小預設 32 KiB，到上限就停，把規則精簡、調大 project_doc_max_bytes 或拆到嵌套目錄；
• 全局文件沒生效：同目錄下有 AGENTS.override.md 時只讀它，要恢復就刪掉 override；
• 文件是空的：Codex 會跳過空文件；
• 工作目錄不對：從項目根逐級走到你啟動 Codex 的目錄，在別的目錄啟動會讀到不同的鏈。

三、生成和維護

在命令行裏用 /init 可以在當前目錄生成 AGENTS.md 骨架，見 /guides/codex-cli-commands-cheatsheet。官方也建議：項目較大時，用嵌套的 AGENTS.md 控制注入的上下文量，每個文件越大越耗額度，見 /guides/codex-usage-limits。

四、和其他工具的規則文件

AGENTS.md 是多個編碼工具共用的約定，Claude Code 讀的是 CLAUDE.md，各工具的寫法和讀取規則不同，見 /guides/agents-md-cross-tool-guide 和 /guides/claude-md-agents-md。

常見問題

Q：AGENTS.md 裏的規則一定會被遵守嗎？

官方說它是讓 Codex 在每個任務開始前有一致的預期，沒有寫「一定遵守」。重要的約束可以同時寫進測試或檢查裏。

Q：我可以用別的文件名嗎？

官方提供 project_doc_fallback_filenames 配置備用文件名，詳見官方高級配置。

Q：Codex 新手怎麼開始？

見 /guides/codex-first-day-from-signup-to-first-task。

參考資料

• Codex 官方文檔：Custom instructions with AGENTS.md — https://learn.chatgpt.com/docs/agent-configuration/agents-md
• Codex 官方文檔：Advanced Configuration — https://learn.chatgpt.com/docs/config-file/config-advanced
• Codex 官方文檔：Command line options — https://learn.chatgpt.com/docs/developer-commands