AGENTS.md 深度指南：如何给 AI 编程助手写一份好「入职手册」

你让 AI 帮你写代码，它上来就把你精心设计的目录结构改了个面目全非。

你跟它说「别动那个文件」，下一轮它又动了。

你换了一个 AI 工具，之前的规则全废了，又得从头教一遍。

这三个问题，一个文件就能解决。它叫 AGENTS.md。

一、AGENTS.md 是什么

先说个类比。新员工入职第一天，你会给他一份文档：项目用什么技术栈、代码怎么跑、测试怎么运行、哪些东西不能碰。AGENTS.md 干的就是这个事，只不过读者不是人，是 AI。

它是放在项目根目录的一个 Markdown 文件。AI 编程工具（Claude Code、OpenAI Codex、Cursor、Google Jules 等）每次启动会话时，会自动读取这个文件，把里面的内容当作项目的背景知识。

说白了，README.md 是写给人看的，AGENTS.md 是写给 AI 看的。

下图展示了 AGENTS.md 与其他 AI 规则文件的定位关系。可以看到，AGENTS.md 是唯一一个跨工具通用的开放标准。

文件	归属工具	是否开放标准
CLAUDE.md	Claude Code	否
.cursor/rules/	Cursor	否
copilot-instructions.md	GitHub Copilot	否
AGENTS.md	跨工具	是

和其他规则文件的关系

你可能已经见过一些类似的文件。它们各有各的领地：

