Codex 进阶教程 01｜AGENTS.md 实战：让 Codex 记住你的项目规矩

悠悠空谷1615

236人浏览 · 2026-06-09 18:42:55

悠悠空谷1615 · 2026-06-09 18:42:55 发布

Codex 进阶教程 01｜AGENTS.md 实战：让 Codex 记住你的项目规矩

这是《Codex 进阶教程》系列的第 1 篇。

很多人开始认真用 Codex 之后，都会遇到一个很烦的问题。

比如在今天这个对话线程里，它明明已经知道了：

这个项目用 pnpm
deploy/ 不能乱动
改完前端要先跑测试
改多个文件之前先说范围

结果你换了个线程，或者切到另一个目录，它又像失忆了一样，重新按自己的默认习惯来。

于是你只能再说一遍：

别用 npm
先别碰部署文件
改完告诉我怎么验证
不要顺手加依赖

说白了，AGENTS.md 解决的就是这个问题。

它不是用来写漂亮话的，也不是随手留两句备注，而是一份默认工作说明。把你反复强调的规则写进去，Codex 每次开工前都会先按这个标准执行。

这篇文章我不想讲得太虚，只讲三件事：

什么情况下你就该写 AGENTS.md
到底该把它放在哪
有哪些版本你可以直接复制就用

1. 什么情况下，你就该写一份 `AGENTS.md`

判断方法其实很简单。

如果你最近几天和 Codex 对话时，有一句提醒已经重复说了 3 次以上，那这句话大概率就不该继续留在聊天里了，而该写进 AGENTS.md。

最常见的几类就是这些：

这个仓库统一用 pnpm
改完要先跑哪条测试命令
哪些目录不要碰
新增依赖前先问我
改多个文件前先报范围
先分析再改，不要一上来就大改

你可以把它理解成一句话：

只要一条规则你已经说烦了，它就值得进 AGENTS.md。

很多人一开始总觉得，自己缺的是 prompt 技巧。其实不是。真正让协作变稳的，往往不是你这一次问得有多花，而是哪些规则不用再重新说。

2. AGENTS.md 的三层作用域与加载顺序

这一段一定要搞清楚，不然你文件写了也可能白写。

和 OpenAI 官方文档一致，Codex 大致会按下面这个思路读规则：

第一层：你的全局规则

位置通常在：

~/.codex/AGENTS.md

或者同目录下的：

~/.codex/AGENTS.override.md

这一层适合放你几乎所有项目都通用的习惯。比如：

默认先解释再动手
新增依赖前先确认
改完后告诉我验证方法

第二层：项目根目录规则

比如你的项目在：

C:\work\my-app

那最常见的放法就是：

C:\work\my-app\AGENTS.md

这一层适合放整个仓库都通用的规则。比如：

这个项目统一用 pnpm
前端改完要跑 pnpm test
deploy/ 不要动

第三层：子目录里的局部规则

如果某个子目录有自己特殊的命令、风险或者禁区，就可以在那个目录再放一份：

C:\work\my-app\services\payments\AGENTS.override.md

这层不是每个项目都需要。只有当某个子目录真的“和别的地方不一样”时，才值得单独加。

你先记住这 3 句就够了

如果你不想背加载机制，只记这 3 句就行：

所有项目都通用的习惯，放 ~/.codex/AGENTS.md
整个仓库通用的规则，放项目根目录 AGENTS.md
只有某个目录特殊，才在那个目录再放 AGENTS.override.md

很多人一上来就把事情搞复杂了。其实大多数项目，一开始只需要第 2 层，也就是项目根目录那一份。

3. 先从根目录这一份开始，别一上来搞复杂

如果你现在还没有用过 AGENTS.md，最稳的起手方式不是设计三层结构，而是先在项目根目录放一份最小版本。

比如：

# AGENTS.md

- 这个仓库统一用 `pnpm`，不要切回 `npm`
- 改前端代码后先跑 `pnpm test`
- `deploy/` 和 `scripts/release/` 下面的文件不要动，除非我明确提到
- 如果要新增依赖，先告诉我为什么要加
- 如果准备改多个文件，先把改动范围说清楚再动手
- 默认先分析问题和方案，不要一上来直接大改
- 改完后告诉我影响了哪些文件，以及我该怎么验证

这份东西看起来很普通，但已经够用了。

你会发现它里面写的都不是大道理，而是很具体的工作规则：

用什么包管理器
改完跑什么
哪些目录别碰
什么情况要先说
输出结果时要交代什么

这才是 AGENTS.md 该写的内容。

像“保持代码优雅”“注意可维护性”“遵循最佳实践”这种话，不是不能写，而是写了也没什么实际帮助。它太虚了，真到动手时，Codex 还是不知道你到底希望它怎么做。

4. 实战场景：如何根据项目复杂度放置文件？

这一段我讲直白一点，因为这里最容易让人看完还是不知道怎么放。

场景 1：你的项目不大（绝大多数情况）

如果你的项目就是一个普通 Web 应用，前后端都不复杂，也没有特别多模块，那你先只放这一份：

repo/AGENTS.md

就够了。不要为了“显得专业”就硬拆三层，没有差异，就不要多放文件。

场景 2：只有某个目录特别特殊

比如你的仓库大部分地方都一样，只有 services/payments/ 这个目录很敏感：

它有单独测试命令
里面有 webhook、账单、回调逻辑
你不希望 Codex 在这里顺手乱改

那就这样放：

repo/
  AGENTS.md
  services/
    payments/
      AGENTS.override.md

