AGENTS.md 怎么写：给 Codex 一份能执行、能验证的项目说明

先把长期规则和本次任务分开

AGENTS.md 适合保存会在多轮任务里重复使用的约定，例如允许修改的目录、测试命令、禁止触碰的文件和完成证据。本次只改一句文案之类的短期目标，留在当前任务说明里，不要不断把根文件写长。

官方文档说明 Codex 会在开始工作前读取适用范围内的 AGENTS.md；这证明读取约定，不自动证明规则写得清楚或任务已经完成。

复制一份能验收的最小模板

把下面代码块按项目替换，先求可执行，不求面面俱到。复制失败时可以直接手动选择代码。

# 项目目标
一句话说明这次长期要维护的结果。

## 允许范围
- 可以修改：src/、tests/
- 不要修改：.env、生产数据、生成目录

## 完成标准
- 先运行对应测试
- 再运行 git diff --check
- 最终报告改动文件、命令结果和未验证项

## 工作约定
- 保留现有行为
- 不新增依赖
- 失败时记录原始错误，不伪装完成

1. 写入根目录 AGENTS.md

   操作

   把模板保存为项目根目录的 AGENTS.md，并把目录、命令和禁止项替换成仓库真实内容。

   你应该看到

   每条完成标准都能对应一条命令输出或一个可观察结果。

   如何确认

   逐条指出谁执行、在哪个目录执行、看到什么才算通过。

   卡住时

   • 如果不知道测试命令，先读 package.json、README 或现有 CI 配置，不要编造命令。
   • 如果禁止项覆盖整个项目，把范围缩到真正不可触碰的密钥、生产数据或生成物。

理解 root 到当前目录的层级

Codex 从项目 root（根目录）走到当前工作目录 cwd（这次任务所在目录），沿途读取 AGENTS.md；更靠近当前文件的规则会覆盖更上层冲突规则。这样可以把全仓库约定放在根目录，把前端或测试的特殊命令放在对应子目录。

官方页面还说明默认读取预算 project_doc_max_bytes 为 32 KiB。超过预算时，后面的说明可能进不了上下文；应删除重复内容，或把只在某个目录生效的规则移到更近的 AGENTS.md。

用新任务验证读取结果

不要以“文件已经保存”当作生效证据。关闭旧对话或开启新任务，在目标目录运行官方建议的验证读取命令：codex --ask-for-approval never "Summarize the current instructions."。重点核对它复述的允许目录、禁止项和验证命令。

1. 对照复述与原文

   操作

   在项目目录执行验证读取命令，把输出与 root 到 cwd 的每个 AGENTS.md 逐项对照。

   你应该看到

   输出能复述当前目录真正适用的目标、边界和验证要求。

   如何确认

   故意选择一条只在子目录存在的无害规则，确认近目录覆盖已被读到。

   卡住时

   • 如果仍出现旧规则，确认命令运行目录并重新开启任务，避免把旧对话记忆误当文件读取。
   • 如果输出缺少后半段，检查总文本是否接近 32 KiB 预算并删除重复解释。

规则没生效时按层级排查

Codex 跑错命令时，先确认当前目录，再列出 root 到 cwd 的所有 AGENTS.md，检查是否有更近文件覆盖了根规则。若它读到了规则却仍无法验收，问题通常不是“再写得更强硬”，而是命令不存在、范围冲突或完成标准无法观察。

• 读错目录：回到实际项目目录后重新验证读取。
• 规则冲突：保留更近目录的特殊规则，并让根规则只表达全局约定。
• 规则过长：删去愿景口号、重复背景和一次性任务，把确定性命令留在前面。
• 验收模糊：把“质量要好”改成测试、diff、页面或输出文件检查。

本站本次实测：子目录规则被新任务读到

版本：Codex CLI 0.138.0，显式使用 gpt-5.4 与 read-only sandbox。输入：要求新任务复述当前规则、不得改文件或运行命令，并返回证据 token。关键输出：回复包含 GUIDE_AGENTS_LAYER_2026_07_15，并明确 no files may be changed、commands may not be run。退出码：0。验收结论：通过，一次新的非交互任务实际读取了夹具 AGENTS.md。失败项：默认 gpt-5.6-luna 与此 CLI 不兼容，首跑退出 1；本机插件与系统 Skill 权限警告不影响验收输出。下方“本节来源”链接公开命令、输入、输出摘录、退出码和限制的脱敏 JSON 摘要。

来源与转换边界

层级、近目录覆盖、32 KiB 默认预算与验证读取命令来自 OpenAI 当前官方文档；案例来源只帮助发现常见写法问题。本文按中文任务重新组织并加入可执行模板，没有完整翻译任何英文文章，也没有把一次本地实测外推成普遍效果。