Codex的AGENTS.md怎么写？项目规则、子目录覆盖与不生效排查

每次打开同一个代码项目，都要重新告诉Codex用哪个包管理器、如何验证、哪些文件不要改，会让任务容易遗漏要求。AGENTS.md可以保存项目约定。本教程用一个练习网站说明规则放在哪里、如何验证加载，以及子目录有特殊要求时怎样覆盖，不将写了文件等同于规则已经生效。

第一步：确认当前项目和工作目录

官方说明Codex启动时构建指令链，项目层从项目根目录沿路径走到当前工作目录；通常项目根是Git根。找不到项目根时只检查当前目录。先明确本次从哪里启动，再决定AGENTS.md位置，避免把文件放在不在发现路径上的另一个文件夹。

全局规则默认放在Codex主目录中，通常为~/.codex；如果配置了CODEX_HOME，则以该位置为准。本教程优先只设置练习项目内规则，不修改全局行为。已有文件先备份和阅读，再合并需要的约定，不能为了套模板覆盖团队已有内容。

第二步：写少量可执行的项目约定

# AGENTS.md

## 项目约定
- 开始前阅读README中的启动和验证方法。
- 沿用仓库已有包管理器，不混用锁文件。
- 修改范围限于当前任务；不改生成文件和无关配置。
- 修改行为后运行对应检查，报告实际命令和结果。
- 不知道业务规则时标为待确认，不编造数据。

把实际存在的检查命令写清楚，比要求“质量必须完美”更有用。若项目根本没有npm test，就不能盲目要求始终执行它。规则应说明适用范围和完成标准，避免长篇重复规范挤占上下文；敏感密钥、真实客户数据也不应写进指导文件。

第三步：理解同目录与子目录的优先顺序

同一目录先检查AGENTS.override.md，再检查AGENTS.md，随后才是配置的备用文件名，每个目录最多选一份。全局层也优先读取非空的override文件。沿根目录到当前目录合并时，更靠近当前目录的要求可覆盖前面的同类约定。不要以为两份同目录文件都会叠加读取。

例如仓库根要求通用检查，docs目录需要不同的文档校验，可以在docs增加适用的指导文件。但从根目录启动的指令发现不会自动把所有子目录文件遍历一遍。开始处理特殊目录时明确要求读取相关规则，并核对本次工作目录和实际加载来源。

第四步：用只读提问验证加载

请先不修改任何文件。列出这次启动发现的指导文件路径与顺序，摘要说明包管理器、允许修改范围、验证方式。检查是否有AGENTS.override.md覆盖了同目录AGENTS.md；如规则冲突，说明本次采用哪条以及原因。不要把未读取的文件说成已加载。

将回答与磁盘上的实际文件对照，确认不是模型根据常识猜出来的约定。官方说明指令链通常在每次运行或TUI会话开始时构建，改完规则后应重启对应会话再验证。让旧会话继续回答，不足以证明启动发现逻辑读到了新文件。

第五步：按现象定位失效原因

完全没加载，检查启动目录、文件是否为空及项目根判断；加载了错误要求，查全局和上级override；备用名称无效，检查project_doc_fallback_filenames拼写并重新启动。官方默认组合指导文档上限为32KiB，过长时应先压缩和分层，必要时再调整配置。

AGENTS.md是上下文约定，不会代替实际测试、文件权限或Git检查。验收标准是路径正确、加载来源可解释、规则简明且与真实项目一致，并在下一次任务中看到相应行为。团队维护时把项目规则纳入版本管理，发现过期命令及时修正，避免越积越长的旧要求影响后续任务。

官方资料

资料核对日期：2026年10月31日。

• OpenAI：AGENTS.md指令发现与配置