这时候两份文件分别负责的事情很明确：

repo/AGENTS.md 负责回答：这个项目整体怎么合作？
repo/services/payments/AGENTS.override.md 负责回答：只有到了这个目录，还要额外注意什么？

场景 3：你所有项目都有同一套习惯

如果你发现不管做什么项目，自己都会反复说“先分析再改”、“新依赖前先确认”之类的话，那就可以把它们抽出来放到：

~/.codex/AGENTS.md

这样以后你开别的项目，也不用每次重写一遍。

5. 写完以后，怎么确认它真的读到了

很多人不是不会写，而是写完以后根本没确认 Codex 有没有按自己想的读进去。

最简单的检查方法是直接问它。

如果你使用的是 Codex CLI 工具，可以直接在终端里通过命令行问它。比如在项目根目录下：

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

如果你想看某个子目录的规则有没有生效，就切到那个目录再问：

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

你可以按这个顺序检查：

先在项目根目录问一次
再去特殊子目录问一次
看它回答时有没有把对应规则带上

如果你明明写了，但它没带上，优先检查这几件事：

文件是不是放错目录了
你是不是本来该放 AGENTS.override.md，结果放成了 AGENTS.md
规则是不是其实写在了不该写的那一层

6. 三种最常见的写废方式

第一种：写成口号墙

就像前面提到的，千万不要把它写成口号墙。比如：

保持代码整洁
注意可维护性
写出高质量代码

这些话听起来都没错，但真到干活时，几乎不帮你减少任何沟通成本。

AGENTS.md 里优先写“具体怎么做”，不要优先写“希望它成为一个怎样的工程师”。

第二种：把临时任务写进去

比如今天你在修登录页，就把这种话写进去：

先修 login.tsx，再看 register.tsx

这就不对了。

AGENTS.md 里写的应该是长期规则，不是今天这次任务的待办清单。

今天这个任务说完就过期了，长期规则不会。

第三种：项目变复杂后，依然把所有东西堆在根目录

就像前面说的，项目小的时候放根目录没问题，但当模块变多、差异变大时，还不拆分就会出问题。

比如支付模块和管理后台明明有完全不同的风险点，你还把所有规则都塞在根目录里，最后要么那份文件会越来越长，要么写得很空，谁也约束不住。

所以一句话：

能共用的放根目录，只有特殊目录才单独加一份。

7. 3 个可以直接复制的完整模板

下面这部分你可以直接拿去改。

模板 1：普通前端项目

适合场景：

React / Vue / Next.js / Vite
单仓库前端项目

建议放在：

repo/AGENTS.md

内容：

# AGENTS.md

- 这个仓库统一用 `pnpm`，不要切回 `npm`
- 改代码前先确认相关页面、组件和请求入口在哪，不要一上来直接大改
- 改前端代码后先跑 `pnpm test`
- 如果只是样式或小交互调整，优先做最小改动，不要顺手重构别的组件
- `deploy/`、`scripts/release/` 和 `.env*` 相关文件不要动，除非我明确提到
- 如果要新增依赖，先告诉我为什么要加，以及有没有现有方案可复用
- 如果准备改多个文件，先把改动范围说清楚再动手
- 改完后告诉我影响了哪些文件、页面该怎么验证、有没有潜在回归风险

模板 2：后端 API 服务

适合场景：

Node.js API / Go 服务 / Java 服务 / Python 后端

建议放在：

repo/AGENTS.md

内容：

# AGENTS.md

- 先定位接口入口、调用链和测试方式，再决定怎么改，不要直接重构
- 如果是修 bug，先说明问题最可能出在哪一层，再给最小改动方案
- 改接口或业务逻辑后先跑相关测试；如果没有自动化测试，告诉我最小验证步骤
- `config/`、`deploy/`、密钥配置、生产环境脚本不要动，除非我明确提到
- 涉及数据库结构、迁移脚本或缓存键变更时，先告诉我影响范围和风险，再动手
- 如果要新增依赖，先说明必要性
- 如果改动超过一个模块，先列出准备修改的文件和原因
- 改完后说明影响了哪些接口、该怎么验证、有没有兼容性风险

模板 3：Monorepo / 多模块项目

适合场景：

apps/、services/、packages/
前后端混合仓库

这个场景不要只放一份，推荐最常见的两层写法。

目录结构：

repo/
  AGENTS.md
  apps/
    admin/
  services/
    payments/
      AGENTS.override.md
  packages/

根目录 repo/AGENTS.md：

# AGENTS.md

- 先说明你准备在哪个 app、service 或 package 里改，再动手
- 不要跨多个模块顺手大改，除非我明确要求
- 整个仓库统一先做最小改动，避免无关重构
- 如果要新增依赖，先说明是加在根目录还是子模块里
- 改完后说明影响的是哪个模块，以及对应验证方式
- `deploy/`、CI 配置、发布脚本、环境变量文件不要动，除非我明确提到

支付目录 repo/services/payments/AGENTS.override.md：

# AGENTS.override.md

- 进入这个目录后，先看清支付相关入口、回调链路和测试方式，再决定怎么改
- 支付相关改动优先做最小补丁，不要顺手重构别的业务
- 涉及 webhook、账单、订单状态流转、退款逻辑时，先说明风险点和验证路径
- 密钥轮转、支付配置、生产环境回调地址不要动，除非我明确提到
- 改完后告诉我影响了哪些流程，以及我该怎么验证支付链路

这个模板最重要的点不是“文件多”，而是分工清楚：