Codex使用AGENTS.md把项目规则写清楚

只想让 Codex 改一个接口返回值，结果它又准备安装依赖、改配置文件、动了不相关模块。问题很多时候不只是模型能力，而是项目规则没有提前说清楚。

广大开发者中常遇到类似的情况——明明交代了“只改这一个函数”，Codex 却顺手把旁边的代码也重构了，或者擅自加了一个看起来“很合理”的依赖包。每次都得在对话里补一句“别改配置文件”“别加依赖”“跑一下测试”。一次两次还行，每个任务都说一遍，沟通成本就上去了。

为什么每次临时提示不够

每次在对话里重复强调项目规范，问题至少有三个：

第一，容易遗漏。测试命令、禁止修改的目录、代码风格要求——这些信息一次说全很难，总有一两条忘记提。第二，重复说明增加负担。同一个项目做十次修改，就要说十遍“测试用 pnpm test”。第三，Codex 每次会话都是从零开始读取上下文，上一轮说过的话，这一轮它不记得。

项目规范、测试命令、禁止修改的目录这些信息，本质上应该属于项目本身，而不是每次对话的临时附赠品。

AGENTS.md 是什么

AGENTS.md 是一个 Markdown 文件，Codex 会在开始处理任务之前读取它。你可以把它理解为放在项目里的长期工作说明书——Codex 每次接手任务前都会先看一遍。

它和 README.md 的区别在于：README 是写给人的，介绍项目是什么、怎么用；AGENTS.md 是写给 Codex 的，告诉它怎么工作、用什么命令、遵守什么约束。

把它放在项目根目录，Codex 每次启动时都会加载里面的规则。不再需要每次都在对话里重复“测试用哪个命令”“不要改哪个目录”——这些规则写进 AGENTS.md，Codex 每次都会读到。

一个可以直接用的 AGENTS.md 示例

在项目根目录创建 AGENTS.md，写入以下内容：

# 项目规则
## 工作流程
- 修改代码之前，先说明修改计划，等确认后再动手。
- 修改完成后，输出 Git Diff，方便人工检查。
## 修改范围
- 只允许修改 `src/` 目录下的代码。
- 不要修改 `config/` 目录下的配置文件，除非任务明确要求。
- 不要修改 `tests/` 目录下的已有测试用例，除非任务明确要求。
## 依赖管理
- 不要新增任何依赖，除非任务明确要求且先说明原因。
## 验证
- 修改完成后，运行 `npm test`（或 `pnpm test`，根据项目实际情况替换）。
- 确保所有测试通过后再提交。
## 禁止事项
- 不要重构无关代码。
- 不要修改格式化工具自动生成的文件。

这个模板覆盖了大多数项目最需要的几条约束。你可以根据自己项目的实际情况调整测试命令和目录名称。

每条规则解决什么问题

“修改前先说明计划” —— Codex 有时候会直接动手，改完了你才发现方向不对。要求它先给计划，相当于多了一道“人工确认”的环节，避免做无用功。

“只允许修改指定目录” —— 这是最直接的限制修改范围的手段。明确告诉 Codex 哪些目录可以动、哪些不能动，能有效避免它改到不该改的地方。

“不要新增依赖” —— Codex 有时候会“贴心”地帮你加一个看起来合理的包，但项目可能有自己的依赖管理策略。这条规则强制它在加依赖之前先说明原因，给你判断的机会。

“不修改配置文件” —— 配置文件（如 .env、config.toml）往往是项目敏感信息所在，不应该被随意改动。

“修改后运行测试” —— 这是验证修改是否正确的最基本手段。把测试命令写进 AGENTS.md，Codex 每次改完代码都会自动跑一遍。

“输出 Git Diff” —— 要求 Codex 在修改完成后展示变更内容，方便你做最后的人工审查。规则再具体，也不能完全代替人工检查。

放在哪里、什么时候需要再加一份更细的规则

项目根目录放一份通用的 AGENTS.md 就够大多数项目用了。

但如果项目里某个子目录有特殊要求——比如 services/payment/ 目录下的代码有独立的测试命令、或者 scripts/ 目录不允许任何自动修改——可以在该子目录里再放一份 AGENTS.md。

Codex 的加载规则是：从项目根目录开始，逐级向下到当前工作目录，把沿途的 AGENTS.md 合并起来。越靠近当前目录的规则，优先级越高。子目录的规则可以覆盖根目录的规则。

另外还有一个 AGENTS.override.md 文件——如果在同一个目录下同时存在 AGENTS.md 和 AGENTS.override.md，Codex 会读取后者而忽略前者。这个机制适合用来做临时覆盖，比如某个目录需要一套完全不同的规则，而不想在原有规则上叠加。

四个常见误区

有人把项目背景、技术选型理由、团队历史全写进去，结果 Codex 读到真正有用的规则时，注意力已经被稀释了。AGENTS.md 应该只写 Codex 需要知道的“操作指令”，不是项目文档。保持精简，每条规则一句话说清楚。

“尽量不要乱改”“最好别加依赖”——这类表述对 Codex 来说太模糊。用明确的指令：“不要修改 config/ 目录”“不要新增依赖，除非任务明确要求”。越具体，Codex 越容易遵守。

有一次你不想让 Codex 改某个文件，就把这条写进了 AGENTS.md。结果后面所有任务它都不碰那个文件了。AGENTS.md 里放的是“长期有效的项目约定”，不是临时的任务限制。一次性需求放在当次对话的提示词里就好。

AGENTS.md 只是给 Codex 提供了约束，不代表它永远不会犯错。规则写得再好，人工审查也不能省。每次修改完，看一遍 Git Diff、跑一遍测试，这是最后的把关。

总结

AGENTS.md 的作用不是让 Codex 自动变得完美，而是把“你每次都要重复说的话”沉淀为项目规则。规则越具体，Codex 的修改范围越容易控制。

下次再遇到 Codex 乱改文件、乱加依赖的情况，不妨先检查一下项目根目录有没有 AGENTS.md，里面的规则够不够具体。