Codex 教程：用 AGENTS.md 给编程助手写一份项目说明书

用 Codex 写代码一段时间后，很多人会发现自己总在重复同样的话：「测试用 pnpm 跑」「改完先跑 lint」「这个目录别动」。与其每次写进提示词，不如把它们写进一个叫 AGENTS.md 的文件。Codex 每次开始工作前会自动读取它，相当于给编程助手准备了一份项目说明书。

AGENTS.md 是什么

OpenAI 官方把 AGENTS.md 形容为「写给智能体看的 README」，是一种开放格式的普通 Markdown 文件。人看 README 了解项目，Codex 看 AGENTS.md 了解你的项目该怎么构建、怎么测试、有哪些规矩。

文件可以放在三个地方

1. 全局：放在 Codex 的主目录里，默认是 ~/.codex/AGENTS.md（设置了 CODEX_HOME 环境变量时以它为准）。写你个人的工作习惯，对所有项目都生效。
2. 项目根目录：一般就是 Git 仓库的根目录。写整个项目通用的规范。
3. 子目录：某个模块有特殊要求时，在那个目录里单独放一份。

Codex 从项目根目录一路往下走到你当前所在的目录，每一层最多读一个文件，然后从上到下拼接起来。离当前目录越近的文件排在越后面，内容冲突时以它为准。空文件会被跳过。

用 override 文件临时覆盖

在同一个目录里，Codex 先找 AGENTS.override.md，没有才读 AGENTS.md。所以想临时换一套规则又不想改原文件时，新建一个 override 文件就行，用完删掉即可恢复。

官方示例是这样的：

• ~/.codex/AGENTS.md：改完 JavaScript 后跑测试、优先用 pnpm、加生产依赖前先确认；
• 仓库根目录 AGENTS.md：提交合并请求前先跑 lint；
• services/payments/AGENTS.override.md：这个服务用 make test-payments，不用 npm test。

一份 AGENTS.md 写什么

官方最佳实践建议覆盖这几项：

• 项目目录结构，各部分放什么；
• 怎么运行项目；
• 构建、测试、lint 的具体命令；
• 代码风格和约定；
• 明确不能做的事；
• 改完后怎样验证结果。

一个简单的例子：

# 项目说明

## 常用命令
- 安装依赖：pnpm install
- 运行测试：pnpm test
- 代码检查：pnpm lint

## 约定
- 新功能必须附带测试
- 不要修改 migrations/ 目录下已有的文件

## 完成标准
- 测试和 lint 全部通过后再结束任务

不想从零写，可以在 Codex 命令行里运行 /init，它会在当前目录生成一份初稿，再按自己的项目修改。官方建议保持简短；当 Codex 反复犯同一个错误时，让它自己总结原因，再把结论补进 AGENTS.md。

注意大小上限

所有 AGENTS.md 拼接后的总大小，默认上限是 32 KiB（配置项 project_doc_max_bytes）。达到上限后，Codex 不再读取后面的文件。内容多时，要么调高上限，要么把规则拆到各个子目录里。

想用别的文件名

团队已经有自己的说明文件时，可以在 ~/.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。不在列表里的文件名一律不读。

怎么确认规则生效了

在项目根目录运行：

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

想看某个子目录加载了哪些文件：

codex --cd services/payments --ask-for-approval never "List the instruction sources you loaded."

正常的顺序是：全局文件、根目录 AGENTS.md、子目录的文件。

规则没生效时，按这几点排查：

• 什么都没读到：确认当前目录对不对、文件是不是空的；
• 读到了意外的规则：往上层目录和 Codex 主目录里找找有没有 AGENTS.override.md；
• 备用文件名不生效：检查 project_doc_fallback_filenames 的拼写，并重启 Codex；
• 内容被截断：调高 project_doc_max_bytes 或拆分文件。

上手建议

• 先在常用项目的根目录运行 /init，生成初稿后只保留真正重要的几条。
• 把「怎么跑测试」写清楚，这是最能减少返工的一条。
• 个人习惯放全局文件，项目规范放仓库里，并提交到 Git，让团队成员共用。
• 官方仓库建议用 Plus、Pro 等套餐的 ChatGPT 账号登录 Codex，还没有会员的，可以在 BuyBuy代充（buybuytopup.cn） 开通 ChatGPT Plus，开通后就能按本文给自己的项目配上 AGENTS.md。