这段时间项目改 bug，我用的 Codex。活儿它是干完了，测试也过了，但我打开 diff 一看就火了，它用了 npm，而这个项目全组都用 pnpm；它顺手加了个依赖没打招呼；提交信息还写得跟它自己爽了似的，完全不是我们仓库的规范。我又得回去一条条纠，纠完下一个任务，它照样再来一遍。这不是 Codex 笨，是它根本不知道你的规矩，你没告诉它，它就只能按自己那套来。问题是，也不可能每次开一个任务都把项目规范、测试命令、代码风格从头打一遍字，那太蠢了。其实 Codex 早就留了个口子解决这事，就是一个叫 AGENTS.md 的文件。写好它，Codex 每次干活前会自动读一遍，相当于你把项目的规矩一次性交代清楚，之后它就照着来。这文件门槛低到离谱，但真正写明白、用对的人不多。

它就是写给 AI 看的 README

项目里的 README.md 是给人看的：项目是干嘛的、怎么快速跑起来、怎么参与贡献。 AGENTS.md 补的是另一半，那些给 AI agent 看的、写进 README 会显得啰嗦、但 agent 又必须知道的东西：怎么装依赖、用哪个包管理器、跑测试用什么命令、代码风格什么样、提 PR 有什么规矩、哪些操作绝对不能碰。它就是个普通的 Markdown 文件，没有任何必填字段，你爱写什么标题写什么标题，Codex 自己会读，放在仓库根目录，它启动干活之前会先把这个文件读进上下文。这套格式现在已经不是 OpenAI 一家的私货了，它由 Codex、Cursor、Google 的 Jules、Amp、Factory 一起攒出来，现在归 Agentic AI Foundation 管，超过 6 万个开源项目在用。也就是说，写一份 AGENTS.md，换 Cursor、换 Gemini CLI 一样认，不用重写。一个细节挺能说明问题：OpenAI 自己的主仓库里，塞了 88 个 AGENTS.md。

它最聪明的地方：一层压一层，就近生效

如果只是根目录放一个文件，那还不算什么，AGENTS.md 真正好用的是它的分层机制。 Codex 每次启动会临时拼一条「指令链」，按这个顺序找：先看全局的。在 Codex 主目录（默认 ~/.codex）里放一份，写个人的通用偏好，比如装依赖优先用 pnpm、加生产依赖前先问我一句，这样不管打开哪个仓库，这些习惯都跟着走。再看项目的。从项目根目录一路走到当前所在的目录，每一层都找有没有 AGENTS.md。最后合并。从根往下拼，越靠近当前目录的文件，越晚出现在提示里，也就越有话语权。这带来一个很实用的效果：就近覆盖，比如有个 monorepo，根目录规定跑测试用 npm test，但 services/payments 这个子目录情况特殊，得用 make test-payments。只要在这个子目录里单独放一份 AGENTS.md，写清楚它的规矩，Codex 在这个目录干活时就自动用这套，不影响别处。官方 FAQ 里那句话说得很直白，离改动文件最近的那份 AGENTS.md 说了算；而在对话里直接下的指令，优先级压过一切。

那到底该往里写什么

别一上来就想写全，官方反复强调一句话，一份短而准的 AGENTS.md，比一份又长又空的强得多。怎么判断该写什么？有个简单标准，你会怎么跟一个刚入职的同事交代这个项目，就把那些话写进去。最该写的是命令那一块，依赖怎么装、开发服务器怎么起、测试怎么跑，这是 Codex 用得最频繁的信息，也是最容易踩雷的地方。代码风格。用不用 TypeScript 严格模式、单引号还是双引号、加不加分号，这些在意的，写清楚它就照做，不然它只能猜。测试和 PR 规范也顺手带上，CI 配置在哪、怎么只跑某个包的测试、合并前要不要全绿、提交标题什么格式、提交前必须跑哪些检查。最后别忘了红线，哪些操作绝对不能碰，写明白，比如不通知安全群，别动任何密钥这种，一句话能挡掉大麻烦。下面这份样板把上面几块都覆盖了，可以直接抄过去改成自己项目的样子：

# AGENTS.md

## 环境与命令
- 装依赖：pnpm install
- 起开发：pnpm dev
- 跑测试：pnpm test
- 提 PR 前必须跑：pnpm lint 和 pnpm test，全绿才能合

## 代码风格
- TypeScript 严格模式
- 单引号、不加分号
- 优先用函数式写法

## 测试
- CI 配置在 .github/workflows
- 改了代码就补对应测试，哪怕没人要求
- 移动文件或改 import 后，跑一遍 lint 确认没破

## 红线
- 加新的生产依赖前先问我
- 不通知安全群，别动任何密钥

不用一次写满，CLI 里有个 /init 命令能生成一份初始骨架，在这基础上改成自己项目真实的样子就行。

几个容易忽略的点

文件有大小上限。 Codex 拼指令链时有个默认 32 KiB 的上限，超了就截断，所以别把一份 AGENTS.md 写成万言书，真要写很多，就拆到各个子目录里，靠就近生效来分担。这个上限也能在配置里调大。 空文件会被直接跳过。 如果发现规矩没生效，先确认文件里真有内容，别是个空壳。 想临时改规矩、又不想删原文件。 可以用 AGENTS.override.md，同一层里，override 文件优先级比普通 AGENTS.md 高，Codex 会用它、忽略掉旁边那份普通的，临时需求过了，把 override 删掉就恢复原样，这个机制在团队里很有用，想给某个子模块单独加规矩，不用去动大家共用的那份。 已经有别的文件名了怎么办。 比如团队一直用 TEAM_GUIDE.md。不用改名，在配置里把这个文件名加进 fallback 列表，Codex 就会把它也当指令文件读。 改了不生效？ 重启就好，Codex 是每次启动重新拼指令链的，没有缓存，如果感觉读的是旧规矩，在目标目录里重启一下 Codex 就会重新读。

写在最后

AGENTS.md 这东西，说复杂不复杂，就是一个 Markdown 文件，但它解决的是 AI 编程里一个很实在的痛点：和 agent 之间反复对齐规矩的成本。以前每开一个任务，都得重新交代一遍项目怎么回事；现在写一次，它每次自己读，犯了同样的错两次，就让它复盘一下，把教训追加进 AGENTS.md，这个文件是活的，越用越贴合项目。如果已经在用 Codex，花十分钟给你最常改的那个项目写一份，是我最近觉得性价比最高的一个动作，别追求一步到位，先把跑项目的命令、代码风格、几条红线写上，跑一阵子，发现它老在哪犯错，再往里补。同样的模型，同样的代码库，配不配这个文件，用起来的顺手程度差一截。

参考来源

AGENTS.md 官方站：https://agents.md Codex 官方文档（AGENTS.md 指南）：https://developers.openai.com/codex/guides/agents-md