OpenAI Codex 橙皮书·第四篇·AGENTS.md

上一篇讲了第一个项目跑通 + CLI 深度使用，重点是 Auto-review 怎么改审批心智、Windows Full Access 为什么绝对不要开。这篇开始进入这本书的核心实践之一：AGENTS.md。一份好的 AGENTS.md 能让 Codex 从「空降新人」变成「了解项目规矩的老手」。

一、AGENTS.md 是什么

如果你读过花叔的 Claude Code 橙皮书，一定记得 CLAUDE.md 那一章。在 Claude Code 的世界里 CLAUDE.md 是最重要的文件，是 AI 的「宪法」。

AGENTS.md 在 Codex 中扮演的角色完全一样。名字不同逻辑相通：你把项目的构建命令、代码规范、常见陷阱写在一个文件里，AI 每次启动时先读它，然后带着这些背景知识开始干活。没有它 Codex 就是蒙着眼写代码，有了它一进来就知道规矩。

Codex 每次启动时会自动读取 AGENTS.md。这是你和 AI 之间关于「怎么干活」的契约。

二、Codex 怎么找到你的 AGENTS.md

这部分是技术细节但很重要。Codex 的发现机制比你想象的要复杂一些，不是「放个文件在根目录就行了」那么简单。

Codex 在每次运行开始时构建指令链。发现顺序如下：

全局级：在 Codex 主目录（默认是 ~/.codex，可通过 CODEX_HOME 环境变量修改）中，先找 AGENTS.override.md，找不到再找 AGENTS.md。这一层只取一个文件。

项目级：从项目根目录（通常是 Git 仓库根目录）开始，逐级向下走到当前工作目录。每个目录中依次检查 AGENTS.override.md、AGENTS.md、以及 project_doc_fallback_filenames 中配置的备选文件名。每个目录层级最多取一个文件。

合并：所有找到的文件按从根到当前目录的顺序拼接。越靠近当前目录的文件优先级越高，因为它们出现在合并后内容的后面，会覆盖前面的指令。

Codex 会跳过空文件，合并后的总大小上限默认是 32KB（由 project_doc_max_bytes 配置项控制）。超出限制时，后面的文件会被跳过，不再加入指令链。

花叔的经验：32KB 听起来很大，但如果你在多个嵌套目录都放了 AGENTS.md，很容易撞到上限。建议把核心规则集中在根目录文件里，子目录文件只写该目录特有的内容。

三、override 机制：临时覆盖不删原文件

注意到了吗？每一层都优先找 AGENTS.override.md。

这个设计很聪明。场景是这样的：你的团队维护了一份 AGENTS.md 并 check 进了 git 大家共享。但你个人有些不同的偏好，比如你喜欢用 pnpm 而团队规范用 npm。这时候你不需要修改团队文件，只要在同一目录放一个 AGENTS.override.md，它会直接替代同级的 AGENTS.md。

把 override 文件加到 .gitignore 里，团队的基础规范不受影响，个人偏好也保住了。同样的逻辑也适用于全局级：~/.codex/AGENTS.override.md 会临时替代 ~/.codex/AGENTS.md，删掉 override 文件就恢复原来的全局设置。适合做短期实验。

四、/init：快速生成初始 AGENTS.md

不想从零开始写？在 Codex 里输入 /init 命令，它会分析你的项目结构，自动生成一份初始的 AGENTS.md。

生成的内容通常包括：项目使用的语言和框架、检测到的构建和测试命令、目录结构概述。它不完美，但给了一个起点。你在此基础上增删修改，比从空白文件开始快得多。

五、该写什么、不该写什么

判断标准跟 Claude Code 的 CLAUDE.md 完全一致：AI 自己能从代码里推断出来的不要写，AI 猜不到的必须写。

该写的：构建测试 lint 命令；与默认不同的代码风格偏好；项目架构决策和技术选型；开发环境的坑和特殊配置；PR 要求和代码审查标准；什么叫「完成」的定义；约束和禁止事项（带替代方案）。

不该写的：「这是一个 Python 项目」（AI 看文件就知道）；语言标准规范（AI 已经掌握）；详细 API 文档（给路径别全文粘贴）；频繁变化的信息（每次都得改的不适合放这里）；文件逐一描述（AI 会自己看文件树）；「写整洁代码」「遵循最佳实践」这种废话；所有人都知道的常识。

六、一个实际的 AGENTS.md 示例

看一个项目级 AGENTS.md 示例（不到 200 字）：

# MyProject

## 仓库结构

- src/ 主代码

- tests/ 测试文件

- scripts/ 构建和部署脚本

## 开发命令

- 安装依赖：pnpm install

- 跑测试：pnpm test（所有测试必须通过再提 PR）

- Lint 检查：pnpm lint

- 构建：pnpm build

## 工程规范

