每次让 AI 改代码，都要重新说明包管理器、测试命令和目录约定，会增加沟通成本。Codex 提供的 AGENTS.md 可以保存这些长期有效的项目规则。本文依据 OpenAI 官方文档整理，资料核对日期为 2026 年 10 月 19 日。[1]
先把指令放在正确的位置
官方文档说明，Codex 在启动任务时构建指令链：先读取全局指令，再从项目根目录沿路径读取到当前工作目录。同一目录优先选择非空的 AGENTS.override.md，然后才是 AGENTS.md；每个目录最多纳入一份文件。较深目录的指令会覆盖前面的冲突规则。[1]
这意味着，你不必把所有约定塞进根目录：
1demo/2├── AGENTS.md3├── web/4│ └── AGENTS.md5└── worker/6 └── AGENTS.md
本文建议根目录只描述共同规则，前端与任务处理器各自保存专用规则。需要注意：这里的发现路径与启动时的当前目录有关。不要假定从根目录启动后，所有子目录文件已经自动加载；应让 Agent 在修改具体模块前检查适用指令。
一份可以按项目改写的模板
下面是本文设计的示例，使用前必须把路径与命令换成仓库实际存在的内容。
1# 项目约定23## 结构4- web/ 保存前端；worker/ 保存后台任务。5- 修改模块前，读取该模块适用的 AGENTS.md。67## 依赖8- 使用仓库现有的包管理器和锁文件。9- 新增依赖前说明用途，并检查现有依赖能否完成任务。1011## 验证12- 先检查 package.json，确认可用脚本。13- 修改业务逻辑后运行相关测试。14- 交付时写明执行的命令、结果和未验证范围。1516## 数据17- 凭据从环境变量或已配置的凭据管理服务读取。18- 日志与示例使用合成数据，避免带入真实客户信息。
模板的作用是减少猜测。例如，“运行相关测试”之后还要求写明命令，就能让人判断 Agent 到底验证了什么。若项目没有测试，应该如实记录，而不是编造一个通过结果。
AGENTS.md 与 Skill 怎么分工
官方文档把 Skill 定义为可复用的工作流：一个技能目录包含带有 name、description 的 SKILL.md，也可以附脚本与参考资料。Agent 先看到名称与描述，决定使用后再读取完整指令。[2]
据此，本文建议：
内容 | 建议位置 |
|---|---|
每次修改都适用的项目规范 | 根目录 AGENTS.md |
某个模块的额外规则 | 对应目录的指令文件 |
只在数据库迁移等任务中需要的详细流程 | 专用 Skill |
本次修改的临时目标 | 当前任务提示词 |
例如，根文件只写“修改数据库结构时使用项目的迁移技能”，详细的备份、迁移和验收步骤交给技能维护。这样更容易避免同一规则复制多份后互相矛盾。
用三个场景检查规则是否有用
以下是本文建议的验收方式，不代表已经在你的仓库完成测试。
- 正常修改：让 Codex 修复一个小问题，检查它是否采用现有包管理器、运行适用检查并说明结果。
- 目录差异：分别从根目录和模块目录开启任务，让它列出实际加载的指令来源，核对规则是否符合预期。
- 能力不足：选择一个暂时缺少运行环境的任务，检查它是否明确报告无法验证的内容。
可以用这段提示词开始：
先列出本次任务已加载或已读取的项目指令及其适用范围。检查仓库现有脚本，再完成这个小修改。交付时列出修改内容、实际验证结果和剩余限制。
修改指令后若仍出现旧行为，官方文档建议重启目标目录中的 Codex 会话，重新构建指令链。[1]
保持规则简短，并持续删改
一份规则文件是否有效，取决于它能否改变可观察的工作行为。建议先写三到五条最常重复的约定，实际使用后再补充。格式检查交给工具，复杂流程交给 Skill，只有长期有效的项目决策留在这里。
参考来源
本文为原创整理；模板与验收场景为作者建议，并非官方模板。未在读者环境执行示例。