如果你已经开始把 Codex 用进真实项目，迟早会碰到一个问题：
同样是“帮我看一下这个仓库”，为什么有时候 Codex 很顺，有时候却像没接住你的意思？
答案往往不在模型本身，而在你有没有把项目规则讲清楚。
这时候，AGENTS.md 就很有用了。
OpenAI 官方把它定义成给 Codex 的项目指导文件。Codex 会在开始工作前读取 AGENTS.md，把它作为持续存在的项目上下文；官方也建议把它当成给 agents 用的开放式 README，写那些你和团队希望 Codex 每次都遵守的规则。
这篇我想把它讲得更像“项目说明书”，而不是概念解释。
一、AGENTS.md 到底是什么
你可以把 AGENTS.md 理解成：
专门写给 Codex 看的项目说明书。
它不是给人看的产品文档，也不是需求文档。它更像一份“项目运行手册”，告诉 Codex：
- 这个仓库是干什么的
- 怎么启动、怎么测试
- 哪些地方可以改
- 哪些地方不要乱动
- 代码风格和提交流程是什么
- 这个仓库有哪些特殊约定
官方文档里提到，一个好的 AGENTS.md 通常会覆盖这些内容：
- build 和 test 命令
- review 期望
- 仓库特定约定
- 目录级别的说明
换句话说，它不是让 Codex “更聪明”，而是让它“更懂你这个仓库的玩法”。
二、为什么要写 AGENTS.md
很多人一开始觉得没必要，觉得自己每次直接在 prompt 里说清楚就行了。
短期看好像可以。但一旦你开始重复做这些事情，AGENTS.md 的价值就出来了。
1. 不用每次重复同样的话
比如你每次都要对 Codex 说：
|
1 2 3 |
请先跑测试。 不要改生产配置。 提交前先看 diff。 |
当这种提示词开始重复出现，最适合把它挪进 AGENTS.md。
OpenAI 官方的 best practices 也明确说过：当某个 prompting pattern 已经稳定有效，就不要每次手动重复，把它写进 AGENTS.md。
2. 让每次任务从同一套规则开始
Codex 会先读这个文件，再开始干活。
这样不管你今天让它改登录页，还是明天让它修 bug，它都能从同一套仓库规则出发。
3. 适合团队协作
如果不是你一个人用，而是几个人一起用 Codex，AGENTS.md 可以帮大家统一口径：
- 怎么命名
- 怎么测试
- 怎么 review
- 怎么提交
- 哪些目录优先保护
这比口头约定稳定得多。
三、AGENTS.md 里应该写什么
我建议你按“从通用到具体”的顺序写。
1. 项目简介
先让 Codex 知道这是什么项目。
|
1 2 3 |
## Project Overview This is a React + Node.js project for internal dashboard management. The frontend lives in `web/`, the backend lives in `api/`. |
2. 启动和测试命令
这个最重要。
Codex 要干活，得先知道怎么验证结果。
|
1 2 3 4 5 |
## Build and Test - Install dependencies: `npm install` - Start frontend: `npm run dev` - Run tests: `npm test` - Run lint: `npm run lint` |
如果你的项目不是 npm，也可以写成 Python、Go、Rust、Java 的对应命令。
重点不是格式，而是让 Codex 知道“怎么确认改动没把项目弄坏”。
3. 代码风格和约定
这部分很适合写那些你不想每次重复讲的规则：
|
1 2 3 4 5 6 |
## Conventions - Prefer small, focused changes. - Do not rename public APIs unless necessary. - Keep file and folder names in English. - Follow the existing formatting style. - Use existing utilities before creating new helpers. |
4. review 规则
如果你常常让 Codex 帮你看改动，可以把 review 规则也写进去。
|
1 2 3 4 5 |
## Review Expectations - Check for regressions first. - Flag behavior changes explicitly. - Mention if tests are missing. - Call out risky changes to auth, config, or production paths. |
5. 特殊目录说明
有些目录最好单独写清楚，比如：
|
1 2 3 4 |
## Directory Notes - `scripts/` contains helper scripts and should not be rewritten casually. - `docs/` should remain documentation-only. - `config/` may affect production behavior and needs extra care. |
这类说明很实用。
Codex 看到以后，会更容易知道哪些地方是“能改”、哪些地方是“要谨慎”。
6. 不要做什么
这一段也很重要，最好直接写清楚。
|
1 2 3 4 5 |
## Do Not - Do not modify secrets or `.env` files. - Do not change deployment settings without asking. - Do not rewrite generated files unless needed. - Do not introduce unrelated refactors. |
四、一个适合新手直接抄的模板
如果你现在就想在仓库里放一个，可以先从这个简版开始。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 |
# Project Overview This repository contains a web app for internal use. ## Build and Test - Install: `npm install` - Start: `npm run dev` - Test: `npm test` - Lint: `npm run lint` ## Conventions - Keep changes small and focused. - Follow existing code style. - Prefer reusing existing utilities. - Avoid unrelated refactors. ## Review Expectations - Check for regressions. - Mention any risky behavior changes. - Point out missing tests. ## Do Not - Do not modify secrets or `.env` files. - Do not change deployment settings without asking. - Do not touch unrelated files. |
这个版本不复杂，但已经够 Codex 用了。
五、写 AGENTS.md 时最容易犯的错
1. 写得太长
AGENTS.md 不是项目百科。
它越长，Codex 越不容易一眼抓住重点。
官方也建议把它保持得小而精。
所以我的建议是：
- 先写最重要的 5 到 10 条
- 后面真的有重复问题，再慢慢补
- 不要把所有制度都一股脑塞进去
2. 写得太空
像这种就没什么用：
|
1 2 3 |
请认真开发。 请注意代码质量。 请保证不要出错。 |
这种话人看着都对，Codex 看了也很难执行。
更好的写法是：
|
1 2 3 |
- Run tests before finishing. - Keep changes limited to the requested files. - Report any failed commands explicitly. |
3. 把 README 当成 AGENTS.md
README 是给人看的项目说明。
AGENTS.md 是给 Codex 看的工作规则。
两者可以内容有交集，但目的不一样。
README 讲“这个项目是什么”，AGENTS.md 讲“Codex 应该怎么在这个项目里做事”。
4. 忘了写测试和 review
这是最可惜的。
Codex 最需要知道的不是“项目宣传语”，而是：
- 怎么验证
- 哪些文件重要
- 哪些地方别乱动
- 出现问题该先看什么
六、AGENTS.md 和普通提示词有什么区别
可以简单理解成：
| 方式 | 作用 | 特点 |
|---|---|---|
| 普通提示词 | 单次任务说明 | 临时、一次性、灵活 |
| AGENTS.md | 仓库级规则 | 持久、自动加载、适合重复执行 |
如果你今天只改一次，普通提示词就够了。
如果你会反复在这个仓库里让 Codex 干活，AGENTS.md 就非常值。
七、我建议的写法顺序
你可以按这个顺序来写：
- 项目简介
- 构建和测试命令
- 代码风格
- review 规则
- 特殊目录说明
- 不要做什么
这个顺序最符合 Codex 实际使用场景。
因为 Codex 最先需要的是：
- 这是什么项目
- 怎么验证
- 哪些地方有边界
而不是一上来先读一堆背景故事。
八、什么时候应该更新 AGENTS.md
下面这些情况，建议顺手更新：
- 新增了测试命令
- 构建方式变了
- 仓库结构调整了
- 某些目录的约定变了
- Codex 反复在同一个地方犯错
- 你们团队开始固定一个 review 流程
它不是写一次就不动了。它应该跟着项目一起长。
九、一个很实用的小习惯
我现在更喜欢把 AGENTS.md 当成“项目里的低配操作手册”。
每次 Codex 在这个仓库里出错，我都会问自己：
|
1 |
这个错误是提示词没说清，还是规则文件没写清？ |
如果是后者，就把它补进 AGENTS.md。
这样下次就不用再手动重复同一句话了。
十、总结
AGENTS.md 其实不神秘。
它就是一份专门写给 Codex 的项目说明书，核心目标是把重复规则固化下来，让每次任务都从同一套仓库规范开始。
如果你记不住太多东西，只要记住这句话就够了：
当你发现自己总是在重复同样的提示词时，就该把它写进 AGENTS.md 了。
这会比一次次手动提醒 Codex 稳得多，也更适合长期维护项目。
