Codex 的 AGENTS.md 设置教学文档
1. AGENTS.md 是什么
AGENTS.md 是 Codex 的项目级指令文件，用来在 Codex 开始工作前，提前告诉它：
- 这个项目有哪些固定约定
- 在什么情况下要先询问你
- 应该优先运行哪些命令
- 哪些目录、模块、团队有特殊规则
- 你的个人长期工作偏好是什么
可以把它理解成"给 Codex 的持久化说明书"。
它和一次性的聊天提示词不同，重点在于：
- 它会在 Codex 每次启动时自动读取
- 它支持全局规则 + 项目规则 + 子目录规则的分层叠加
- 越靠近当前工作目录的规则，优先级越高
2. Codex 是如何加载这些指令的
根据 OpenAI 官方文档，Codex 会在开始工作前构建一条"指令链"，加载顺序如下。
2.1 全局作用域
Codex 先看你的 Codex 主目录，默认是：
bash
~/.codex如果你设置了环境变量 CODEX_HOME，那就改为读取该目录。
在这个目录里，Codex 的查找顺序是：
AGENTS.override.mdAGENTS.md
注意：
- 这里只会使用第一个"非空文件"
- 如果
AGENTS.override.md存在且非空，那么AGENTS.md在该层就不会再被读取 - 空文件会被跳过
这意味着：
AGENTS.md适合放长期稳定的个人默认偏好AGENTS.override.md适合放临时性的全局覆盖规则
2.2 项目作用域
然后 Codex 会从"项目根目录"开始，一路向下走到"当前工作目录"。
官方文档说明：
- 项目根通常是 Git root
- 如果找不到项目根，Codex 只检查当前目录
- 在路径上的每一层目录中，最多只会取一个说明文件
每层目录的查找顺序是：
AGENTS.override.mdAGENTS.mdproject_doc_fallback_filenames里配置的备用文件名
举例来说，如果当前工作目录是：
text
repo/services/payments/那么 Codex 会依次检查：
~/.codex/AGENTS.override.md或~/.codex/AGENTS.mdrepo/下的说明文件repo/services/下的说明文件repo/services/payments/下的说明文件
2.3 合并顺序
Codex 不是只取一个文件，而是会把找到的文件按顺序拼接起来：
- 先全局
- 再项目根目录
- 再更深层目录
- 最后到当前目录
拼接时用空行连接。
这就带来一个核心规则：
离当前目录越近的文件，越容易覆盖更早的指导。
原因不是"程序做了复杂的冲突解析"，而是因为这些近处文件被放在组合提示的后面，后面的指令通常会在模型理解上更有覆盖效果。
3. 覆盖规则怎么理解
这是最容易搞混的部分。
3.1 同一目录内
同一目录下如果同时存在：
AGENTS.override.mdAGENTS.md
那么优先使用 AGENTS.override.md，AGENTS.md 会被忽略。
官方文档给了一个很明确的例子：
services/payments/AGENTS.md会因为存在services/payments/AGENTS.override.md而被忽略
所以：
AGENTS.override.md是"本层强制覆盖文件"AGENTS.md是"本层常规说明文件"
3.2 不同目录之间
不同目录不是二选一，而是逐层叠加。
例如：
~/.codex/AGENTS.md定义全局工作习惯- 仓库根目录
AGENTS.md定义这个项目统一规范 services/payments/AGENTS.override.md定义支付模块特殊要求
如果你在 services/payments/ 里启动 Codex，那么三层都会生效，但最近的一层最有主导权。
4. 默认大小限制
官方文档明确写到，Codex 会在拼接这些说明文件时检查总大小。
默认限制是：
text
project_doc_max_bytes = 32 KiB这表示：
- 空文件不会被加载
- 一旦组合后的总字节数达到上限，Codex 就不再继续添加更多说明
如果你的说明很多，建议两种做法：
- 提高
project_doc_max_bytes - 把大文件拆到更接近目标目录的多个说明文件里
实践上，第二种通常更好，因为它更符合"按目录分层"的设计思路。
5. 可以自定义哪些文件名
如果团队已经在使用别的说明文件名，不想改成 AGENTS.md，也可以通过配置让 Codex 识别。
官方给出的配置示例是：
toml
# ~/.codex/config.toml
project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md"]
project_doc_max_bytes = 65536配置后，Codex 在每层目录的查找顺序会变成：
AGENTS.override.mdAGENTS.mdTEAM_GUIDE.md.agents.md
要点：
- 备用文件名只在你显式配置后才会被识别
- 不在列表里的名字，Codex 会忽略
- 修改配置后，需要重启 Codex 或开启新会话
6. CODEX_HOME 的作用
CODEX_HOME 用于切换 Codex 的"主目录配置环境"。
默认情况下，Codex 使用：
bash
~/.codex如果你这样运行：
bash
CODEX_HOME=$(pwd)/.codex codex exec "List active instruction sources"那么 Codex 会改为从当前项目里的 .codex/ 读取全局配置，而不是你的用户主目录。
这个能力适合：
- 为不同项目准备不同的 Codex 工作画像
- 在 CI、自动化机器人、共享开发环境里隔离配置
- 避免个人全局规则污染某些特殊工程
7. 官方推荐的典型配置方式
7.1 全局默认规则
适合写在：
text
~/.codex/AGENTS.md适合放的内容：
- 常用包管理器偏好
- 是否默认跑测试
- 是否允许自动加依赖
- 修改某类文件后要不要做额外检查
- 你喜欢的代码风格或协作方式
官方示例包括：
- 修改 JavaScript 文件后总是运行
npm test - 安装依赖时优先使用
pnpm - 添加新的生产依赖前先征求确认
7.2 仓库根目录规则
适合写在：
text
<repo>/AGENTS.md适合放的内容：
- 仓库统一 lint/test 命令
- 代码提交前的检查要求
- 文档更新规则
- 目录结构说明
- 哪些模块不能轻易改
官方示例包括：
- 提 PR 前运行
npm run lint - 修改公共工具行为时同步更新
docs/
7.3 子目录专项规则
适合写在：
text
<repo>/some/subdir/AGENTS.override.md适合放的内容：
- 某服务的专属测试命令
- 某模块的安全限制
- 某团队的特殊工作流程
- 某目录下的禁止操作
官方示例包括：
- 支付模块不要跑通用
npm test，改跑make test-payments - 不允许在未通知安全团队的情况下轮换 API Key
8. 一套容易落地的写法模板
下面是一套更适合实际项目使用的中文模板。
8.1 全局模板
md
# Global Codex Rules
## Working agreements
- Prefer pnpm for JavaScript package management.
- Run relevant tests after code changes.
- Ask before adding new production dependencies.
- Keep changes minimal and aligned with existing style.
- Do not modify unrelated files.8.2 仓库根目录模板
md
# Repository Instructions
## Setup
- Use `pnpm install`.
- Run `pnpm lint` before finalizing changes.
## Code changes
- Preserve existing architecture and naming conventions.
- Update docs when public behavior changes.
## Safety
- Do not change CI, deployment, or secrets handling unless explicitly requested.8.3 子模块覆盖模板
md
# Payments Service Override
## Testing
- Run `make test-payments` for any change in this directory.
## Safety
- Never modify payment gateway credentials.
- Ask before changing retry logic, timeouts, or idempotency behavior.9. 官方验证方法
文档里给了几种非常实用的验证方式。
9.1 检查当前指令摘要
在仓库根目录运行：
bash
codex --ask-for-approval never "Summarize the current instructions."预期结果：
- Codex 会把当前生效的指令概括出来
- 你能确认全局和项目级规则是否都已加载
9.2 检查某个子目录加载了哪些文件
bash
codex --cd services/payments --ask-for-approval never "List the instruction sources you loaded."预期结果：
- 先看到全局文件
- 再看到仓库根目录的
AGENTS.md - 最后看到
services/payments/AGENTS.override.md
9.3 检查日志
如果你想审计 Codex 到底加载了哪些说明文件，官方建议查看：
~/.codex/log/codex-tui.log- 或最近的
session-*.jsonl日志文件（前提是你启用了会话日志）
这对排查"为什么它没按预期执行"很有帮助。
10. 常见问题与官方排错思路
10.1 为什么我的说明文件完全没生效
优先检查：
- 你是不是在目标仓库里启动 Codex
codex status显示的 workspace root 是否正确- 对应文件是不是空文件
因为官方明确说明：
- 空文件会被忽略
- 找不到项目根时，Codex 可能只看当前目录
10.2 为什么加载了"错误的规则"
优先检查：
- 上层目录是否存在
AGENTS.override.md ~/.codex/下是否存在全局覆盖文件
因为很多"莫名其妙的行为"，其实是被更高层的 override 文件覆盖了。
10.3 为什么备用文件名没有被识别
优先检查：
project_doc_fallback_filenames是否拼写正确- 修改配置后是否重启了 Codex
10.4 为什么规则被截断了
优先检查：
- 是否超过
project_doc_max_bytes
解决方式：
- 调大上限
- 按目录拆分说明文件
10.5 为什么像是读到了另一个人的配置
优先检查：
bash
echo $CODEX_HOME如果不是默认空值或你预期的目录，那说明 Codex 用的是另一套 home 配置。
11. 我对"Codex agent 设置"的实战理解
如果你说的是"怎么把 Codex 调教成一个稳定可控的 agent"，那 AGENTS.md 的核心不是写得多，而是写得准。
建议遵循下面这几个原则。
11.1 写规则，不写废话
好的规则应该是可执行的，例如：
- 修改前端代码后运行
pnpm test:web - 未经确认不要新增依赖
- 修改接口时同步更新
openapi/
不好的规则通常是这种：
- 保持代码整洁
- 尽量小心一点
- 注意工程质量
后者太抽象，模型很难稳定执行。
11.2 全局文件写"长期偏好"
放在 ~/.codex/AGENTS.md 的内容应该尽量长期稳定，例如：
- 偏好的命令工具
- 是否默认跑测试
- 是否先征求确认
- 代码风格偏好
不要把某个仓库的特殊流程写到全局里，否则会污染其他项目。
11.3 仓库根目录写"项目通用规范"
适合写：
- 本仓统一命令
- 文档规范
- 提交流程
- 架构约束
这样做的好处是，新人和 Codex 都能快速进入同一套工作方式。
11.4 子目录写"局部强约束"
越靠近实际工作目录，规则应该越具体。
比如：
backend/payments/强制使用支付测试命令infra/禁止擅自修改部署脚本mobile/指定构建和验证流程
这类规则最适合写成目录内的 AGENTS.override.md。
12. 推荐的一套目录策略
如果你的项目比较大，我建议这样分层：
第 1 层：个人全局
文件：
text
~/.codex/AGENTS.md内容：
- 个人长期工作习惯
第 2 层：仓库根
文件：
text
<repo>/AGENTS.md内容：
- 本仓统一规范
第 3 层：关键子系统
文件：
text
<repo>/apps/web/AGENTS.md
<repo>/services/payments/AGENTS.override.md
<repo>/infra/AGENTS.override.md内容：
- 子系统独立工作方式
- 高风险目录的限制
这套结构既清晰，又便于维护。
13. 一句话总结
AGENTS.md 的本质，是把 Codex 的行为规范前置到"会话开始前"，并通过"全局 -> 仓库 -> 子目录"的层级加载机制，让它在不同项目和不同模块中自动切换到正确的工作模式。
如果你只记住 5 个最重要的点，可以记这几个：
- Codex 会在开始工作前自动读取
AGENTS.md - 同目录下
AGENTS.override.md优先于AGENTS.md - 从项目根到当前目录逐层加载，越近越强
- 可通过
project_doc_fallback_filenames支持自定义文件名 - 可通过
project_doc_max_bytes控制总加载大小
14. 适合直接复制的最小配置示例
md
# AGENTS.md
## Repository rules
- Use `pnpm` for package management.
- Run `pnpm lint` and relevant tests after code changes.
- Ask before adding dependencies or changing CI.
- Update documentation when public APIs or behavior change.
- Keep edits scoped to the task and avoid unrelated refactors.