8. AGENTS.md 项目指令

本节目标：搞清楚 AGENTS.md 的作用、编写规范、发现链条和优先级规则，写一份 Codex 真正会遵守的项目指令文件。

AGENTS.md 是你写给 Codex 的一份持久指令。它每次启动、动手干活之前都先读一遍，当成这个项目的背景知识装进脑子。

为什么需要它？因为 Codex 每开一轮都从一张白纸开始。上回你苦口婆心交代的「用 pnpm、别碰 legacy 目录、测试这么跑」，这回它一概不记得。没有 AGENTS.md，你就得每次重新解释一遍。

和 config.toml 的区别

很多人把 AGENTS.md 和 config.toml 搞混。它俩是两套东西：

AGENTS.md：自然语言写的项目规矩，给 Codex 当背景知识读。像手套箱里的驾驶手册—「这辆车用 95 号油」「冬天先热车」
config.toml：机器执行的开关旋钮。像中控台上的实体按钮—空调几度、座椅加热开不开

一个管「记住什么」，一个管「怎么干活」。

Note

AGENTS.md 之于 Codex，约等于 CLAUDE.md 之于 Claude Code—同一个概念，换了个文件名。

发现链条

AGENTS.md 不止一份，它能放在好几个地方，作用范围从大到小。Codex 启动时会把它们串成一条「指令链」。

第一步：全局层

在你的 Codex 主目录（~/.codex）里，Codex 先看有没有 AGENTS.override.md，有就用它；没有才读 AGENTS.md。这一层只取第一个非空文件。

第二步：项目层

从项目根目录（通常是 Git 根）开始，一路往下走到你当前所在的目录。沿途每一个目录里，Codex 按顺序挑：先看 AGENTS.override.md，再看 AGENTS.md。每个目录最多只收一个文件。

第三步：合并

Codex 把找到的这些文件从根到叶依次拼接，中间用空行隔开。越靠近你当前目录的文件，排在拼接结果的越后面，优先级越高。

Tip

两个要点：第一，是「拼接」不是「覆盖」—全局和项目同时生效，不存在写了项目级全局就失效；第二，更近的赢—项目规矩能盖过个人偏好，这正是团队协作想要的。

两个层级：项目级 vs 用户级

层级	放哪	管谁	典型内容
全局	`~/.codex/AGENTS.md`	你这个人的偏好，跨所有项目	「回我话简洁点」「用双引号」
项目	仓库根目录或子目录的 `AGENTS.md`	这个项目或团队的规矩	「测试用 pytest -q」「禁改 migrations」

项目级那份可以提交进 Git，全队共享。队友拉下来也有同一套（前提是队友也信任了这个项目）。

判断一条信息该放哪层，问自己：「这条跟我这个人有关，还是跟这个项目有关？」

AGENTS.override.md

AGENTS.override.md 是 Codex 独有的设计，Claude Code 没有对应物。

它解决什么问题？设想你 ~/.codex/AGENTS.md 里写了一套团队共用的全局约定，今天你接了个临时活，需要整段换掉这套全局指导，又不想删原文件。

AGENTS.override.md 就是一张「以此为准」的便签：它在时，同级的 AGENTS.md 被整个跳过；把它删了，原来那份立刻回来。

典型场景：

全局临时覆写：在 ~/.codex/AGENTS.override.md 写一套临时指导，原文件不动
子目录特殊规则：某个子目录需要跟外面完全不同的规矩

# services/payments/AGENTS.override.md

## 支付服务规则

- 用 `make test-payments` 替代 `npm test`
- 轮换 API Key 前必须先通知安全频道

Warning

override 只在自己那一格里二选一，不会清掉别的目录的指令。整条链的拼接、就近优先规则照旧。如果你发现 Codex 蹦出来一条你压根没写的奇怪指令，第一件事就是顺着目录树往上找有没有谁藏了个 AGENTS.override.md。

该写什么

写「Codex 在每一轮里都该保持的事实」。五类内容：

类别	具体写什么	例子
项目概述	一句话说清这是个啥	「基于 FastAPI 的订单管理后端」
技术栈	语言、框架、数据库	「Python 3.11 / PostgreSQL / pytest」
常用命令	测试、构建、检查怎么跑	`npm run lint`、`make test`
代码约定	风格、命名、必须遵守的写法	「函数必须有类型注解」
明确的不要做	雷区、禁改文件	「禁改 migrations 已有文件」

