AGENTS.md 怎么写？让 Codex 读懂你的项目规范和开发习惯

每次 Codex 改完代码说”完成了”，你跑 pnpm test 才发现没跑测试；或者在 monorepo 根目录，它跑的是另一个 package 的测试。这类重复解释很费时间：npm run build、pnpm test、不要改 generated 目录、补完要跑 lint。AGENTS.md 就是把这些规则写进项目里，让 Codex 第二次就不用再问。

如果你刚跑通 Codex 入门和入口选择，下一步不是让它重构整个项目，而是先把这些重复口头交代沉淀下来。

先给你 12-20 行的种子版骨架，再解释三层加载机制、怎么验证生效、什么不该写进去、已有 CLAUDE.md 或 Cursor Rules 时如何共存，以及什么时候该更新。

AGENTS.md 不是 README，是 Codex 的”长期工作说明书”

README.md 写给人类读者，讲项目是什么、怎么安装、怎么上手。AGENTS.md 写给 Codex，讲的是每次启动时都会自动加载的规则：怎么构建、怎么测试、哪些目录不能碰、提交前要做什么检查。

根据 OpenAI 官方文档，Codex 在开始工作前会读取 AGENTS.md 并把它作为上下文的一部分。这和你每次在聊天里重复交代”npm run build""pnpm test”不同：AGENTS.md 是持久的项目指导，不用每次手动输入。

但要澄清一个边界：AGENTS.md 不是长期记忆系统，不是会自动学习的知识库。它只是每次启动加载的静态指导文件。如果你想跨会话积累知识、治理项目记忆，可以看之前写的 AI Agent 记忆管理，那里讲了长期记忆和项目规则的分工。

Codex 怎么发现你的 AGENTS.md？（三层加载机制）

Codex 的读取顺序分三层：全局层、项目层、合并层。理解这个机制能帮你判断规则在哪生效、为什么有时候好像没生效。

全局层：你个人的通用习惯

Codex 会先在你的用户目录 ~/.codex 下找文件。这一层放的是你个人的通用习惯，比如默认用中文回复、代码风格偏好、常用工具习惯。注意：全局层最多读一个文件，按 AGENTS.override.md -> AGENTS.md 的顺序，不会叠加。

项目层：从 Git 根向当前目录逐层扫描

项目层从 Git 根（或项目根）向当前工作目录扫描。每层也按 AGENTS.override.md -> AGENTS.md -> fallback filenames 的顺序最多读一个。fallback 文件名可以通过 project_doc_fallback_filenames 配置（比如加入 TEAM_GUIDE.md），具体配置项名称以官方文档为准。

合并顺序：越近目录越后出现，优先级越高

所有找到的文件按从根到当前目录的顺序拼接。越近目录的规则越后出现，在上下文里位置越靠后，Codex 越容易优先采纳。

举个例子：monorepo 项目根目录有 AGENTS.md，写的是”测试命令用 pnpm test”；apps/web/AGENTS.md 写的是”测试命令用 pnpm --filter web test”。当你在 apps/web 目录启动 Codex，它读到的顺序是：根目录规则 -> apps/web 规则。apps/web 的测试命令会出现在上下文后面，更容易被采纳。

三层加载机制总结表

层级	路径范围	文件优先级	用途建议
全局层	~/.codex/	AGENTS.override.md -> AGENTS.md（最多读一个）	个人通用习惯，不签入仓库
项目层	Git 根 -> 当前目录	每层按 AGENTS.override.md -> AGENTS.md -> fallback 最多读一个	项目规则，根目录放通用，子目录放特殊要求
合并层	从根到当前目录依次拼接	越近目录越后出现，优先级越高	monorepo 里具体指导覆盖通用规则

建议：根目录放团队共享的通用规则，子目录放特殊要求（比如某个 package 用不同的测试命令）。AGENTS.override.md 适合临时或局部覆盖，不要把它当成团队默认；否则规则会被隐藏在 override 里，团队协作时容易混乱。

最小种子模板：先写哪 6 块？

OpenAI 官方建议把 AGENTS.md 写成”open-format README for agents”，核心是写短、写真、写可验证。不要直接复制网上 300 行的大模板，先写 6 个基础块，再按需要逐块扩展。

种子版骨架包含这 6 块：

