夜雨聆风《Codex 零基础入门》系列 · 第 05 期
本文约 2400 字 · 阅读约 7 分钟 · 适合人群：想让 Codex 在项目里“自动懂规矩”的新手
上一期我们讲了提示词四要素。但你大概会发现一个新麻烦：每次都得重复说“我们用 pnpm，不用 npm；提交前跑 lint；不要碰 legacy/ 目录”……这些项目级的规则，写进 prompt 太累、还容易漏。
解决方案是一个简单到不像答案的东西——一个放在项目根目录的 Markdown 文件：AGENTS.md。它会被 Codex 每次启动自动读取，就像新员工入职时拿到的那份手册。
一、AGENTS.md 是什么
一句话：AGENTS.md 是一份写给 AI 编程代理看的 README。
README 写给人看，告诉读者这个项目是干嘛的、怎么用；AGENTS.md 写给 Agent 看，告诉它“在这个项目里应该怎么干活”——用哪个包管理器、怎么跑测试、什么不能碰、PR 标题怎么写。
更妙的是，它已经成了一个跨工具的开放标准——OpenAI Codex、Cursor、Gemini CLI、Windsurf 等多个工具都会读这个文件。一份写好，多个工具受益。它目前由 Linux Foundation 旗下的 Agentic AI Foundation 维护。
二、为什么需要它
•不用每次重复说相同的话。项目规则写一次，Codex 每次启动自动加载，节省你和它两边的精力。
•团队成员共享同一套规则。AGENTS.md 进 Git 版本控制，所有人（和所有人的 AI）用同一份。
•让 AI 跨工具一致行为。今天用 Codex，明天换 Cursor，规则不必重写。
•作为新人（人或 AI）的快速入职文档。实际上很多团队发现，新人也开始读 AGENTS.md 来上手项目。
三、最关键的写法原则：命令优先，越具体越好
好的 AGENTS.md 不是文学创作，而是一份“可直接复制粘贴”的操作清单。
•✅ 写命令："提交前运行 pnpm lint --fix && pnpm test"——清晰、可执行、可验证。
•❌ 别写口号："写干净、可读的代码"——对 AI 来说等于没说。
•✅ 给路径和参数：“运行单个测试：pnpm vitest run -t “<测试名>””——AI 能直接照着抄。
•❌ 别给空话："遵循最佳实践"——AI 不知道你说的最佳实践是哪一套。
•不要放密码和密钥。AGENTS.md 是要进版本控制的，敏感信息走环境变量。
四、一份最小可用模板
把下面这份扔到项目根目录，改改命令就能用：
# AGENTS.md ## 项目简介 订单服务的后端，Node.js + TypeScript + Fastify + PostgreSQL。 目录：src/ 业务代码，migrations/ 数据库迁移，tests/ 测试。 ## 开发环境 - Node.js 22+，包管理器用 pnpm（不要用 npm 或 yarn） - 安装依赖：pnpm install - 本地启动：pnpm dev ## 测试 - 跑全部测试：pnpm test - 跑单个文件：pnpm vitest run path/to/file.test.ts - 跑指定测试：pnpm vitest run -t "测试名" - 覆盖率：pnpm test --coverage ## 代码规范 - 提交前必须运行：pnpm lint --fix && pnpm typecheck - 新函数必须有类型注解 - 文件命名用 kebab-case ## PR 规则 - 标题用 Conventional Commits：feat(scope): description - 每个 PR 聚焦一件事，diff 控制在 400 行以内 - 改动行为时必须更新测试 ## 不要碰 - legacy/ 目录下的代码（计划在 Q3 整体重写） - migrations/ 里已生成的迁移文件（只能新增） |
五、Codex 怎么读它（分层规则）
AGENTS.md 不止一个文件——Codex 会从一条“指令链”里依次加载，越靠近你当前工作目录的规则优先级越高。
•全局层：~/.codex/AGENTS.md 放你的个人偏好（比如"我喜欢函数式风格"），所有项目都生效。
•项目根层：项目根目录的 AGENTS.md 放项目级规则，团队共享。
•子目录层：在 services/payments/ 这种子模块下可以再放一份 AGENTS.md，覆盖父级规则。
Codex 从项目根一路向下读到当前目录，依次拼接进上下文。还有一个特殊文件 AGENTS.override.md，如果存在，会替换同层的 AGENTS.md，方便临时覆盖而不删原文件。
懒得手写？在 TUI 里直接敲 /init，Codex 会读你的项目然后自动起草一份 AGENTS.md，你在它的基础上改就行。
六、几个常见误区
•写成 README 的样子：AGENTS.md 是操作清单，不是项目介绍——尽量短、尽量是命令。OpenAI 自己仓库里的 AGENTS.md 才二三十行。
•一上来就写得很全：从 20–30 行开始，遇到 Codex 反复犯的错再补一条。它是“长出来的”，不是“设计出来的”。
•放秘密：AGENTS.md 进 Git，凡是不想 push 上去的东西都不能写进来。
•和 README 重复：项目介绍、教程那些留给 README，AGENTS.md 只关心“AI 干活时要遵守什么”。
本期小结
•AGENTS.md 是一份给 AI 看的“项目入职手册”，Codex 启动时自动读取。
•已成为多工具共用的开放标准（OpenAI、Cursor、Gemini CLI 等都支持）。
•写法原则：命令优先，越具体越好；别写口号、别放密码、别和 README 重复。
•支持分层：全局（~/.codex/AGENTS.md）+ 项目根 + 子目录，越靠近越优先。
•懒人方案：在 Codex TUI 里敲 /init 自动生成初稿。
下期预告
本系列入门篇的最后一个核心话题——《Codex 会乱改我的代码吗？沙箱、授权与自动审查》。把“它真的会动手”这件事的安全机制讲透：沙箱怎么管它能做什么、审批怎么管它什么时候问你，以及新手最稳妥的权限配置。 |
参考来源（官方）
OpenAI Developers：Custom instructions with AGENTS.md（developers.openai.com/codex/guides/agents-md）
agents.md：官方标准说明（agents.md）
OpenAI Developers：Best Practices（developers.openai.com/codex/learn/best-practices）
本文基于公开资料整理，Codex 功能更新较快，具体请以官方最新文档为准。
