AGENTS.md 自定义指令

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

Codex 在执行任何工作之前会读取 AGENTS.md 文件。通过将全局指导与项目特定的覆盖指令进行层级组合，无论打开哪个仓库，你都可以让每次任务以一致的预期启动。

Codex 如何发现指导文件

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

1. 全局范围： 在你的 Codex 主目录中（默认为 ~/.codex，除非你设置了 CODEX_HOME），Codex 会首先读取 AGENTS.override.md（如果存在）。否则，Codex 读取 AGENTS.md。Codex 在此级别仅使用第一个非空文件。

2. 项目范围： 从项目根目录（通常是 Git 根目录）开始，Codex 向下遍历到你当前的工作目录。如果 Codex 找不到项目根目录，则只检查当前目录。在路径上的每个目录中，它会依次检查 AGENTS.override.md、AGENTS.md，然后是 project_doc_fallback_filenames 中的任何回退文件名。每个目录最多包含一个文件。

3. 合并顺序： Codex 从根目录向下拼接文件，用空行连接。越靠近当前目录的文件越靠后出现在组合提示中，因此会覆盖更早的指导。

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

创建全局指导

在你的 Codex 主目录中创建持久化的默认设置，让每个仓库都继承你的工作约定。

1. 确保目录存在：

mkdir -p ~/.codex

2. 创建 ~/.codex/AGENTS.md 并添加可复用的偏好设置：

~/.codex/AGENTS.md

## 工作约定

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

3. 在任何地方运行 Codex 确认文件已加载：

codex --ask-for-approval never "总结当前指令。"

预期结果：Codex 在提出工作建议之前会引用 ~/.codex/AGENTS.md 中的条目。

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

分层项目指令

仓库级别的文件让 Codex 了解项目规范，同时仍然继承你的全局默认设置。

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

AGENTS.md

## 仓库期望

- 在发起 Pull Request 之前运行 `npm run lint`。
- 当修改行为时，在 `docs/` 中记录公共工具函数。

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

services/payments/AGENTS.override.md

## 支付服务规则

- 使用 `make test-payments` 而不是 `npm test`。
- 不得在未通知安全频道的情况下轮换 API 密钥。

3. 从 payments 目录启动 Codex：

codex --cd services/payments --ask-for-approval never "列出你加载的指令来源。"

预期结果：Codex 首先报告全局文件，其次是仓库根目录的 AGENTS.md，最后是 payments 覆盖文件。

Codex 到达当前目录后就会停止搜索，因此请将覆盖文件放置在尽可能靠近专项工作的位置。

以下是一个添加了全局文件和 payments 特定覆盖后的示例仓库结构：

AGENTS.md               ← 仓库期望
services/
  payments/
    AGENTS.md           ← 因存在覆盖文件而被忽略
    AGENTS.override.md  ← 支付服务规则
    README.md
  search/
    AGENTS.md
    ...

自定义回退文件名

如果你的仓库已经使用了不同的文件名（例如 TEAM_GUIDE.md），可以将其添加到回退列表中，使 Codex 将其视为指令文件。

1. 编辑你的 Codex 配置：

~/.codex/config.toml

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

2. 重启 Codex 或运行新命令，使更新后的配置生效。

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

有了回退列表后，Codex 会将替代文件视为指令：

TEAM_GUIDE.md           ← 通过回退列表检测到
.agents.md              ← 根目录中的回退文件
support/
  AGENTS.override.md    ← 覆盖回退指导
  playbooks/
    ...

当你需要不同的配置文件时（例如项目特定的自动化用户），设置 CODEX_HOME 环境变量：

CODEX_HOME=$(pwd)/.codex codex exec "列出活动指令来源"

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

验证你的设置

• 从仓库根目录运行 codex --ask-for-approval never "总结当前指令。"。Codex 应按优先级顺序回显来自全局和项目文件的指导。
• 使用 codex --cd subdir --ask-for-approval never "显示当前活跃的指令文件。" 确认嵌套覆盖替换了更广泛的规则。
• 如果需要在会话后审计 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 指向与你编辑的不同的主目录。

下一步

• 访问官方 AGENTS.md 网站了解更多信息。
• 查看 提示 Codex 了解与持久化指导配合良好的对话模式。