1. repo layout：技术栈和目录结构，让 Codex 知道前端后端在哪、用什么框架
2. Commands：具体的构建、测试、lint 命令（不要写”跑一下测试”，要写 pnpm test）
3. Constraints：不要改哪些目录、不要做什么事（比如不要改 src/generated/）
4. PR expectations：提交前要做什么检查、review 时要补什么
5. Done when：什么情况才算完成（比如 pnpm test 通过、pnpm build 成功）
6. 如果有特殊约定，比如包管理器、代码风格、命名规范，可以加一小段

下面是一个 SaaS 管理后台项目的种子版示例：

# AGENTS.md

## Repo layout
- Frontend: React + TypeScript + Vite (src/)
- Backend: Node.js + NestJS (server/)
- Database: PostgreSQL
- Package manager: pnpm

## Commands
- Install: pnpm install
- Dev: pnpm dev
- Build: pnpm build
- Test: pnpm test
- Lint: pnpm lint

## Constraints
- Do NOT edit src/generated/ (auto-generated code)
- Do NOT commit migrations/ without team review

## PR expectations
- Add tests for new features
- Run `pnpm test` before marking done

## Done when
- `pnpm test` passes
- `pnpm build` succeeds

这个模板够短，不会污染上下文。先写这 6 块，后面遇到问题再逐块扩展。不要一开始就塞进项目愿景、依赖列表、架构图、API 文档索引，那会让文件变长，反而降低 Codex 对核心规则的注意力。

怎么确认 Codex 真的读了你的 AGENTS.md？

写完 AGENTS.md 后，可以用一个验证命令确认是否生效。OpenAI 官方推荐的命令是：

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

这个命令会让 Codex 总结它当前加载的指导。如果输出里包含你写的规则（比如测试命令、不要改的目录），说明生效；如果输出里完全没提到，或者提到的是别的规则，就需要排障。

排障清单

检查项	可能原因	处理方法
文件名大小写	文件名不是 AGENTS.md（比如写成 Agent.md、agents.md）	改成 AGENTS.md，大写 A 和全大写后缀
版本过旧	旧版本有 symlink/NFS/mount 路径问题（v0.138+ 有修复，版本号以官方为准）	升级到最新版本
路径遮挡	项目路径是 symlink、NFS 挂载或 bind mount，遮挡发现链	检查启动目录是否在真实路径下；必要时直接在物理路径启动
被覆盖	AGENTS.override.md 或子目录规则覆盖了你的规则	检查当前目录和全局目录是否有 override 文件；检查子目录是否写了同名文件
大小上限	文件超过默认大小上限（默认 32 KiB，具体值以官方文档为准）	精简文件，删掉易过期清单和大段描述
启动目录错误	Codex 从错误目录启动，影响项目层扫描范围	确认启动目录是否在 Git 根或你想的子目录下；用 --cd 指定目录

如果排障后仍不生效，建议查阅 OpenAI 官方 Custom instructions 文档或升级到最新版本。不要相信”一定生效”的说法；Codex 的读取机制有路径、版本、配置等多层因素，排障清单能解决大部分常见问题。

什么不该写进 AGENTS.md？

AGENTS.md 不是万能仓库。有些东西写进去会带来安全风险、维护负担或上下文污染，需要明确禁止。以下是不可写项清单：

1. 密钥、API key、生产密码

安全风险。任何密钥、生产环境密码、API token 都不应写进 AGENTS.md。Codex 读取的文件可能被多人看到，甚至签入 Git 仓库。密钥管理应走环境变量、.env 文件（不签入）、或专用的 Secrets 系统。如果你需要 Codex 在沙箱环境用密钥，可以看后续”权限、沙箱、密钥管理”专题，那里讲了执行层约束。

2. 易过期大清单

维护风险。不要写依赖列表、生态数字、价格、额度等会频繁变化的信息。比如”当前依赖有 React 18.2、Vue 3.4、TypeScript 5.0……”这类清单，过几个月就会过时。应该写”如何新增依赖”的流程，而不是列举所有依赖；应该写”检查 Lighthouse 分数是否低于 90”，而不是列举某个具体分数。

3. 抽象口号

无法执行。比如”保持高质量""写优雅代码""确保代码可维护”。这些口号 Codex 无法具体执行。应该写验收标准：pnpm test 通过、pnpm lint 无报错、新增功能补测试、Lighthouse 分数不低于 90。

4. 模糊命令

不够具体。比如”跑一下测试""检查构建”。应该写具体命令：pnpm test、pnpm build、lighthouse --preset=desktop。

5. 不可验证的要求

