可以把Codex当成一位刚加入项目的新同事，而AGENTS.md就是放在项目里的“入职说明”。
它不负责描述某一次需求，而是告诉Codex：这个项目怎么找代码、怎么验证、哪些规则每次都要遵守。
一、哪些场景适合使用AGENTS.md？
适合写入长期、稳定并且会反复用到的内容：
- 项目地图：订单、库存、支付等代码分别放在哪里。
- 常用命令：项目如何启动，修改后要运行哪些测试。
- 修改边界：哪些目录不能动，哪些接口必须保持兼容。
- 业务规则：支付回调必须幂等，金额统一使用分保存。
- 审查要求：检查上下游、异常路径、配置和数据兼容性。
商城案例
团队每次都要提醒Codex“支付回调可能重复到达，不能重复记账”。与其在每个任务里重复说明，不如把它写进支付服务的
AGENTS.md。
下面三类内容要分开放：
| 内容 | 放在哪里 |
|---|---|
| 本次需求的临时要求 | 当前提示词 |
| 项目长期规则 | AGENTS.md |
| 一套需要重复执行的步骤 | Skill |
二、AGENTS.md放在哪里？
最常见的配置有三层：
| 使用范围 | 文件位置 | 适合内容 |
|---|---|---|
| 所有项目 | ~/.codex/AGENTS.md |
个人表达习惯、通用检查要求 |
| 当前项目 | 项目根目录的AGENTS.md |
项目结构、命令、公共规则 |
| 某个模块 | 模块目录下的AGENTS.md |
只对该模块生效的规则 |
例如：
shop/
├── AGENTS.md
└── services/
├── order/
└── payment/
└── AGENTS.md判断使用哪一层规则，可以记成一句话：处理哪个目录或文件，就近匹配离它最近的AGENTS.md。
例如，处理order目录时，因为里面没有单独的AGENTS.md，所以使用项目根目录规则；处理payment目录时，则会在项目规则的基础上加载支付服务规则。上层规则仍然有效，只有内容冲突时，才以距离当前目录或文件更近、粒度更细的规则为准。
同一目录还可以使用AGENTS.override.md临时覆盖普通规则。没有冲突时优先使用AGENTS.md，需要明确替换旧规则时再用override。
注意：新规则不会自动同步到旧任务
新建或修改
AGENTS.md后，新任务会读取最新内容；已经打开的旧任务仍然使用启动时读取到的规则。需要继续旧任务时，可以明确发送“重新读取当前项目的AGENTS.md，并按最新规则继续”；对规则准确性要求较高时，直接新建任务最可靠。AGENTS.override.md也遵循相同的加载方式。
三、怎么配置？
1、个人通用规则
在Codex配置目录创建：
~/.codex/AGENTS.md可以放这些内容：
# 个人协作习惯
- 默认使用中文回答。
- 修改前先阅读相关代码，不猜测项目结构。
- 完成后说明改动文件、验证结果和剩余风险。
- 未经确认，不新增生产依赖。2、项目公共规则
在Git仓库根目录创建AGENTS.md，并提交到仓库，让团队成员共用。
3、模块补充规则
某个服务有特殊要求时，在该服务目录增加一份更具体的AGENTS.md，不要把所有细节都堆在根文件里。
4、使用其他文件名
标准文件名最省事。如果项目已经有TEAM_GUIDE.md，可以在~/.codex/config.toml中配置备用名称：
project_doc_fallback_filenames = ["TEAM_GUIDE.md"]配置后需要重新启动Codex。
四、怎样写效果最好？
1、一条规则只说一件事
不推荐：
修改代码时注意质量、安全和性能。推荐：
修改支付回调时，必须检查重复回调、并发回调和事务失败后的重试。2、写清动作和验证方式
不推荐：
改完记得测试。推荐：
修改订单状态流转后，运行 `make test-order`，并覆盖创建、取消、支付和退款场景。3、说明例外情况
线上环境必须开启支付回调验签；测试环境使用模拟回调，不要求配置线上证书。有例外却不写清楚，Codex很容易把测试环境也当成线上问题。
实际案例：同一个问题被反复误报
某项安全配置只要求线上环境开启，测试环境使用模拟服务。团队没有记录这个差异时，每次审查都会把测试配置当成风险；写入对应服务的
AGENTS.md后，Codex只检查线上配置，并在结论中保留环境说明。
4、规则放在离代码最近的位置
只有支付服务需要遵守的规则，就放到services/payment/AGENTS.md，不要让商品、搜索等无关模块也背着这份规则。
实际案例：不同服务使用不同测试命令
项目根目录要求改动后运行
make test，支付服务因为依赖模拟网关，需要运行make test-payment。把第二条写在支付目录后，Codex处理支付代码时会自动采用更具体的命令。
5、把“建议”改成可判断的标准
# 不够明确
- 尽量不要修改公共接口。
# 更容易执行
- 未经需求明确允许，不修改公共接口的字段名、类型和错误码。五、哪些内容不推荐写？
- 一次性需求：例如“本周活动券打八折”，应留在当前任务中。
- 大段背景资料：只写入口和关键结论，详细文档使用链接指向。
- 模糊口号：例如“代码要优雅”“注意性能”，Codex不知道如何判断。
- 密码和密钥：任何令牌、账号、证书都不应写进仓库。
- 可以自动检查的格式规则：格式化、静态检查等应交给脚本或CI真正拦截。
- 互相冲突的要求：一处要求“必须重构”，另一处要求“禁止重构”，只会增加误解。
- 过多实现细节：规则应说明目标和边界，不要把每个需求的实现方案提前写死。
一个简单判断方法是：三个月后这条规则仍然成立吗？ 如果不会，通常不适合写进AGENTS.md。
实际案例：提醒不等于拦截
AGENTS.md可以提醒“金额不能使用浮点数”，但无法保证每次都不出错。团队后来又增加静态检查和测试，让错误直接导致CI失败；前者告诉Codex规则，后者负责真正把关。
六、可直接使用的项目模板
# 项目协作规则
## 项目地图
- `services/order`：订单创建、状态流转和取消。
- `services/inventory`：库存锁定、释放和补偿。
- `services/payment`：支付下单、回调和退款。
- `docs/api`：接口协议和错误码说明。
## 常用命令
- 安装依赖：`make install`
- 运行全部测试：`make test`
- 运行订单测试：`make test-order`
- 启动本地环境：`make dev`
## 修改规则
- 不修改与当前需求无关的文件。
- 未经确认，不新增生产依赖或修改公共接口。
- 金额统一使用整数分，不使用浮点数。
- 新增订单状态时，检查调用方、消息消费者和历史数据兼容性。
- 支付、退款和库存操作必须考虑幂等与重试。
## 验证要求
- 修改后运行与改动范围对应的测试。
- 无法运行测试时，说明原因和未验证范围。
- 完成后汇总改动点、测试结果和剩余风险。
## Code Review Rules
- 优先报告确定的Bug，再报告潜在风险和优化建议。
- 检查diff之外的调用方、配置、数据和异常路径。
- 不把测试环境缺少线上专用配置当成线上风险。如果支付服务还有特殊规则，可以再创建：
# services/payment/AGENTS.md
- 支付回调可能重复或并发到达，所有处理必须幂等。
- 重复回调应返回成功，避免支付平台持续重试。
- 线上必须验签；测试环境使用模拟回调，可以不配置线上证书。
- 修改后运行 `make test-payment`。七、怎么确认配置已经生效？
新建任务后可以直接问：
请列出当前任务读取到的项目规则，并说明它们来自哪些AGENTS.md文件。如果没有生效，依次检查：
- 是否从正确的项目目录启动Codex。
- 文件名是否为
AGENTS.md或AGENTS.override.md。 - 文件是否为空。
- 上层目录是否存在意外的
AGENTS.override.md。 - 修改文件后是否重新打开了任务。
八、总结
把AGENTS.md当成项目的长期说明书即可：只记录稳定、具体、能执行的规则，并把规则放到离相关代码最近的位置。
如果一段内容描述的是“每次遇到某类任务要按哪些步骤完成”，它更适合做成Skill，而不是继续塞进AGENTS.md。