写好 AGENTS.md：六场景模板，少让 Agent 走偏

一、真正解决的是什么

Codex 在陌生仓库里最容易遇到的，不是不会写代码，而是不知道团队的「默认答案」。

例如：

• 这个项目用 pnpm、npm 还是 yarn？
• 单元测试和集成测试分别怎么跑？
• 改接口时，是否必须同步 OpenAPI 文档？
• 数据库迁移能不能自动执行？
• 前端应该复用哪个组件库？
• 完成任务的标准是「代码写完」，还是「测试、文档和兼容性检查全部通过」？

这些信息往往散落在 README、CI 配置、团队 Wiki 和老员工的经验里。Codex 如果找不到，只能根据常见做法猜。猜对了是效率，猜错了就是返工。

AGENTS.md 的价值，就是把这些隐性的工程共识变成可重复加载的项目上下文。

按照 Codex 官方文档，Codex 会在开始工作前读取适用的 AGENTS.md。它可以同时使用三种层级：

• ~/.codex/AGENTS.md：个人在所有仓库通用的习惯。
• 仓库根目录的 AGENTS.md：整个项目共享的规则。
• 子目录里的 AGENTS.md 或 AGENTS.override.md：某个服务、包或模块的局部规则。

Codex 会从项目根目录一路读取到当前工作目录，越靠近当前目录的规则优先级越高。换句话说，根目录负责「共同宪法」，子目录负责「地方条例」。

这也是写好 AGENTS.md 的第一个关键：不要试图用一份巨型文件解释整个世界，要让规则跟着代码的边界走。

二、六条原则

1
- 修改 TypeScript 文件后运行 `pnpm lint` 和 `pnpm typecheck`。
2
- 新增业务逻辑时，在同目录补充 `*.test.ts`。
3
- 单个函数超过 60 行时，优先拆分；不要仅为满足行数机械拆分。

1
### Verification
2

3
- 文档改动：运行 `pnpm lint:docs`。
4
- 单个包改动：运行 `pnpm --filter <package> test`。
5
- 共享类型或公共包改动：运行 `pnpm test:affected`。
6
- 如果本地缺少依赖或服务，说明未运行的检查、原因和潜在风险；不要声称验证通过。

1
### Guardrails
2

3
- 未经明确要求，不新增生产依赖。
4
- 不修改已经发布的数据库迁移；需要变更时创建新的迁移文件。
5
- 不读取、输出或提交 `.env`、密钥及真实客户数据。
6
- 不执行生产部署、数据删除、密钥轮换和远程 Git 推送。

1
### Repository map
2

3
- `apps/web/`：Vue 3 管理端。
4
- `services/api/`：Node.js API 服务。
5
- `packages/contracts/`：前后端共享类型，改动可能影响所有应用。
6
- `docs/architecture.md`：系统边界与关键设计决策。
7
- `docs/review.md`：代码审查清单。

1
repo/
2
├── AGENTS.md
3
├── apps/web/
4
│   └── AGENTS.md
5
└── services/payments/
6
    └── AGENTS.override.md

三、可直接改的通用模板

下面这份模板适合大多数中小型项目。复制之后，请删除不适用的内容，并把占位命令替换为仓库中真实可运行的命令。

（图卡把骨架收成七段：项目说明 / 仓库地图 / 命令 / 验证 / 边界 / 完成标准 / 审查规则。下面完整模板另含 Working rules、Coding conventions 等可删改栏目。）

1
## AGENTS.md
2

3
### Project overview
4

5
- 本仓库用于：<一句话说明产品或服务>。
6
- 主要技术栈：<语言、框架、运行时>。
7
- 包管理器：<pnpm/npm/yarn/uv/poetry 等>。
8
- 修改前先阅读：`README.md`、`docs/architecture.md`。
9

10
### Repository map
11

12
- `src/`：核心业务代码。
13
- `tests/`：自动化测试。
14
- `docs/`：架构与使用文档。
15
- `<关键目录>`：<职责及影响范围>。
16

17
### Working rules
18

19
- 修改前先阅读相关实现和测试，不根据文件名猜测行为。
20
- 优先做满足需求的最小改动，避免顺手重构无关代码。
21
- 遵循现有结构、命名和错误处理方式。
22
- 未经明确要求，不新增生产依赖，不改变公共 API。
23
- 发现需求与现有实现冲突时，先说明证据和影响，再决定是否继续。
24

