使用 `AGENTS.md` 编写自定义指令

官方原文： Custom instructions with AGENTS.md
译文同步： 2026-07-22

Codex 在开始工作前会读取 AGENTS.md 文件。通过叠加全局规则和项目专用覆盖，无论打开哪个仓库，每次任务都可以从一致的预期开始。

Codex 如何发现指令

Codex 启动时会构建一条指令链；每次运行构建一次，在 TUI 中通常对应每次启动的会话。发现顺序和优先级如下：

全局范围： 在 Codex 主目录中查找（默认为 ~/.codex，除非设置了 CODEX_HOME）。如果存在 AGENTS.override.md，读取它；否则读取 AGENTS.md。这一层只使用第一个非空文件。
项目范围： 从项目根目录（通常是 Git 根目录）开始，逐层走到当前工作目录。找不到项目根目录时，只检查当前目录。在沿途的每个目录中，依次检查 AGENTS.override.md、AGENTS.md，以及 project_doc_fallback_filenames 中配置的后备名称。每个目录最多包含一个文件。
合并顺序： Codex 从根目录向下拼接这些文件，并用空行分隔。越接近当前目录的规则出现在组合提示词的越后面，因此可以覆盖更早的规则。

Codex 会跳过空文件。当合并后的大小达到 project_doc_max_bytes 限制时便停止继续添加；默认限制为 32 KiB。达到上限时，可以提高限制或把指令拆分到嵌套目录。

创建全局指令

在 Codex 主目录中创建持久默认值，让所有仓库继承你的工作约定。

确保目录存在：
bash
```
mkdir -p ~/.codex
```

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

# ~/.codex/AGENTS.md

## 工作约定

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

在任意目录运行 Codex，确认文件已加载：

bash

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

预期结果：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

## 支付服务规则

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

从支付服务目录启动 Codex：

bash

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

预期结果：Codex 先报告全局文件，再报告仓库根目录的 AGENTS.md，最后报告支付服务的覆盖文件。

Codex 到达当前目录后便停止向下搜索，所以应把覆盖规则放在尽可能接近专用代码的位置。

text

repository/
├── AGENTS.md                         # 仓库通用约定
└── services/
    ├── payments/
    │   ├── AGENTS.md                 # 因覆盖文件存在而被忽略
    │   ├── AGENTS.override.md        # 支付服务规则
    │   └── README.md
    └── search/
        └── AGENTS.md

添加代码审查规则

为 Codex 的 GitHub 代码审查添加规则时，在最接近目标代码的 AGENTS.md 中加入 ## Code Review Rules。仓库级检查放在根目录，服务专用检查放在嵌套文件。

## Code Review Rules

### 实验分组

- 不要根据曝光后的行为（包括转化或留存）过滤实验组比较。
  安全做法：根据分配或曝光构建分组，把转化作为结果报告。

规则应简短，明确要标记的行为以及安全做法或例外。格式和 lint 检查应交给 CI。

自定义后备文件名

如果仓库已经使用其他文件名（例如 TEAM_GUIDE.md），可以把它加入后备列表，让 Codex 将其作为指令文件处理。

编辑 Codex 配置：

toml

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

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

此后 Codex 会在每个目录中按以下顺序检查：

AGENTS.override.md
AGENTS.md
TEAM_GUIDE.md
.agents.md

未列入后备列表的名称不会参与指令发现。提高字节限制后，组合指令在截断前可以包含更多内容。

text

repository/
├── TEAM_GUIDE.md                     # 通过后备列表识别
├── .agents.md                         # 根目录的次级后备文件
└── support/
    ├── AGENTS.override.md             # 覆盖后备规则
    └── playbooks/

如果需要不同的配置档案，例如项目专用的自动化用户，可以设置 CODEX_HOME：

bash

CODEX_HOME=$(pwd)/.codex codex exec "列出当前生效的指令来源"

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

验证设置

在仓库根目录运行 codex --ask-for-approval never "总结当前生效的指令。"，确认 Codex 按优先级复述全局和项目规则；
使用 codex --cd subdir --ask-for-approval never "显示当前生效的指令文件。"，确认嵌套覆盖替代了更宽泛的规则；
如需审计 Codex 加载了哪些指令文件，可以通过 codex -c log_dir=./.codex-log 启用纯文本 TUI 日志，然后检查 ./.codex-log/codex-tui.log；如果已启用会话日志，也可以检查最新的 session-*.jsonl；
指令看起来陈旧时，在目标目录重新启动 Codex。Codex 每次运行、每次 TUI 会话开始时都会重新构建指令链，不需要手动清理缓存。

排查发现问题

没有加载任何内容： 确认当前位于预期仓库，且 codex status 报告的工作区根目录正确；指令文件不能是空文件。
出现了错误的规则： 检查目录树更高层或 Codex 主目录中是否存在 AGENTS.override.md；重命名或删除覆盖文件即可恢复普通文件。
Codex 忽略后备名称： 确认 project_doc_fallback_filenames 中没有拼写错误，然后重新启动 Codex。
指令被截断： 提高 project_doc_max_bytes，或把大型文件拆到嵌套目录中，确保关键规则保留下来。
配置档案混淆： 启动 Codex 前运行 echo $CODEX_HOME。非默认值表示 Codex 使用了与你所编辑目录不同的主目录。

下一步

访问官方 AGENTS.md 网站了解更多信息；
阅读提示词，了解与持久指令配合使用的对话模式；
阅读高级配置，了解项目指令发现的配置项。

使用 AGENTS.md 编写自定义指令 ​

Codex 如何发现指令 ​

创建全局指令 ​

分层设置项目指令 ​

添加代码审查规则 ​

自定义后备文件名 ​

验证设置 ​

排查发现问题 ​

下一步 ​

使用 `AGENTS.md` 编写自定义指令

Codex 如何发现指令

创建全局指令

分层设置项目指令

添加代码审查规则

自定义后备文件名

验证设置

排查发现问题

下一步