Codex 的 7 个 AGENTS.md 技巧，让你的 AI 程序员秒懂项目
你是不是也遇到过这种场景？让 Codex 帮忙改个代码，结果它一上来就乱跑测试、乱改文件，甚至把你不想动的模块也重构了一遍。😤 别急着骂 AI，很可能是你没告诉它项目的规矩。
今天咱们不聊高大上的 Agent 架构，就聊一个特别实用的小文件——AGENTS.md。它能让 Codex 从一个"愣头青"变成"老司机"。下面这 7 个技巧，是我从实战里总结出来的，建议收藏。
## 1. 先搞懂：AGENTS.md 到底是啥？
一句话：README.md 是给人看的，AGENTS.md 是给 AI 看的。
README 告诉你仓库是干嘛的，AGENTS.md 告诉 Codex 这个仓库有哪些规矩：怎么启动、跑什么测试、哪些目录不能碰、能不能加依赖。**Codex 每次进入项目都会自动读它**，相当于给 AI 配了一本"员工手册"。
注意文件名，建议统一写成 `AGENTS.md`，别写成 `Agent.md` 或 `agents.md`，大小写不一致可能导致加载失败。
## 2. 全局 AGENTS.md：放你的"个人偏好"
如果你希望 Codex 不管在哪个项目里都遵守一些底线，那就放在全局配置里：
```
~/.codex/AGENTS.md
```
比如：默认用中文回复、改代码前先读相关文件、不要覆盖用户已有改动、新增生产依赖前先确认。这些规则不依赖具体仓库，换任何项目都成立。
怎么验证生效了？跑一条命令：
```
codex --ask-for-approval never "Summarize the current instructions."
```
如果输出里出现了你写的规则，就说明 Codex 已经读进去了。✅
## 3. 项目级 AGENTS.md：写清这个仓库的"工程规矩"
全局规则管的是"人"，项目规则管的是"事"。
比如你的项目用 Prisma（一个数据库工具），改完 `schema.prisma` 后必须跑 `pnpm db:generate` 重新生成客户端。这种规则就不适合放全局，因为不是每个项目都用 Prisma。**判断标准很简单：换一个项目还成立，放全局；只在这个仓库成立，放项目根目录。**
项目级 AGENTS.md 一般放在 `repo/AGENTS.md`，里面写清楚：安装命令、启动命令、测试命令、lint 命令、目录结构、哪些生成文件不能手改等等。
## 4. 子目录 AGENTS.md：管好 monorepo 里的"小团队"
现在很多项目是 monorepo，一个仓库里可能有前端、后端、支付、搜索。每个模块的风险点不一样，这时候就可以在子目录放自己的 AGENTS.md。
比如 `services/payments/AGENTS.md` 里可以写：禁止记录卡号、token 等敏感信息；改支付逻辑必须跑 `pnpm test payments`。这样 Codex 进入不同子目录时，会自动加载更细的规则。
## 5. AGENTS.override.md：更高优先级的"强覆盖"
有时候你不想让某个子目录遵守根目录的规则，或者想临时替换规则，可以用 `AGENTS.override.md`。
它的优先级比同目录下的 `AGENTS.md` 更高。**如果两个文件同时存在，Codex 会忽略 `AGENTS.md`，只读 `AGENTS.override.md`。** 适合安全要求特别高的服务，或者临时切换测试命令等场景。
## 6. 自定义 fallback 文件名：兼容团队已有文档
有些团队已经写好了 `TEAM_GUIDE.md` 或 `.agents.md`，不想改名。没关系，可以在 `~/.codex/config.toml` 里配置：
```toml
project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md"]
project_doc_max_bytes = 65536
```
这样 Codex 就会按顺序查找这些文件。`project_doc_max_bytes` 是限制合并后的大小，规则太多可以调大。
## 7. 生产级模板：直接抄作业
最后分享一个我常用的生产级 AGENTS.md 思路。这份模板不绑定技术栈，核心是让 Codex 有"工程纪律"：
- **先读再写**：动手前先读 README、CI 配置，搞清楚真实命令。
- **最小改动**：不要顺手重构、重命名、格式化没动过的代码。
- **验证要实**：跑项目定义的测试和 lint，跑不了要说明原因，别假装跑过。
- **依赖要问**：新增生产依赖前必须解释为什么现有工具不够用。
- **安全红线**：不提交密钥，不打印敏感信息，改数据要谨慎。
- **报告要清**：结束时说清楚改了哪些文件、怎么验证的、有什么风险。
你可以把这份"纪律"直接放进项目根目录的 AGENTS.md，再叠加自己项目的具体命令。比如加上"改完 Prisma schema 跑 `pnpm db:generate`"、"API 变更要更新 docs/api"等等。
## 最后说两句
AGENTS.md 不是写作文，别放什么"代码要优雅"这种空话。**要写能影响 Codex 行为、能被命令验证的规则。** 从全局到项目，从项目到子目录，层层递进，你的 Codex 才能真正懂项目。
赶紧去给你的项目建一个 AGENTS.md 吧！如果你有更好的写法，欢迎在评论区聊聊。🚀