AGENTS.md 是给 Codex 的项目级工作说明。它适合记录真实的构建命令、目录边界、代码约定和验收要求，让每次任务从同一组可检查的规则开始。它不是 README 的替代品，也不应该堆满只对某一次任务有效的临时提示。
OpenAI 当前文档说明，Codex 会在开始工作前读取 AGENTS.md，并把全局规则与项目目录中的规则按顺序合并。要让这套机制可靠，关键不是写得越长越好，而是把规则放到正确层级，并明确验证方式。
AGENTS.md 适合解决什么问题
一份有效的项目说明，应回答 Codex 开工前必须知道、且能从仓库中核实的问题：
- 项目使用什么包管理器、运行时和主要命令；
- 修改不同目录时分别要运行哪些检查；
- 哪些文件由工具生成，不能手工编辑；
- 哪些用户改动、密钥、媒体或生产数据必须保留；
- 完成任务时需要报告哪些结果和未验证事项。
规则要能转化为具体行为。例如“修改 TypeScript 后运行 pnpm check”比“保证代码质量”更可执行；“不得把 .env 内容写入日志或提交”也比笼统的“注意安全”更容易验收。
Codex 如何发现和合并规则
OpenAI 官方文档给出的发现顺序分为全局和项目两部分，而且每次运行只建立一次指令链。在终端交互界面中，这通常意味着启动一个新会话时重新发现。
- 全局范围： Codex 在
CODEX_HOME中查找规则；默认位置是~/.codex。若存在非空的AGENTS.override.md，它优先于AGENTS.md。 - 项目范围： Codex 从项目根目录（通常是 Git 根目录）一路走到当前工作目录。每一级目录依次检查
AGENTS.override.md、AGENTS.md，再检查配置的备用文件名；每个目录最多采用一个文件。 - 合并顺序： 规则从根目录到当前目录依次加入。距离当前目录更近的文件排在后面，因此可以覆盖更上层的说明。
空文件会被跳过。当前官方文档还说明，合并内容受 project_doc_max_bytes 限制，默认上限为 32 KiB。接近上限时，应删除重复说明或把只适用于局部目录的规则下沉，而不是盲目提高长度。
全局、项目和子目录如何分工
推荐按“适用范围”放置规则，而不是按编写者或时间分类。
~/.codex/AGENTS.md # 个人跨项目习惯
my-repo/AGENTS.md # 整个仓库的技术栈与总体验收
my-repo/apps/web/AGENTS.md # Web 应用专用命令和边界
my-repo/packages/api/AGENTS.md # API 包专用规则全局文件只放真正跨项目稳定的偏好，例如保留用户改动、先阅读仓库说明、不要输出密钥。仓库根文件负责统一工具链、目录结构和提交前检查。子目录文件只补充或覆盖该目录需要的差异，例如 Web 包使用浏览器测试，而 API 包需要运行契约测试。
AGENTS.override.md 适合明确的临时覆盖，但同一目录中它会取代普通 AGENTS.md，不是在其后追加几行。临时问题结束后要移除覆盖文件，否则后续会话仍可能沿用过期规则。
写出可执行的项目规则
下面是一份精简结构示例。命令必须替换为仓库真实存在的脚本，不要把示例当成通用模板直接复制。
Project agent rules
## Stack
- Astro static output with strict TypeScript.
- Use pnpm only.
## Before editing
- Read docs/CONTENT.md for editorial changes.
- Preserve existing user changes shown by Git status.
## Validation
- Run pnpm check after TypeScript or Astro changes.
- Run pnpm validate before handing off publishable work.
## Security
- Never print or commit .env values.
- Keep editorial media outside public/ and dist/.将规则写成“触发条件 + 动作 + 结果”更容易维护。例如：“修改内容集合后运行 pnpm build，并确认新 URL 出现在 sitemap”同时说明了何时执行、执行什么和检查什么。
不要把容易变化的模型名称、价格或平台默认值写成永久规则。确实需要时，应要求任务在执行当日查阅官方文档，并记录核验来源。
用分层规则管理单一仓库
假设仓库同时包含网站和命令行工具，根目录可以只规定共享边界：使用同一种包管理器、不得修改生成文件、交付前检查 Git 差异。随后在 apps/site/AGENTS.md 中写网站构建和可访问性检查，在 packages/cli/AGENTS.md 中写命令行测试和兼容性要求。
当 Codex 从 apps/site 启动时，它会合并全局、仓库根目录和 apps/site 的说明，但不会因为同级目录中存在 packages/cli/AGENTS.md 就自动加载它。这样能避免不相关命令污染当前任务，也让局部规则更短。
如果局部要求与根规则冲突，应该在子目录文件中明确说明覆盖范围和原因，例如“本目录只运行站点检查，不运行后端集成测试”。含糊的“忽略上面规则”会让边界难以审查。
验证当前会话实际加载了什么
编写完成后，不要只检查文件是否存在。OpenAI 官方页面给出两类验证方法：
codex --ask-for-approval never "Summarize the current instructions."
codex --cd apps/site --ask-for-approval never "Show which instruction files are active."第一条用于确认全局和当前项目说明是否进入指令链；第二条用不同工作目录检查局部规则。提示语只是核验请求，不应让 Codex修改文件。
如果需要调查发现过程，可用一次性配置把日志写到受控目录：
codex -c log_dir=./.codex-log日志和会话文件可能包含本地路径、提示或项目上下文，不应直接提交或公开。检查完成后按项目安全策略处理这些诊断文件。
常见错误与排查顺序
文件存在但没有生效
先确认文件不是空的，再确认启动目录位于预期项目路径内。检查同一目录是否存在优先级更高的 AGENTS.override.md，以及文件名大小写是否正确。修改规则后应启动新会话，让 Codex 重新建立指令链。
子目录规则覆盖了不该覆盖的内容
查看根目录到当前目录之间的所有规则文件。距离当前目录更近的说明排在后面，因此一句过于宽泛的局部规则可能覆盖仓库要求。把覆盖改成具体目录、文件类型或命令条件。
备用文件名没有被读取
只有配置在 project_doc_fallback_filenames 中的名称才会参与发现。每个目录最多采用一个文件，且 AGENTS.override.md 与 AGENTS.md 优先。不要同时维护多个内容不同、却期望全部加载的备用文件。
后半段规则消失
检查合并后的内容是否触及 project_doc_max_bytes。先删除重复段落、长背景和可从 README 获取的说明，再把局部规则移动到适用子目录。提高上限会增加每次会话的上下文成本，不能替代内容治理。
维护与审查清单
每当项目命令、目录或发布流程变化时，同步审查 AGENTS.md。至少确认：
- 所有命令仍在
package.json、任务文件或 CI 中真实存在； - 规则没有要求 Codex伪造测试、部署或日期；
- 全局与项目文件没有重复大段内容；
- 临时
AGENTS.override.md已在用途结束后清理； - 新增子项目拥有必要的局部规则，同时仍继承仓库安全边界；
- 验证命令能在正确工作目录复现当前指令链。
如果你还没有安装终端工具，可先阅读 Codex CLI 安装教程；需要理解会话内命令时，继续查看 Codex CLI 常用命令。
常见问题
AGENTS.md 会自动执行里面的命令吗？
不会因为文件中出现一条命令就无条件执行。它向 Codex 提供任务规则；实际命令仍受当前任务、权限、审批和沙盒边界约束。涉及安装、网络或生产操作时，还应保留明确的人为检查。
README 和 AGENTS.md 应该写同样内容吗？
不必重复。README 面向开发者介绍项目，AGENTS.md 更适合记录代理工作时必须遵循的操作边界和验证要求。两者引用同一真实命令即可，但不要复制整份背景说明。
修改 AGENTS.md 后，当前会话会立即更新吗？
官方文档说明发现链每次运行建立一次。为了避免沿用旧内容，修改后启动新会话，并用只读核验提示确认生效规则。
可以为不同包分别创建 AGENTS.md 吗？
可以。把规则放在对应子目录中，Codex 从该目录工作时会沿根目录到当前目录合并说明。局部规则应只覆盖真正不同的部分。