适合谁读：经常让 Codex 修改真实代码库，希望减少重复说明、误用命令和跨模块误改的开发者。核心结论是：把稳定、可检查的项目事实写进
AGENTS.md，把一次性需求留在当前任务里；规则越靠近实际目录越具体，效果通常越可靠。
本文更新：2026 年 7 月 20 日。本文依据当日可访问的 OpenAI Codex 官方文档整理，不涉及套餐、模型或价格。
为什么只靠每次提示词不够
同一个仓库往往有固定的构建方式、测试入口、目录边界和评审要求。如果每次都重新输入，不仅费时，还容易漏掉关键限制。例如一个父目录下面可能放着多个独立 Git 仓库，前端与后端也可能使用完全不同的测试命令。Codex 如果不知道这些事实，就可能在错误目录运行命令，或只验证了局部结果。
AGENTS.md 的作用不是替你写一篇长文档，而是给 Codex 一组会随仓库一起保存的持久指令。官方文档建议保持内容精简，优先记录每次都应遵守的构建与测试命令、评审期望、仓库约定和目录级规则。
Codex 如何找到这些规则
官方说明中，Codex 会在一次运行开始时构建指令链：先读取 Codex 主目录中的全局指令，再从项目根目录沿路径走到当前工作目录，逐层查找指令文件。同一目录里，AGENTS.override.md 的优先级高于 AGENTS.md；越靠近当前工作目录的规则越晚加入，因此可以覆盖更上层的通用要求。
这带来一个实用设计：根目录只放全仓库共识，特殊模块在自己的目录补充规则。例如根目录要求“修改后运行基础测试”，支付模块则明确要求使用该模块专属测试命令。这样无需把所有模块细节塞进一个巨大文件，也不会让前端规则干扰后端任务。
需要注意，Codex 通常只在运行或会话开始时读取一次指令链。刚修改规则后，如果当前任务没有反映新内容，应在目标目录重新开始一次任务，而不是反复清理所谓缓存。
一份可直接改造的模板
可以从下面这个精简版本开始，再按真实项目替换命令：
# Repository guidance
## Scope
- 先确认实际 Git 根目录；父目录可能包含多个独立仓库。
- 只修改当前任务涉及的模块，保留用户已有的未提交改动。
## Commands
- 安装依赖：使用项目锁文件对应的包管理器。
- 单元测试：`npm test`
- 静态检查：`npm run lint`
## Verification
- 修改业务逻辑时补充或更新相关测试。
- 完成后报告执行过的命令、结果和未验证项。
## Safety
- 添加生产依赖前先征求确认。
- 不提交令牌、真实域名、个人路径或本地配置。模板中的命令必须在仓库里真实存在。不要为了显得完整而编造 npm test、make check 或部署脚本；错误的固定指令会比没有指令更糟。可以先查看 package.json、构建文件和 CI 配置，再写入唯一、明确的推荐命令。
用四步把规则写得可执行
1. 先记录“事实”，再记录“偏好”
“后端是 Maven 多模块工程”“测试必须从某个子模块运行”属于项目事实，应写清入口和范围。“代码写得优雅一些”则难以验证，最好改成具体要求，例如“公共接口变更时更新接口文档，并运行契约测试”。
2. 给命令补上触发条件
不要只列一串命令。说明什么改动需要运行哪项验证，以及成本过高时如何处理。例如：“只改文档时不运行完整集成测试；修改数据库迁移时运行迁移校验并报告回滚路径。”这能减少无意义的重型检查，也防止关键测试被漏掉。
3. 把特殊规则放到最近的目录
如果 services/payment/ 与仓库根目录的命令不同，就在该目录增加 AGENTS.md 或临时使用 AGENTS.override.md。后者适合明确覆盖同目录的普通规则，但也更容易让人忘记它的存在，因此应写明用途，并在不再需要时移除。
4. 让 Codex 复述并验证
写完后，从仓库根目录让 Codex 总结当前指令；再切到特殊子目录，要求列出实际生效的指令文件和关键命令。官方文档也给出了类似验证思路。检查重点不是它能否逐字背诵，而是是否识别了正确的项目根、目录覆盖关系和验收步骤。
三个常见误区
第一，把一次性的产品需求写成永久规则。某个需求只适用于当前任务，就应留在任务描述里，否则未来会持续干扰无关工作。
第二，把密钥、账号或内部地址写进文件。AGENTS.md 往往会进入版本库，适合写“从环境变量读取”，不适合保存真实凭据。示例也应使用泛化域名、用户名和路径。
第三，用规则替代权限控制。AGENTS.md 能指导行为，但不是安全边界。高风险命令仍应依靠沙箱、审批、最小权限和可回滚流程约束；重要操作还要在执行前核对准确目标。
最后建议
最好的 AGENTS.md 通常不长，却能回答三个问题：这是哪个仓库或模块、改完应该运行什么、哪些边界绝不能越过。先加入三到五条最常被重复提醒的规则，观察几次真实任务，再把反复出现的纠正固化进去。它不是一次写完的说明书，而是一条持续缩短沟通成本的反馈回路。