文件	归属工具	特点
CLAUDE.md	Claude Code 专属	Claude Code 原生支持
.cursor/rules/*.mdc	Cursor	支持路径匹配、手动引用、AI 自主加载
.github/copilot-instructions.md	GitHub Copilot	Copilot 专属
AGENTS.md	跨工具开放标准	Codex、Cursor、Claude Code、Jules 等通用

AGENTS.md 的核心价值在于跨工具通用。写一份，换个 AI 工具照样能用。潘嘉铖在知乎文章中做了一个很好的比喻：所有层的 AGENTS.md 文本拼接在一起同时生效，多层之间是拼接而非覆盖——每一层都加上一道约束。

实际操作中，很多开发者用 @import 语法让 CLAUDE.md 引用 AGENTS.md，只维护一份：

<!-- .claude/CLAUDE.md -->
@import ../AGENTS.md

这样 Claude Code 读 CLAUDE.md 时，自动加载 AGENTS.md 的内容。

二、官方怎么说

AGENTS.md 不是一个民间约定，它有官方背书。

2025 年，OpenAI Codex、Google Jules、Cursor、Amp、Factory 等公司联合推出了这个格式。目前超过 6 万个开源项目在使用。它由 Linux Foundation 旗下的 Agentic AI Foundation 管理，是一个真正的开放标准。

官方网站 agents.md 的说明很简单：

AGENTS.md is just standard Markdown. Use any headings you like; the agent simply parses the text you provide.

翻译过来就是：纯 Markdown，没有强制字段，没有特定格式。 AI 自己解析你写的文本。

这听起来太自由了，自由到很多人不知道该写什么。下面就来解决这个问题。

三、六层结构：经过验证的写作框架

我综合了知乎上多篇高赞文章（程序员鱼皮、段小草、潘嘉铖、aa程序小宏等）和 agents.md 官方示例，提炼出一个实用的六层结构。你不需要全部照搬，但每一层都值得想一遍。

层一：构建和启动命令（投入产出比最高）

这是最重要的一层。AI 最常犯的错误就是瞎编命令——它看到 package.json 就用 npm，看到 requirements.txt 就用 pip，完全不管你项目实际用的是 pnpm 还是 poetry。

## 构建命令
- 安装依赖: `pnpm install`（**禁止**使用 npm/yarn）
- 启动开发服务器: `pnpm dev`
- 运行测试: `pnpm test`
- 提交前必须通过: `pnpm lint && pnpm typecheck`

几个要点：

• 用粗体或「禁止」「必须」等强语气词。AI 需要明确的、不带感情色彩的指令，而不是委婉的建议。段小草在文章中说得很好：你可以在 AGENTS.md 里写「ABSOLUTELY NEVER do sth.」这样直白的指令，但如果把这种话写给人类同事，就显得非常无礼。
• 写明前置条件。比如「运行测试前需要先启动 PostgreSQL」。
• 不要写凭经验猜测的命令。不确定的留空，比写错好。

层二：编码规范（只写 AI 反复犯错的）

很多开发者在这里犯一个错误：把整个团队编码规范搬进来。AI 不需要你教它什么是驼峰命名。

判断标准：这行删掉后，AI 会不会更容易犯错？如果不会，它就是在浪费上下文。

## 编码规范
- 使用命名导出，禁止默认导出
- Service 层错误统一用 Result 模式，不能直接 throw
- API 响应统一格式: `{ data, error, meta }`
- 所有时间统一存 UTC，时区转换交给前端

注意，这里写的都是「AI 容易猜错、代码里读不出来的约定」。Linter 能抓到的不用写。

层三：架构规则（画红线）

告诉 AI 哪些东西不能碰。这比说一万句「应该怎么做」有用。

## 架构规则
- 分层只能 domain → application → infrastructure，禁止反向依赖
- 数据库操作必须走 Service 层，不能在路由直接调 ORM
- 忽略 `legacy/` 目录，这是已弃用的旧代码
- 忽略 `vendor/` 和 `node_modules/`
- 只关注 `src/main/` 下的业务代码和 `src/test/` 下的测试代码

这一层特别重要。AI 有个坏习惯：看到代码就忍不住「顺手整理」。不画红线，它改着改着就把你的架构约束全破了。

层四：项目边界

哪些目录要关注，哪些要忽略。这直接影响 AI 的注意力分配。

## 项目边界
- 核心代码在 `src/` 目录
- `src/components/` 是共享组件库，改动需要格外谨慎
- `src/pages/` 是页面级组件
- `e2e/` 是端到端测试，使用 Playwright
- 不要修改 `.github/workflows/` 下的 CI 配置

层五：Git 规范

提交格式、分支策略、PR 要求。这些规则不写，AI 就会用它自己默认的格式。

## Git 规范
- 提交信息使用 conventional commits 格式
- 分支命名: `feat/xxx`、`fix/xxx`、`refactor/xxx`
- 禁止直接提交到 main 分支
- PR 标题格式: `[模块名] 简短描述`

层六：验证清单

改完代码后的自动检查步骤。这是保证质量的最后一道关。

## 验证清单
- [ ] 运行 `pnpm lint` 无错误
- [ ] 运行 `pnpm test` 全部通过
- [ ] 运行 `pnpm typecheck` 无类型错误
- [ ] 移动端和桌面端各验证一次

agents.md 官方文档明确说了：如果你在这里列了测试命令，AI 会在完成任务前自动运行它们，并尝试修复失败。

四、大型项目怎么办：嵌套 AGENTS.md

项目大了，一个文件放不下。官方的解决方案很优雅：嵌套。

项目根目录/
├── AGENTS.md           ← 全局规则
├── packages/
│   ├── frontend/
│   │   └── AGENTS.md   ← 前端子项目规则
│   ├── backend/
│   │   └── AGENTS.md   ← 后端子项目规则
│   └── shared/
│       └── AGENTS.md   ← 共享库规则

规则很简单：最近的文件优先。 AI 编辑 packages/frontend/ 下的文件时，先读全局 AGENTS.md，再读 frontend 的 AGENTS.md，后者覆盖前者中冲突的部分。

OpenAI 自己的仓库里就有 88 个 AGENTS.md 文件。这不是滥用，是大型 monorepo 的合理做法。

五、社区在争论什么

AGENTS.md 虽然被广泛采用，但并非没有争议。了解这些争论，能帮你更好地决策。

争论一：需要单独给 AI 写文件吗

反对派认为：既然 LLM 的核心能力就是理解人类语言，我们应该优化给人类看的文档（README/CONTRIBUTING），让 AI 自行适应，而不是为 AI 单独开小灶。AGENTS.md 里写的那些构建命令、测试方式，本来就该在 CONTRIBUTING.md 里。

支持派给出了三个现实理由：

1. 指令精确度不同。AI 需要明确的指令（「禁止使用 npm」），但这种话写给人类显得无礼
2. 详略程度不同。给 AI 的文档必须精炼，因为每多一个 token 都在花钱。给人类的文档追求 100% 完整
3. 知识盲点不同。AI 对最新框架 API 了如指掌，但对项目里的不成文潜规则一无所知

我觉得两派都有道理。但现实是，很多项目的 CONTRIBUTING.md 确实写得不好，AGENTS.md 的出现逼着大家重视这件事。不管叫什么名字，把项目规则写清楚，对人对 AI 都是好事。

争论二：单文件还是多文件

有经验的开发者提出，对于大型复杂项目，一个巨大的 Markdown 文件很快会变得难以维护。

目前的共识是分层处理：

层级	位置	作用范围
组织托管	GitHub 组织级别	整个组织
用户级	~/.codex/AGENTS.md	当前用户所有项目
项目级	项目根目录	团队共享（提交到版本控制）
本地级	.claude/CLAUDE.md	仅自己（不提交）

所有层拼接在一起生效，越靠近工作目录的指令越优先。这个设计和编程语言的作用域规则异曲同工。

六、最容易犯的五个错误

我看了大量知乎文章和社区讨论，总结出以下高频陷阱。

错误一：写成项目介绍。 项目愿景、业务历史、团队故事写了一大堆，却没有启动命令和测试方式。AI 不需要了解你的创业故事，它需要知道怎么跑起来。

错误二：规则太宽泛。 「写高质量的代码」「遵循最佳实践」——这种话等于没说。AI 需要的是「使用命名导出，禁止默认导出」这样具体的指令。

错误三：强制全量测试。 大型项目的完整测试可能跑几十分钟。改一个静态文案也强制全量运行，最后只会让规则被忽略。更合理的做法是：先运行相关测试，再根据影响范围扩大。

错误四：从不更新。 AGENTS.md 是活文档。技术栈换了、目录结构调了、新加了约束——都需要同步更新。过时的规则比没有规则更危险。

错误五：多工具不同步。 Claude 侧规则更新了，Codex 侧没更新；根目录写了新规则，rules 的索引没更新。建议定期做一次同步检查。

七、一个可以直接用的模板

把前面的内容汇总成一个模板。根据项目实际情况增删，不要照抄。

# AGENTS.md

## 构建命令
- 安装依赖: `pnpm install`
- 启动开发: `pnpm dev`
- 运行测试: `pnpm test`
- 类型检查: `pnpm typecheck`
- 代码规范: `pnpm lint`
- 提交前必须通过: `pnpm lint && pnpm test && pnpm typecheck`

## 编码规范
- 使用命名导出，禁止默认导出
- 使用函数式组件，不用 class 组件
- 所有组件必须有 TypeScript 类型定义
- 错误统一用 Result 模式，不直接 throw

## 架构规则
- 分层方向: domain → application → infrastructure，禁止反向依赖
- 数据库操作必须走 Service 层
- API 响应格式: `{ data, error, meta }`
- 所有时间存 UTC，时区转换交给前端

## 项目边界
- 核心代码在 `src/`
- `src/components/` 是共享组件，修改需谨慎
- `legacy/` 目录已弃用，不要修改
- 不要动 `.github/workflows/` CI 配置

## Git 规范
- 提交格式: conventional commits
- 分支命名: `feat/xxx`、`fix/xxx`
- 禁止直接提交到 main

## 验证清单
- [ ] pnpm lint 无错误
- [ ] pnpm test 全通过
- [ ] pnpm typecheck 无错误

八、让 AI 帮你写 AGENTS.md

一个很实用的技巧：不要从零开始写。

几乎所有支持 AGENTS.md 的工具都能帮你生成初稿。以 Codex 为例，你只需告诉它项目目标和基本约束，让它起草一份。Claude Code 有 /init 命令，自动扫描项目结构生成 CLAUDE.md。

生成之后，人工审查一轮。重点是：

1. 命令是否真实可执行（不要凭经验补一个看起来能用的）
2. 约束是否具体到 AI 能执行
3. 有没有遗漏项目特有的坑点

还有一个进阶玩法：让 AI 定期审查 AGENTS.md。你可以跟它说「请根据最近三次审稿反馈，总结哪些规则应该沉淀进 AGENTS.md」，让它给你建议，你来决定是否采纳。

九、学术论文怎么说：意外的发现

以上都是实践者的经验。学术界怎么看？

arXiv 论文 2602.11988《Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents?》做了一个严谨的对照实验，结论出乎意料：

提供 context file 不会普遍提高任务成功率，但会增加 20% 以上的推理成本。

实验用了两个数据集（SWE-Bench Lite 的 300 个任务 + AGENTBENCH 的 138 个实例），三种对照（无 context / LLM 自动生成 / 开发者手写），在多个 LLM 和编码代理上均成立。

但论文有一个重要转折：

context file 中的指令确实会被遵循，但大段的仓库概述虽然流行且被推荐，实际上并无帮助。

翻译成实操建议就是：少写废话，多写规则。 构建命令、编码约束、Never 规则——这些具体的、可执行的指令才是有效的。项目愿景、架构概述、技术栈介绍——这些大段描述只是浪费 token。

这和我们前面说的「判断标准：这行删掉后 AI 会不会更容易犯错」完全一致。

知乎博主 @阿晚讲编程 做了 3 周 50+ 次人工抽检，数据也印证了这一点：

指标	没有 AGENTS.md	有 AGENTS.md
代码规范遵循率	~60%	95%+
一次通过率	~40%	80%+
每次修正时间	~8 分钟	~1 分钟

注意这是小样本自测数据，但趋势足够明显。关键是写的都是具体规则，不是泛泛而谈。

小结

AGENTS.md 的本质，是在 AI 编程时代重新定义「项目文档」。README 给人看，AGENTS.md 给 AI 看，各司其职。

写好它的关键就三句话：命令要精确，约束要具体，文档要更新。

少写概述，多写规则。每一条规则都应该是从真实踩坑中长出来的。

如果你还没开始用，今天就在项目根目录创建一个吧。

---

参考文献

1. AGENTS.md 官方网站
2. Thoughtworks Technology Radar: AGENTS.md
3. 段小草：OpenAI 谷歌联手推出 AGENTS.md，能否成为编程 Agent 的「官方说明书」?
4. 程序员鱼皮：67个AI编程必会知识
5. 程序员鱼皮：CLAUDE.md 速通指南
6. 潘嘉铖：AGENTS.md: Agent 的指令本
7. aa程序小宏：如何写出让 Agent 准确执行的「共识协议」
8. 万字详解CLAUDE.md 最佳实践
9. AGENTS.md 怎么写？一套适合 Codex Desktop 的项目规范模板
10. 别每次都重新提醒 AI：我怎么用 CLAUDE.md 和 AGENTS.md 沉淀项目规则