让 AI 帮你写代码，最头疼的不是它不会写，而是它不懂你的项目：依赖怎么装、测试怎么跑、提交信息什么格式，每次都要在对话里重复交代。这个问题现在有个标准答案——AGENTS.md，一个专门写给 AI 编码工具看的项目说明文件。GitHub 上已经有超过 6 万个开源项目在用它。
一句话理解：README 是写给人看的，AGENTS.md 是写给 agent 看的。你在 Codex 里干活的每一个项目，都值得放一个。
里面写什么
官方给的定位很克制：构建步骤、测试命令、代码风格、PR 规范这些”会塞爆 README、对人类贡献者又没什么用”的信息。比如一个典型的 AGENTS.md 长这样：
## Setup commands
- Install deps: pnpm install
- Run tests: pnpm test
## Code style
- TypeScript strict mode
就这么朴素。没有特殊语法，没有 YAML，就是普通 Markdown。它的价值不在格式，而在约定——agent 打开项目就知道去哪找指令，不用你每次喂。
大仓库怎么玩：嵌套
monorepo 场景是它设计得最细的地方。你可以在仓库根目录放一个总的 AGENTS.md，再给每个子项目各放一个。agent 的规则是”就近优先”：改哪个子目录的代码，就先读那个目录的文件，子项目的指令自然盖过全局。官方数据是 OpenAI 自己的主仓库里现在躺着 88 个 AGENTS.md 文件，每个子项目各管各的。
Codex 怎么用上它
Codex 对 AGENTS.md 的支持是原生级别的：进入项目目录后它会自动发现并读取这个文件，你不需要任何配置动作。要做的就是把这个文件提交到仓库根目录，内容和写 CONTRIBUTING.md 的思路差不多——把”你会对新同事交代什么”写进去就对了。
顺带说一句，这个格式已经成了事实标准：Cursor、Gemini CLI、GitHub Copilot 的 coding agent、Devin、Windsurf、Aider、VS Code，加上 Codex，主流 AI 编码工具几乎全数支持。也就是说你写一份文件，全家桶通用，这买卖怎么算都划算。
实操建议：从最短的版本开始写——三条命令（装依赖、跑测试、构建）加两条代码风格约束，先跑起来，之后随着 agent 犯的错逐步补充。别一开始就想着写大而全的规范文档，AGENTS.md 是给机器读的操作手册，不是企业文化手册。
