先说结论：AGENTS.md 是一份放在项目根目录的纯文本规则文件。Codex 在开始任何任务之前会自动读取它，用来了解”这个项目有什么规矩”。写好了它，Codex 上手更快、犯错更少；写错了或写太长，反而浪费上下文和额度。
AGENTS.md 是什么、放哪、什么时候被读？
AGENTS.md 就是一个 Markdown 文件，作用类似于你给新同事写的”项目须知”。
- 放哪：项目根目录，文件名就叫
AGENTS.md。子目录里也可以放，用来覆盖该目录的特殊规则。 - 什么时候被读：Codex 打开项目、新建线程或开始一条新任务时，会自动扫描并加载。你不需要手动指定路径，也不需要在对话里提醒它去读。
- 谁会读：Codex App、Codex CLI、IDE Extension 都会读。只要是在项目目录里工作，它就生效。
你也可以用 CLI 的 /init 命令让 Codex 根据当前项目自动生成一份初稿，再手动调整。
该写什么？7 类适合沉淀的稳定规则
以下 7 类信息不会频繁变动，读一次就能长期指导 Codex：
- 项目用途 —— 一两句话说清项目干什么、给谁用。Codex 判断改动是否合理时需要这个背景。
- 目录边界 —— 哪些目录可以改、哪些不要碰。比如”不要动
config/下的生产配置”。 - 命名规范 —— 文件名、变量名、分支名的规则。比如”组件用 PascalCase，slug 用英文短横线”。
- 常用命令 —— 安装、启动、测试、构建的命令。Codex 看到这些才知道怎么验证改动。
- 必读文件 —— 哪些文件承载了关键配置或数据，改之前必须先看。
- 验收检查 —— 提交前必须满足的条件。比如”build 通过""无 lint 警告""不含禁用关键词”。
- 汇报格式 —— 你希望 Codex 完成后怎么告诉你结果。比如”列出改了哪些文件和改动原因”。
这 7 类覆盖了”开始前要知道的”和”结束后要交代的”，足以让 Codex 在大多数项目里正常工作。
不该写什么？三个常见误区
临时任务不要往里塞。 “帮我改一下首页标题”这种一次性指令，直接在对话里说就行。AGENTS.md 里写的应该是长期有效的规则。
易变数据不要写进去。 价格、版本号、日期这类经常变的内容，放进 AGENTS.md 容易过期。过期信息比没有信息更危险——Codex 会按错误的规则行动。
越长越好是个误区。 AGENTS.md 会占用上下文窗口，内容越多，Codex 每次任务消耗的额度越大。写太多还会让重点被淹没。只写稳定规则，细节拆到子目录或单独的文档文件里。
可复制的中文模板
# 项目规则（AGENTS.md）
## 项目简介
这是一个 [用途简述] 项目，面向 [目标用户]，技术栈 [框架/语言]。
## 目录说明
- `src/` 是主要代码目录，可以修改
- `config/` 下的文件未经确认不要改动
- `docs/` 是文档目录，改内容时需要同步更新
## 命名规范
- 组件文件：PascalCase（如 MyComponent.tsx）
- 工具函数：camelCase
- 文章 slug：英文短横线，无中文无空格
## 常用命令
- 安装依赖：npm install
- 本地开发：npm run dev
- 构建检查：npm run build
- 运行测试：npm test
## 必读文件
- site.config.ts：全站业务参数，改之前先看
- README.md：项目说明
## 提交前检查
- [ ] npm run build 通过，无警告
- [ ] 新文件有完整的头部信息
- [ ] 不含禁用关键词（列表见项目文档）
## 汇报要求
完成后列出：改了哪些文件、每个文件的改动原因、是否通过构建检查。把这个模板复制到项目根目录，替换方括号里的内容即可。如果某个子目录有特殊规则（比如文档目录的写作规范和代码目录不同），在那个子目录下再放一份针对性的 AGENTS.md。
写完之后怎么验证？
最简单的办法：打开一条新线程，让 Codex 用一句话概括你的项目规则。如果它能准确说出目录边界、常用命令和验收条件，说明 AGENTS.md 写得到位。如果它漏掉了重要规则或误解了边界，回去调整。
想了解 Codex 拿到 AGENTS.md 后具体怎么执行任务，参考 Codex 是怎么执行任务的。额度和模型选择的详细说明，参考 Codex 额度指南。
套餐、价格、模型以 OpenAI 官网当时显示为准，本文核对日期 2026-09-17。