其中常用命令被参考最频繁—Codex 跑测试、提 PR 前会先来这儿翻命令，省得它瞎猜。禁止清单是防它「聪明但闯祸」的护栏。

不该写什么

新手翻车重灾区，也叫「140 行没人听」问题：

长篇大论的背景：公司介绍、产品愿景、技术选型历史—Codex 写代码用不上，纯占上下文，还把真正有用的规矩稀释了
过时信息：换了包管理器却没更新，里头还写着 npm，反过来误导它
看代码就知道的东西：别复述目录结构、别把 ESLint / Prettier 已定义好的风格再抄一遍。Codex 自己会读代码

Tip

写每一条之前先自问一句：「这条 Codex 看代码能不能自己推出来？能，就删。」这一刀能把一份接手项目的 AGENTS.md 从一百多行砍到几十行。

大小限制

Codex 对 AGENTS.md 的红线跟 Claude Code 不一样—Claude Code 按行数（建议 200 行内），Codex 按字节。

合并后的总大小达到 project_doc_max_bytes 限制（默认 32 KiB）就停止继续加文件。注意这算的是全局 + 项目 + 子目录加一块儿的总和。

# ~/.codex/config.toml
project_doc_max_bytes = 65536  # 调高到 64 KiB

Warning

撑爆 32 KiB 的信号，优先拆子目录或精简内容，而不是硬抬上限。我自己的偏好是优先拆、其次删，实在拆不动才抬 project_doc_max_bytes。

自定义文件名

你仓库里早就有一份 TEAM_GUIDE.md，不想再造一个 AGENTS.md 重复一遍？用 project_doc_fallback_filenames 让 Codex 认你已有的文件名：

# ~/.codex/config.toml
project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md"]

加了之后，Codex 在每个目录里的挑选顺序变成：AGENTS.override.md -> AGENTS.md -> TEAM_GUIDE.md -> .agents.md，取第一个存在且非空的。

Note

不在这个列表里的文件名，Codex 在指令发现这一步一律忽略。想让某个自定义文件被当成项目说明书，必须把它的名字加进去。

一份合格的示例

# my-project - 一个演示用的最小项目

基于 FastAPI 的订单管理后端，只有用来演示 AGENTS.md 怎么写。

## 常用命令

- `npm test` -- 运行测试
- `npm run lint` -- 代码检查

## 编程约定

- 所有函数必须有类型注解
- 字符串一律用双引号

## 注意事项

- 不要新增任何生产依赖，需要时先问我
- 不要修改 migrations 目录下已有的迁移文件

全文十几行，这就是好 AGENTS.md 该有的样子。真实项目也别失控膨胀。

验证 Codex 读到了

官方给了一个特别直接的验证法—让 Codex 把当前生效的指令总结一遍：

codex --ask-for-approval never "Summarize the current instructions."

如果它复述出了你写的那几条（命令、类型注解、双引号、别加依赖），说明这份 AGENTS.md 确实被装进了它的上下文。

Warning

这里的 --ask-for-approval never 只是为了让演示输出干净，不是说平时干活也建议这么用。

把它当反馈回路

我最爱的用法：Codex 对你代码库做了错误假设，别光在对话里纠正（那是一次性的，下轮它又忘），直接让它把这条修正写进 AGENTS.md。

给一个 Python 项目调了两周，AGENTS.md 从空白长到二十来行，全是它踩过、被我逮住、然后自己记下来的坑。现在新会话基本不犯重复错误了。

小结

维度	关键结论
是什么	每轮开工必读的交接清单，就是 `CLAUDE.md` 换了个名
发现链	全局层 -> 项目层（Git 根逐级到当前目录）-> 从根到叶拼接
谁说了算	拼接不覆盖，越靠近当前目录的越晚拼、冲突时占优
override	那一层跳过同级 `AGENTS.md`，但不清掉别处指令
写什么	概述 / 技术栈 / 命令 / 约定 / 禁区，删一切代码能自证的
大小红线	按字节算，合并默认 32 KiB，撑爆优先拆 / 删
两个旋钮	`project_doc_fallback_filenames` 改文件名、`project_doc_max_bytes` 调上限

下一章讲模型选择和推理强度调节—该派哪个模型去跑你的活儿。