为什么你需要 AGENTS.md
你有没有过这种经历：每次跟 Codex 开一个新会话，都要先重复一遍「这个项目用 pnpm」「测试命令是 xxx」「别改 src/core 目录」？
AGENTS.md 就是解决这个问题的。它让 Codex 在每次会话开始时自动读取项目规则，从此不用反复交代。
一句话总结：AGENTS.md = 项目说明书，Codex 每次开工前必读。
AGENTS.md 在哪三个地方生效
Codex 会从三个层级读取 AGENTS.md，越具体越优先（后面的覆盖前面的）：
| 层级 | 路径 | 适用范围 |
|---|---|---|
| 全局 | ~/.codex/AGENTS.md |
所有项目通用（你的个人偏好） |
| 项目根 | 项目根目录/AGENTS.md |
当前仓库所有子目录 |
| 子目录 | 项目子目录/AGENTS.md |
仅该目录及子目录 |
关键：Codex 从根目录到当前工作目录逐层读取，越靠近当前目录的规则越靠后、优先级越高。
最小可用模板（直接复制）
在项目根目录创建 AGENTS.md，粘贴以下内容：
# AGENTS.md
## 开发命令
- `pnpm install` — 安装依赖
- `pnpm test` — 运行测试（必须全部通过才算完成）
- `pnpm lint` — 代码检查
## 项目结构
- `src/` — 源码
- `tests/` — 测试文件
- `src/generated/` — 自动生成代码，不要手动编辑
## 边界规则
- **必须做**：每次改动后跑测试和 lint
- **先问我**：新增 npm 依赖、修改 prisma/schema.prisma
- **绝对禁止**：直接推 main 分支、提交 .env 文件
保存后，下次开新会话 Codex 就会自动读取这些规则。
全局偏好：只写一次，永远生效
如果你想让 Codex 在所有项目里都遵守某些习惯（比如「用 pnpm 不用 npm」「添加依赖前必须确认」），写到全局：
mkdir -p ~/.codex
然后在 ~/.codex/AGENTS.md 写：
# 全局偏好
## 包管理
- 优先用 pnpm，不要用 npm
## 依赖变更
- 添加新的生产依赖前，必须先询问用户
## 提交规范
- 使用 Conventional Commits 格式
这样不管你在哪个仓库工作，Codex 都会按这个标准来。
迭代方法：Codex 犯错 → 补进 AGENTS.md
AGENTS.md 不是一次写完就结束的。官方推荐的「反馈回路」：
- Codex 犯了一个错（比如改了不该改的文件）
- 你纠正它
- 让 Codex「顺手更新 AGENTS.md，把这条规则加进去」
- 下次不会再犯同样的错
记住：AGENTS.md 是你的 Codex 团队新人的「入职手册」。每纠正一次，手册就更新一次。
什么时候需要 AGENTS.md？
- Codex 反复犯同一个错误 → 补一条规则
- 它读太多无关文件 → 在 AGENTS.md 里指引路径（「优先看 src/ 和 docs/」）
- 每次重复说同样的项目约定 → 固化到文件里
反之，如果只是一个临时任务，不需要写 AGENTS.md，直接给提示词就行。
常见误区
误区1：AGENTS.md 是提示词 不是。它是持久化的项目规则，每次新会话自动加载。临时指令还是放对话里。
误区2：写得越细越好 不是。越长越稀释重点。只写「Codex 每次会话必须知道的事」。
误区3：装了 MCP 才需要 AGENTS.md 不是。MCP 接外部工具，AGENTS.md 管内部规则，两者互补。
来源：OpenAI 官方文档（developers.openai.com/codex/guides/agents-md）、AI Indeed 社区解析
资料最后核对日期：2026-08-25 · 内容整理自 CodexGuide 社区公开教程