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

广大开发者中常遇到类似的情况。明明交代了“只改这一个函数”，Codex 却顺手把旁边的代码也重构了，或者擅自加了一个看起来“很合理”的依赖包。

每次都得在对话里补一句“别改配置文件”“别加依赖”“跑一下测试”。一次两次还行，但如果每个任务都要重复一遍，沟通成本就会上去。

为什么每次临时提示不够

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

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

项目规范、测试命令、禁止修改的目录这些信息，本质上应该属于项目本身。 它们不该是每次对话时临时补充的内容。

AGENTS.md 是什么

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

Codex 每次接手任务前，都会先看一遍这个文件。

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

把它放在项目根目录，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 会读取后者而忽略前者。

这个机制适合用来做临时覆盖。比如某个目录需要一套完全不同的规则，而不想在原有规则上叠加。

四个常见误区

误区一：AGENTS.md 写得太长太杂

有人把项目背景、技术选型理由、团队历史全写进去，结果 Codex 读到真正有用的规则时，注意力已经被稀释了。

AGENTS.md 应该只写 Codex 需要知道的“操作指令”，不是项目文档。保持精简，每条规则一句话说清楚。

误区二：用模糊词

“尽量不要乱改”“最好别加依赖”这类表述，对 Codex 来说太模糊。

更好的写法是：“不要修改 config/ 目录”“不要新增依赖，除非任务明确要求”。越具体，Codex 越容易遵守。

误区三：把一次性需求也写成长期规则

有一次你不想让 Codex 改某个文件，就把这条写进了 AGENTS.md。结果后面所有任务，它都不碰那个文件了。

AGENTS.md 里放的是“长期有效的项目约定”，不是临时的任务限制。一次性需求，放在当次对话的提示词里就好。

误区四：有了规则后不检查 Git Diff 和测试结果

AGENTS.md 只是给 Codex 提供了约束，不代表它永远不会犯错。

规则写得再好，人工审查也不能省。每次修改完，看一遍 Git Diff、跑一遍测试，这是最后的把关。

总结

AGENTS.md 的作用，不是让 Codex 自动变得完美。 它的价值在于，把“你每次都要重复说的话”沉淀为项目规则。

规则越具体，Codex 的修改范围越容易控制。

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