- 使用 TypeScript strict 模式

- 组件用函数式，不用 class

- 新增 API 接口必须写单元测试

- commit message 遵循 Conventional Commits 格式

## PR 要求

- 标题清晰描述改动内容

- 修改了用户可见行为时必须更新文档

- CI 通过后才能合并

## 禁止

- 不要直接修改 generated/ 目录下的文件（它们是自动生成的）

- 不要在代码中硬编码 API 密钥，用环境变量

- 不要跳过 lint 检查

不到 200 字。但每一行都在帮 Codex 避免犯错。「什么叫完成」写清楚了（CI 通过+文档更新），「禁止」项带着原因（generated 目录是自动生成的），这些是 Codex 自己读代码推断不出来的信息。

七、Fallback 文件名怎么配

如果你的项目已经有一个叫 TEAM_GUIDE.md 或者 .agents.md 的文件充当开发规范，不想再多一个 AGENTS.md，可以配置 fallback 文件名：

# ~/.codex/config.toml

project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md"]

project_doc_max_bytes = 65536

配置后 Codex 在每个目录中的检查顺序变成：AGENTS.override.md → AGENTS.md → TEAM_GUIDE.md → .agents.md。不在列表里的文件名会被忽略。上面的配置还顺便把合并大小上限调到了 64KB，适合规则特别多的大型项目。

八、和 Claude Code 的 CLAUDE.md 对比

如果你同时用 Claude Code 和 Codex，这张对比表会有用：

Codex AGENTS.md 在全局配置用 ~/.codex/AGENTS.md，项目配置在仓库根目录。子目录支持 ✅ 逐级向下查找。override 机制 ✅ AGENTS.override.md。Fallback 文件名 ✅ 可配置。大小限制默认 32KB 可调。引用其他文件不支持 @ 语法。快速生成 /init 命令。

Claude Code CLAUDE.md 在全局配置用 ~/.claude/CLAUDE.md，项目配置在仓库根目录。子目录支持 ✅ 逐级向上+向下查找。override 机制 ❌ 无此机制。Fallback 文件名 ❌ 只认 CLAUDE.md。大小限制无明确限制（但过长影响性能）。引用其他文件支持 @ 语法导入。快速生成 /init 命令。

核心思路一样细节上各有取舍。Codex 的 override 机制对团队协作更友好，Claude Code 的 @ 语法在大型项目中组织规则更灵活。

更广一点的趋势：SKILL.md 已经成了跨 Agent 的事实标准，Codex、Claude Code、Cursor、Gemini CLI 共用同一种格式，第三方 skill marketplace 上的 1600+ skills 都按这一套结构组织。你写一个 skill 不再绑死某个工具，今天给 Codex 用、明天复制到 Claude Code 也能跑。AGENTS.md 和 CLAUDE.md 还是各属各家，但 skill 这层的协议已经统一了。

九、验证你的 AGENTS.md 被读到了

写完 AGENTS.md 后怎么确认 Codex 确实读到了？

从项目根目录验证：codex --ask-for-approval never "Summarize the current instructions."

验证子目录的 override 是否生效：codex --cd services/payments --ask-for-approval never "Show which instruction files are active."

查看日志确认加载了哪些文件：cat ~/.codex/log/codex-tui.log

Codex 每次运行都会重建指令链，不存在缓存。如果指令看起来不对，重启 Codex 即可。

十、常见问题排查

Codex 没加载任何指令：确认你在预期的仓库目录中，codex status 检查 workspace root。确认文件非空。

加载了错误的指令：检查目录树上层是否有 AGENTS.override.md，重命名或删除 override 文件。

Fallback 文件名不生效：确认 config.toml 中拼写正确，然后重启 Codex。

指令被截断：提高 project_doc_max_bytes，或把长规则拆分到子目录。

花叔的经验：AGENTS.md 不要写太长，短而准比长而全有用。他自己的写作项目 CLAUDE.md 经过大半年的迭代，核心规则文件控制在 8KB 以内。AGENTS.md 也应该如此。每条规则都应该对应一个真实踩过的坑，而不是提前想象的「万一需要」。从你和 Codex 协作中真正出过问题的地方开始写，一条一条攒，这份文件自然会长成你需要的样子。

下一篇开始拆 §06-08：桌面 App 五件套 + Cloud 异步开发 + Skills / MCP / Automations / /goal 四大扩展能力。这是 Codex 区别于传统 AI 编程工具的高级能力集合，做跨天长任务、自动化工作流、知识工作者场景都在这一篇。

原文信息：Codex 橙皮书 v2.0.1 §05，作者花叔，GitHub alchaincyf/codex-orange-book，CC BY-NC-SA 4.0 协议。

下一篇: 书名解读+5 ❘ 第5篇-AppCloud扩展。下篇看点: AGENTS.md 项目骨架 + 协作规则。