本文为非官方中文翻译，内容以 OpenAI 官方英文文档为准。
官方来源：https://developers.openai.com/codex/guides/agents-md

使用 AGENTS.md 的自定义指令

为你的项目向 Codex 提供额外指令和上下文

Codex 在执行任何工作之前都会读取 AGENTS.md 文件。通过将全局指导与项目特定覆盖相结合，无论你打开哪个仓库，都可以在每个任务开始时拥有一致的预期。

Codex 如何发现指导内容

Codex 在启动时构建一条指令链（每次运行一次；在 TUI 中，这通常意味着每次启动的会话一次）。发现顺序遵循以下优先级：

全局作用域： 在你的 Codex 主目录中（默认为 ~/.codex，除非你设置了 CODEX_HOME），如果存在 AGENTS.override.md，Codex 会读取它。否则，Codex 会读取 AGENTS.md。在这一层级，Codex 只使用第一个非空文件。
项目作用域： 从项目根目录开始（通常是 Git 根目录），Codex 会一路向下遍历到你当前的工作目录。如果 Codex 找不到项目根目录，它只检查当前目录。沿路径中的每个目录里，它会检查 AGENTS.override.md，然后是 AGENTS.md，再然后是 project_doc_fallback_filenames 中的任何后备名称。每个目录中，Codex 最多包含一个文件。
合并顺序： Codex 按从根到下级目录的顺序拼接文件，并用空行连接。更接近你当前目录的文件会覆盖更早的指导内容，因为它们在合并后的提示中出现得更靠后。

Codex 会跳过空文件，并在合并后的总大小达到 project_doc_max_bytes 定义的限制时停止添加文件（默认 32 KiB）。有关这些参数的详细信息，请参阅项目指令发现。当你达到上限时，可以提高该限制，或将指令拆分到嵌套目录中。

在你的 Codex 主目录中创建持久默认值，这样每个仓库都会继承你的工作约定。

创建包含可复用偏好的 ~/.codex/AGENTS.md：

# ~/.codex/AGENTS.md

## 工作约定

- 修改 JavaScript 文件后始终运行 `npm test`。
- 安装依赖时优先使用 `pnpm`。
- 添加新的生产依赖之前先请求确认。

在任意位置运行 Codex 以确认它会加载该文件：
```
codex --ask-for-approval never "Summarize the current instructions."
```
预期结果：Codex 会在提出工作建议之前引用 ~/.codex/AGENTS.md 中的条目。

当你需要临时的全局覆盖而又不想删除基础文件时，请使用 ~/.codex/AGENTS.override.md。移除该覆盖文件即可恢复共享指导。

仓库级文件能让 Codex 感知项目规范，同时仍然继承你的全局默认值。

在仓库根目录中添加一个涵盖基本设置的 AGENTS.md：

# AGENTS.md

## 仓库要求

- 打开 pull request 之前运行 `npm run lint`。
- 更改行为时，在 `docs/` 中记录公共工具。

当特定团队需要不同规则时，在嵌套目录中添加覆盖。例如，在 services/payments/ 内创建 AGENTS.override.md：

# services/payments/AGENTS.override.md

## Payments 服务规则

- 使用 `make test-payments` 代替 `npm test`。
- 未通知安全频道前，绝不要轮换 API 密钥。

从 payments 目录启动 Codex：
```
codex --cd services/payments --ask-for-approval never "List the instruction sources you loaded."
```
预期结果：Codex 会先报告全局文件，其次是仓库根目录下的 AGENTS.md，最后是 payments 覆盖文件。

Codex 在到达你当前目录后就会停止搜索，因此应将覆盖文件放在尽可能接近专业化工作的地方。

添加全局文件和 payments 专用覆盖后，下面是一个示例仓库：

如果你的仓库已经使用了不同的文件名（例如 TEAM_GUIDE.md），请将其添加到后备列表中，这样 Codex 就会将它视为指令文件。

编辑你的 Codex 配置：

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

现在，Codex 会按以下顺序检查每个目录：AGENTS.override.md、AGENTS.md、TEAM_GUIDE.md、.agents.md。不在此列表中的文件名会在指令发现时被忽略。更大的字节限制允许在截断之前合并更多指导内容。

设置好后备列表后，Codex 会将这些替代文件视为指令：

当你想使用不同的配置档案时，例如项目专用的自动化用户，请设置 CODEX_HOME 环境变量：

CODEX_HOME=$(pwd)/.codex codex exec "List active instruction sources"

预期结果：输出会列出相对于自定义 .codex 目录的文件。

在仓库根目录运行 codex --ask-for-approval never "Summarize the current instructions."。Codex 应按优先级顺序回显来自全局和项目文件的指导。
使用 codex --cd subdir --ask-for-approval never "Show which instruction files are active." 以确认嵌套覆盖会替换更宽泛的规则。
如果你需要审计 Codex 加载了哪些指令文件，请在会话结束后检查 ~/.codex/log/codex-tui.log（如果你启用了会话日志记录，则检查最新的 session-*.jsonl 文件）。
如果指令看起来不是最新的，请在目标目录中重启 Codex。Codex 会在每次运行时（以及每个 TUI 会话开始时）重建指令链，因此无需手动清除缓存。

没有加载任何内容： 确认你位于预期的仓库中，并且 codex status 报告的是你期望的工作区根目录。确保指令文件包含内容；Codex 会忽略空文件。
出现了错误的指导： 查找目录树中更高层级或你的 Codex 主目录下是否存在 AGENTS.override.md。重命名或删除该覆盖文件，以回退到常规文件。
Codex 忽略后备名称： 确认你已将这些名称无拼写错误地列在 project_doc_fallback_filenames 中，然后重启 Codex 以使更新后的配置生效。
指令被截断： 提高 project_doc_max_bytes，或将大文件拆分到嵌套目录中，以保持关键指导内容完整。
配置档案混淆： 在启动 Codex 之前运行 echo $CODEX_HOME。非默认值表示 Codex 指向了一个不同于你编辑过的主目录。