每开一个新对话窗口，Codex 都会进入全新的上下文。它不知道项目用什么命令，也不清楚目录边界在哪。哪些文件不能改，团队怎么验证结果，这些它都不知道，每次都靠开口重讲。
AGENTS.md 就是解决这个问题的项目级指令文件，一个开放的 Markdown 约定，给 coding agent 提供稳定、可预测的项目指令入口。项目结构、开发命令、测试要求和协作边界写进去，反复解释的部分就省掉了。
它和 README 不是一回事
更准确地说，AGENTS.md 是面向 coding agent 的 README。README 给人看，讲项目是什么、怎么上手。AGENTS.md 给 Codex 这类 agent 看，告诉它们改代码前要遵守哪些规则。
落到人身上，价值分三种。个人用户省掉重复解释项目怎么跑，怎么测。团队项目把公认的规则沉淀进仓库。多工具环境下，Codex 和 IDE 里的 agent 读的是同一份说明。
放在哪里：项目根目录还是全局
普通项目最推荐在项目根目录建 AGENTS.md。Codex 处理任务前会自动读它，作为工作上下文带进对话。
想让规则对所有项目生效，就写全局指令。在 Codex 主目录里建一个 AGENTS.md，默认位置是用户目录下的 .codex/AGENTS.md。设过 CODEX_HOME 的话以那个目录为准。桌面 App 里的个人偏好和自定义指令，本质上也是写到这里。
两层规则作用域不一样。全局规则影响你打开的所有项目，项目级的只影响当前仓库。
文件名必须写成 AGENTS.md，大小写也要对，写错 Codex 不会自动识别。
读取顺序与合并规则
第一步读全局规则，默认读 .codex/AGENTS.md。同一位置如果还放着 AGENTS.override.md，就优先读它，用来临时覆盖。
第二步读项目规则。Codex 从 Git 根目录一路走到当前工作目录，沿途每一层都试着读一次。同一目录里同时有 AGENTS.override.md 和 AGENTS.md 时，前者覆盖后者。
读到的规则从上到下合并，根目录的先出现，子目录的后出现。越靠近当前目录的规则越具体，局部要求写在那层最合适。根目录写通用规则，前端目录写前端规则，数据库目录写迁移要求。
两个配置项值得知道。项目里已经有别的规则文件时，可以用 project_doc_fallback_filenames 把它们加成备用名。合并后的项目指令还有大小上限，默认 32768 字节，写得太长后面的内容可能进不了上下文。
团队共享与个人私有怎么分
多人协作时，AGENTS.md 放团队共同认可的项目规则。个人路径和本机工具习惯留在本地更合适，临时约束与私有偏好也一样。团队规则保持稳定，个人习惯也不会被提交。
| 文件 | 作用 | 是否提交到 Git |
|---|---|---|
| AGENTS.md | 团队共享的项目规则与命令，含边界和交付要求 | 可以提交 |
| AGENTS.override.md | 官方识别的覆盖文件，临时覆盖同目录规则 | 通常不提交，除非团队约定 |
| AGENTS.local.md | 个人本地偏好、私有路径和临时规则 | 应加入 ignore |
AGENTS.local.md 不是默认识别的标准文件名。想让它被读到，得靠 hooks 或者社区工具，也可以在配置里加进 fallback 文件名。
社区工具 codex-agents-local 提供了这套方案，它通过 hooks 在会话开始或提交提示词时同步规则。它不是官方功能，安装前先看清脚本会改哪些文件、启用哪些 hooks。
不管用不用本地规则，底线要守。密钥和密码不要写进 AGENTS.local.md，并且把它加进 gitignore。也不要借本地规则绕过团队的测试和审批要求。
一份可以直接抄的模板
这份模板覆盖了大多数项目要交代的事，按自己的情况填就行。
项目概览
- 项目类型：
- 主要语言：
- 关键目录：
- 不要修改的目录：
常用命令
- 安装依赖：
- 本地开发：
- 运行测试：
- 类型检查：
- 格式化：
代码规范
- 遵循现有代码风格。
- 不做无关重构。
- 新增功能要补测试。
安全边界
- 不提交 .env 和私有凭据。
- 不执行删除生产数据的命令。
- 改数据库迁移前先说明影响。
交付要求
- 说明改动文件。
- 说明验证命令和结果。
- 说明未验证项和剩余风险。几条实践建议
命令要写具体的，别写态度。一条具体的测试命令，比一句”记得检查代码”有用得多。
规则之间不能打架。这里的要求要和项目里其他规范文档一致，冲突的地方 Codex 判不出来。
AGENTS.md 更适合承担导航作用。可以告诉 Codex 项目文档按什么顺序读，别把所有文档都塞进来。
规则也要跟着项目走。命令和目录会变，验证方式也会变，拖久了就成了误导。
收尾
AGENTS.md 是 Codex 每次进项目都会先看的一页纸。写短、写准、写具体，比在对话里反复纠正省事。
