AGENTS.md 發現

Codex 使用 AGENTS.md 文件在開始協助您之前收集有用的指導。本頁面解釋了這些文件是如何被發現和組合的，所以您可以決定在哪裡放置您的說明。

全局說明（~/.codex）

• Codex 在您的 Codex 主目錄中查找全局指導（通常為 ~/.codex；設置 CODEX_HOME 來更改它）。有關快速概覽，請參閱入門指南中的使用 AGENTS.md 進行內存的部分。
• 如果存在 AGENTS.override.md 文件，它具有優先級。如果不存在，Codex 會回退到 AGENTS.md。
• 只有第一個非空文件被使用。其他文件名，如 instructions.md，除非 Codex 被特別指示使用它們，否則沒有效果。
• Codex 在這裡找到的任何內容都會保持活躍狀態，持續整個會話，Codex 將其與它發現的任何特定於項目的說明結合在一起。

項目說明（按存儲庫）

當您在項目中工作時，Codex 通過收集項目文檔來構建這些全局說明：

• 搜索從存儲庫根目錄開始，繼續到您的當前目錄。如果找不到 Git 根目錄，則僅檢查當前目錄。
• 在該路徑上的每個目錄中，Codex 首先查找 AGENTS.override.md，然後查找 AGENTS.md，然後是您的 Codex 配置中列出的任何備用名稱（參見 project_doc_fallback_filenames）。最多包含每個目錄中的一個文件。
• 文件從根到葉按順序讀取，並用空行連接。跳過空文件，很大的文件在組合大小達到 32 KiB（預設 project_doc_max_bytes 限制）後被截斷。如果您需要更多空間，請在嵌套目錄中分割指導或提高配置中的限制。

它們如何結合在一起

在 Codex 開始工作之前，說明按優先級順序被攝取：來自 ~/.codex 的全局指導首先出現，然後是從存儲庫根目錄到您的當前目錄的每個項目文檔。深層目錄中的指導會覆蓋較早的層，所以最具體的文件控制最終行為。

優先級總結

1. 全局 AGENTS.override.md（如果存在），否則全局 AGENTS.md。
2. 對於從存儲庫根到您的工作目錄的每個目錄：AGENTS.override.md，然後 AGENTS.md，然後是配置的備用名稱。

只有這些文件名被考慮。要使用不同的名稱，請將其添加到 Codex 配置中的備用列表或相應地重命名該文件。

備用文件名

如果您在 Codex 配置中將它們添加到 project_doc_fallback_filenames，Codex 可以查找除兩個預設值之外的其他指令文件名。在搜索路徑的每個目錄中，每個備用都在 AGENTS.override.md 和 AGENTS.md 之後進行檢查。

例如：假設您的配置列出 ["TEAM_GUIDE.md", ".agents.md"]。在每個目錄中，Codex 將按此順序查找：

1. AGENTS.override.md
2. AGENTS.md
3. TEAM_GUIDE.md
4. .agents.md

如果存儲庫根目錄包含 TEAM_GUIDE.md，而 backend/ 目錄包含 AGENTS.override.md，則整體說明將組合根 TEAM_GUIDE.md（因為那裡沒有覆蓋或預設文件）與 backend/AGENTS.override.md 文件（其優先級高於備用名稱）。

您可以在 ~/.codex/config.toml（或另一個配置文件）中配置這些備用，如下所示：

project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md"]

有關更多配置詳細信息，請參閱配置，並重新訪問使用 AGENTS.md 指南以獲取實際使用提示。