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 指南以获取实际使用提示。