无法验收。比如”保证性能提升""确保用户体验更好”。这类要求没有明确的验收标准。应该写可验证的命令或结果：新增 API 响应时间不超过 200ms（用 curl 或 APM 工具测）；Lighthouse Performance 分数不低于 90。

6. 个人偏好

不要写进仓库根。比如”用中文回复""回复长度不超过 100 字""默认用 VSCode”。这些是你个人的工具习惯，不是团队共享的项目规则。个人偏好应放在 ~/.codex/AGENTS.md，不签入仓库；团队共享标准才写进项目的 AGENTS.md。

原则：写短、写真、写可验证。AGENTS.md 的核心是帮 Codex 减少重复询问，不是把所有项目文档塞进去。

已有 CLAUDE.md 或 Cursor Rules，还要再写 AGENTS.md 吗？

如果你已经用 Claude Code 或 Cursor，仓库里可能已经有 CLAUDE.md 或 Cursor Rules。这时候不需要维护三份重复规则，可以用导入或共存策略。

AGENTS.md vs CLAUDE.md：导入策略

Claude Code 读的是 CLAUDE.md，而不是 AGENTS.md。如果仓库已经有 AGENTS.md，可以创建一个简单的 CLAUDE.md 来导入它：

@AGENTS.md

## Claude-specific
- Prefer Chinese responses
- Keep responses concise (under 100 words unless requested)

@AGENTS.md 是导入语法，Claude Code 会先读 AGENTS.md，再读下方写的 Claude-specific 指令。这样可以避免维护两份重复规则：项目规则统一写在 AGENTS.md，Claude 特定的偏好写在 CLAUDE.md。

AGENTS.md vs Cursor Rules：Cursor 有自己的体系

Cursor 有自己的 Rules 体系（Project、Team、User Rules）。Cursor 官方文档摘要提到支持 AGENTS.md，但具体加载细节建议参考 Cursor 官方 Rules 文档。如果你同时用 Cursor 和 Codex，可以把项目规则统一写在 AGENTS.md，Cursor Rules 里写 Cursor 特定的配置或工作流。

AGENTS.md vs config.toml、Rules、Skills、MCP

AGENTS.md 是指导层，告诉 Codex”应该怎么做”。执行层（权限、沙箱、命令约束、工具集成）由其他机制控制。

对比项	AGENTS.md	其他机制	区别
.codex/config.toml	项目规则（怎么构建、怎么测试、不要改哪些目录）	执行策略（模型、沙箱、权限、网络、shell 环境）	规则写进 AGENTS.md，配置写进 config.toml；不要混为一谈
Rules	指导：“不要运行危险命令”	执行层约束：prefix_rule(pattern=["rm","-rf"], decision="forbidden")	AGENTS.md 里的”不要做某事”是建议，不等于规则引擎强制阻止
Skills	常驻项目规则	复杂可复用工作流、带脚本的流程、参考资料	常驻规则写 AGENTS.md；复杂工作流做成 Skill
MCP	指导层	工具集成层	AGENTS.md 不替代 MCP；指导 vs 工具

总结：AGENTS.md 解决”重复解释项目规则”的问题；执行层约束由 Rules、config.toml、沙箱、权限控制；复杂工作流由 Skills 处理；工具集成由 MCP 提供。不要把 AGENTS.md 当成万能入口。

什么时候更新 AGENTS.md？

AGENTS.md 不需要每次项目变化都改。按触发场景更新，避免频繁维护。

更新触发场景

OpenAI 官方文档建议在以下场景更新：

1. Codex 重复犯同一错误：比如连续两次改错了目录，或者每次都跑错 package 的测试。这时候补一条 Constraints 规则：“Do NOT edit src/generated/“或”测试命令用 pnpm --filter web test”。

2. PR review 里重复反馈：团队 reviewer 连续反馈”这类改动要补测试""不要改 generated code""不要 default export”。把这些反馈沉淀到 PR expectations 段，减少重复沟通。

3. Codex 读太多文档才找到答案：比如每次要翻几层目录才找到正确的测试命令或构建流程。这时候补 repo layout 或 Commands 段，把核心信息写在前面。

更新位置原则：最近目录原则

错误发生在哪个目录，就在该层的 AGENTS.md 补规则。不要每次都改根目录；monorepo 里不同 package 有不同规则，应分别维护子目录的 AGENTS.md。

比如：Codex 在 apps/web 目录下跑错了测试，就在 apps/web/AGENTS.md 补规则；不要在根目录写一条会覆盖所有 package 的通用规则。

