AGENTS.md 自定义指令

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

本指南向你展示如何：

• 设置全局默认值
• 添加项目特定指令
• 配置回退文件名

指令链发现

Codex 每次启动时都会构建一个指令链。发现按优先级顺序进行：

1. 全局范围 — Codex 检查你的 Codex 主目录（默认为 ~/.codex，或设置 CODEX_HOME 时的自定义路径）。如果存在 AGENTS.override.md 则优先使用；否则 Codex 读取 AGENTS.md。此级别只使用第一个非空文件。

2. 项目范围 — Codex 从仓库根目录向下遍历到当前工作目录。在每个目录中，它查找 AGENTS.override.md，然后是 AGENTS.md，然后是 project_doc_fallback_filenames 中配置的任何回退名称。每个目录最多包含一个文件。

3. 合并顺序 — 文件从根目录向下连接。后面的文件覆盖前面的指导，因为它们更接近你当前的任务。

Codex 跳过空文件，一旦组合大小达到 project_doc_max_bytes 定义的限制（默认 32 KiB）就停止。当达到上限时，提高限制或将指令分散到嵌套目录中。

设置全局默认值

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

步骤 1：确保目录存在

mkdir -p ~/.codex

步骤 2：创建 AGENTS.md

创建 ~/.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 特定覆盖后的示例仓库：

~/.codex/
└── AGENTS.md                    # 全局默认值

my-project/
├── AGENTS.md                    # 仓库级别指令
├── src/
│   └── ...
└── services/
    └── payments/
        └── AGENTS.override.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 或运行新命令以加载更新的配置。

现在 Codex 按以下顺序检查每个目录：AGENTS.override.md、AGENTS.md、TEAM_GUIDE.md、.agents.md。更大的字节限制允许在截断前有更多组合指导。

有了回退列表，Codex 将备用文件视为指令：

my-project/
├── TEAM_GUIDE.md               # 被识别为指令文件
├── src/
│   └── ...
└── services/
    └── payments/
        └── .agents.md          # 也被识别为指令文件

使用自定义 CODEX_HOME

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

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

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

最佳实践

1. 保持指令简洁 — 避免过长的指令文件，它们会消耗上下文窗口
2. 使用分层结构 — 全局设置通用规则，项目级别设置特定规则
3. 定期审查 — 随着项目演进更新指令
4. 团队协作 — 将项目级 AGENTS.md 提交到版本控制
5. 测试覆盖 — 使用 --ask-for-approval never 快速验证指令加载