25
### Commands
26

27
- 安装依赖：`<command>`
28
- 启动开发环境：`<command>`
29
- 代码检查：`<command>`
30
- 类型检查：`<command>`
31
- 单元测试：`<command>`
32
- 完整测试：`<command>`
33

34
### Coding conventions
35

36
- <语言或框架相关约定>。
37
- <文件命名、导入、异常处理约定>。
38
- 新增或修改公共接口时，同步更新类型、测试和文档。
39
- 不为了"更整洁"修改与任务无关的格式或代码。
40

41
### Testing and verification
42

43
- Bug 修复必须补充能够复现问题的回归测试。
44
- 新功能至少覆盖主路径和一个失败路径。
45
- 先运行受影响范围的测试；共享模块变更再运行完整测试。
46
- 无法运行检查时，明确列出未验证项、原因和风险。
47

48
### Guardrails
49

50
- 不提交密钥、令牌、`.env` 或真实用户数据。
51
- 不执行生产部署、远程推送、数据删除或不可逆操作。
52
- 不修改已发布的迁移文件；创建新的迁移。
53
- 发现疑似安全问题时停止扩散敏感信息，只报告必要细节。
54

55
### Definition of done
56

57
- 请求的行为已经实现，且没有夹带无关改动。
58
- 相关测试、lint 和类型检查通过。
59
- 必要的文档、示例、类型和迁移已同步。
60
- 最终说明包含：改了什么、如何验证、仍有哪些风险。
61

62
### Review guidelines
63

64
- 优先检查正确性、回归风险、安全性和兼容性。
65
- 指出问题时给出文件位置、触发条件和影响。
66
- 不把纯风格偏好当作阻塞问题。

这份模板最重要的部分并不是标题数量，而是每条规则都能落到一个动作、一个边界或一个验收结果上。

四、六个场景的局部规则

通用模板解决的是底座，真正让 Codex 变得稳定的，往往是与业务场景贴合的局部规则。

1
### Feature development
2

3
- 实现前先查找同类功能，沿用现有分层和数据流。
4
- 优先扩展现有模块，不新建平行抽象，除非现有设计无法满足需求。
5
- 修改公共 API 时，同步更新 schema、客户端类型、测试和变更说明。
6
- 新功能必须覆盖成功路径、权限失败和无效输入。

1
### Bug fixes
2

3
- 修改实现前，先用现有日志、调用链或测试证明根因。
4
- 能稳定复现时，先添加失败的回归测试，再修改代码。
5
- 修复应针对根因，不通过吞掉异常、扩大重试或删除校验掩盖问题。
6
- 如果无法复现，列出已验证事实、假设和仍需观测的数据。

1
### Monorepo scope
2

3
- 修改前检查目标包的 `package.json`、依赖方和局部 `AGENTS.md`。
4
- 包内改动先运行 `pnpm --filter <package> test`。
5
- 修改 `packages/contracts/`、`packages/config/` 或公共类型后，运行 `pnpm test:affected`。
6
- 不修改无关包的锁文件、生成物或格式。

1
### Database changes
2

3
- 不修改已经在任何环境执行过的迁移文件。
4
- 破坏性 schema 变更采用 expand-migrate-contract 三阶段，不在一次发布中删除旧字段。
5
- 迁移必须说明回滚或前向修复方案，并评估锁表和大表扫描风险。
6
- 只生成和测试迁移；未经明确授权，不连接生产库、不执行生产迁移。

1
### Frontend work
2

3
- 优先复用现有设计令牌和组件，不创建近似重复组件。
4
- 页面必须处理 loading、empty、error 和 disabled 状态。
5
- 交互元素支持键盘操作，并保留可见焦点状态。
6
- 至少检查 375px、768px 和 1440px 三个宽度。
7
- 视觉改动提供截图或明确说明人工检查路径。

1
### Review guidelines
2

3
- 优先报告正确性、安全性、数据损坏、兼容性和明显性能回归。
4
- 每个问题说明触发条件、用户或系统影响，并标注具体文件位置。
5
- 检查新增行为是否有测试，测试是否真的覆盖失败场景。
6
- 不报告现有代码中的无关问题，不把个人风格偏好列为缺陷。
7
- 如果没有发现问题，明确说明仍未覆盖的测试或环境风险。

五、五个反模式