与长期记忆的区别

AGENTS.md 是每次启动加载的静态指导，不是会自动学习的记忆库。Codex不会根据你的纠正自动更新 AGENTS.md，除非你明确让它更新（OpenAI 官方文档提到可以让 Codex 在你纠正它后更新文件）。

如果你需要跨会话积累知识、治理项目记忆，可以看之前写的 AI Agent 记忆管理，那里讲了长期记忆和项目规则的分工。

模板生长路径：从种子版到扩展版

不要一开始就复制 300 行模板。先写 12-20 行种子版，再按触发场景逐步扩展。

种子版：只写最核心的 6 块

种子版只写 repo layout、常用命令、约束、PR 期望、done/verify，12-20 行。比如：

# AGENTS.md

## Repo layout
- Frontend: React + TypeScript + Vite (src/)
- Backend: Node.js + NestJS (server/)
- Package manager: pnpm

## Commands
- Install: pnpm install
- Dev: pnpm dev
- Build: pnpm build
- Test: pnpm test
- Lint: pnpm lint

## Constraints
- Do NOT edit src/generated/ (auto-generated code)

## PR expectations
- Add tests for new features

## Done when
- `pnpm test` passes
- `pnpm build` succeeds

扩展触发场景：什么时候补一块？

运行几次后，遇到这些场景再扩展：

1. 第一次 Codex 改错了目录：比如改了 migrations/ 或 generated/。这时候补 Constraints 段：“Do NOT commit migrations/ without team review”或”Do NOT edit any file in src/generated/”。

2. 第一次 PR review 反馈重复：团队 reviewer 反馈”这类改动要补测试""不要 default export”。补 PR expectations 段：“Add tests for new features""Use named exports, not default exports”。

3. 第一次 Codex 用错包管理器：比如在 pnpm 项目里用了 npm 命令。补 Commands 段：“Always use pnpm, not npm or yarn”。

4. 第一次 Codex 没跑 lint：提交前忘了跑 lint 检查。补 Done when 段：“pnpm lint passes with no errors”。

扩展版示例：30-50 行

扩展版可能在种子版基础上补了约束、PR 期望、包管理器约定、lint 要求，变成 30-50 行：

# AGENTS.md

## Repo layout
- Frontend: React + TypeScript + Vite (src/)
- Backend: Node.js + NestJS (server/)
- Package manager: pnpm

## Commands
- Install: pnpm install
- Dev: pnpm dev
- Build: pnpm build
- Test: pnpm test
- Lint: pnpm lint
- Always use pnpm, not npm or yarn

## Constraints
- Do NOT edit src/generated/ (auto-generated code)
- Do NOT commit migrations/ without team review
- Do NOT modify .env files (use .env.example as template)

## PR expectations
- Add tests for new features
- Run `pnpm test` and `pnpm lint` before marking done
- Use named exports, not default exports
- Keep components under 200 lines; split if larger

## Done when
- `pnpm test` passes
- `pnpm build` succeeds
- `pnpm lint` passes with no errors
- New features have corresponding tests

核心原则：按触发场景扩展，不要预先写满。AGENTS.md 的价值是减少重复询问，不是展示项目的所有文档。

结论

AGENTS.md 是常驻项目的指导文件，不是万能仓库，也不是长期记忆系统。它解决的是”每次都要重复解释项目规则”的痛点，不是”让 Codex 自动学会项目知识”。

实际操作建议：

1. 先写 12-20 行种子版：repo layout、常用命令、约束、PR 期望、done/verify。不要一开始就复制 300 行大模板。

2. 用验证命令确认生效：codex --ask-for-approval never "Summarize the current instructions."，看输出是否包含你的规则。

3. 按触发场景逐步扩展：Codex 重复犯错误、PR review 重复反馈、读太多文档才找到答案时才补一块。不要每次项目变化都改。

4. 不要把不该写的东西塞进去：密钥、易过期清单、抽象口号、模糊命令、不可验证要求、个人偏好。

5. 已有 CLAUDE.md 或 Cursor Rules 时用导入/共存策略：项目规则统一写在 AGENTS.md，工具特定的偏好写在各自的配置文件。

AGENTS.md 把项目规则沉淀下来，后续 Skills/plugins 专题会把复杂工作流做成可复用的 Skill；权限、沙箱、密钥管理会讲执行层约束；失败复盘与验收会让 done/verify 真正生效。这些机制一起构成 Codex 的完整约束体系。