把临时需求写成永久规则
「这次不要改登录页」属于当前任务提示，不属于项目长期约定。把一次性的限制写进 AGENTS.md，几周后就会变成过期信息。

只写风格，不写命令
用了两页篇幅描述命名偏好，却没有一句告诉 Codex 如何运行测试。这类文件看似完善，实际无法支撑任务从输入到验证的完整流程。

命令已经失效
错误命令比没有命令更糟。CI、包管理器或目录结构变化时，应把 AGENTS.md 纳入同一个 Pull Request 更新。

根目录承载所有差异
当根文件充满目录条件和例外，说明规则应该下沉。利用子目录文件表达局部约束，比在一个大文件里维护复杂分支更稳。

把软要求写成绝对命令
「永远不要重构」「所有改动必须跑全量测试」可能让 Codex 在简单任务上付出巨大成本。更好的表达是说明触发条件、例外和优先级。

六、怎么确认它真的生效

不要凭感觉判断。可以在仓库根目录启动一次新会话，让 Codex 复述当前加载的规则：

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

如果项目使用了子目录覆盖，再从目标目录检查：

1
codex --cd services/payments --ask-for-approval never \
2
  "List the instruction sources you loaded and summarize the effective rules."

你需要确认三件事：

1. 它加载了正确的文件；
2. 局部规则覆盖了冲突的上层规则；
3. 最关键的构建、测试和安全边界没有被遗漏或截断。

Codex CLI 也提供 /init 来生成初始的 AGENTS.md。它适合解决「从零开始」，但生成之后仍要根据项目真实的构建、测试、审查和发布流程进行删改。脚手架只能提供栏目，不能替团队补上工程事实。

短、准、可验证就够起步

高质量 AGENTS.md 的本质，不是写一份更复杂的提示词，而是把团队的工程判断变成 Codex 能稳定执行的上下文。

它应该短、准、可验证：告诉 Codex 项目在哪里，命令怎么跑，边界在哪里，以及做到什么程度才算完成。

如果你不知道从哪里开始，就先写下四项内容：仓库地图、常用命令、不可触碰的边界、完成标准。等 Codex 第二次犯下同一种错误，再把那次教训补进去。

时间久了，这份文件会变成项目里很特别的一类资产：它记录的不是代码本身，而是团队希望代码如何被理解、修改和交付。

两个文件怎么站位

只吃 Claude Code → 维护 CLAUDE.md 就够。多工具混用 → 优先 AGENTS.md，或两份共存、内容按工具微调。

CLAUDE.md 的层级（从近到远）

1. 当前目录 CLAUDE.local.md（私有，勿提交）
2. 当前目录 CLAUDE.md（项目共享）
3. 父目录 CLAUDE.md（Monorepo 继承）
4. ~/.claude/CLAUDE.md（全局）

在 packages/frontend/ 干活时，会叠读子包 + 根目录配置。团队约定进 CLAUDE.md，个人偏好进 CLAUDE.local.md。

该写什么（两边差不多）

少写宣传稿，多写「命令 + 红线」：

• 常用命令：dev / build / test / lint / typecheck / db
• 代码风格与命名（ESM vs CJS、PascalCase 组件等）
• 目录地图与关键入口文件
• Git / PR 约定
• 环境变量前缀、禁止硬编码、统一走哪层封装
• 高频 FAQ（装依赖、连库失败之类）

语气可以硬一点：IMPORTANT / YOU MUST / NEVER 对关键红线有效。Claude Code 对话里按 # 能把当轮结论追加进 CLAUDE.md；/init 能生成骨架，但别指望骨架够用。

AGENTS.md 的就近原则

聊天里的直接指令 > 离当前编辑文件最近的 AGENTS.md > 根目录 AGENTS.md。Monorepo 按 web / api / shared 各放一份，比堆一个巨型根文件干净。

和 CLAUDE.md 比：内容都是自由 Markdown；差别主要在工具覆盖面和优先级细节（CC 有 local 覆盖与全局档）。

写薄还是写厚

别一次灌满。像调 Prompt：先放命令和三条红线，跑几轮再补架构说明。配置越长，越容易互相打架、越吃上下文。能拆子目录就拆。

相关阅读

• Cursor 规则别瞎塞：三层各管各的
• 还在「会聊天」阶段，就别指望 Vibe 封神

素材来源：CSDN 原文