写给开发者的 AGENTS.md 使用手册

一份让 AI 助手和你都省心的项目说明书

“让机器人读得懂，让人类不费劲。”

开场白：为什么又冒出个 AGENTS.md？

你可能已经习惯了 README.md——它面向人类开发者，告诉你项目做什么、怎么贡献。
而 AGENTS.md 则是写给「AI 编程助手」的说明书：

告诉 AI 如何启动开发服务器、跑测试、格式化代码；
让 AI 不会因为误跑生产构建而把你的热重载搞挂；
放在仓库根目录，任何主流 AI 工具都能秒懂。

一句话：README 给人看，AGENTS.md 给 AI 看。

1. 它长什么样？

AGENTS.md 就是普通的 Markdown 文件，文件名必须叫 AGENTS.md，放在仓库根目录。
下面是一段最小可运行示例，你几乎可以原封不动先用起来。

# AGENTS.md

## 启动开发环境
- 安装依赖：`pnpm install`
- 启动热重载：`pnpm dev`
- 跑全部测试：`pnpm test`

## 代码风格
- TypeScript 严格模式
- 单引号，无分号
- 能写纯函数就别写类

2. 我该往里写什么？

把 AI 当成第一天上班的新同事，你最想口头交代哪些事，就写哪些。
推荐 5 个固定板块，按需增删。

板块	写什么	是否必须
1. 启动命令	安装依赖、启动开发服务器、跑测试	强烈建议
2. 代码风格	用空格还是 Tab、要不要分号、函数式还是 OOP	建议
3. 测试策略	如何跑单元测试、CI 入口在哪	建议
4. 提交规范	PR 标题格式、要不要 rebase	可选
5. 常见坑	误跑 build 会破坏热重载等	可选

3. 模板：一句一句抄就能用

把下面整块复制，改 3 处就能用：

# AGENTS.md

## 环境准备
- Node.js ≥ 18
- 包管理器：pnpm （如果团队用 yarn，把下面所有 pnpm 换成 yarn）

## 启动开发服务器
1. 克隆仓库
2. `pnpm install`
3. `pnpm dev`  
   浏览器自动打开 http://localhost:3000  
   ⚠️ 不要跑 `pnpm build`，会关掉热重载。

## 代码风格
- TypeScript strict
- 单引号，无分号
- 组件样式用 CSS Modules，与组件同名并放同目录

## 测试
- 单元测试：`pnpm test`
- 端到端：`pnpm e2e`
- CI 配置见 `.github/workflows/ci.yml`

## 提交 PR 前
1. `pnpm lint`
2. `pnpm test`
3. PR 标题格式：`[组件名] 简短描述`

4. 多包仓库（Monorepo）怎么办？

仓库里有十几个子包？
把 AGENTS.md 放在每个包目录里 就行。
AI 会优先使用离当前文件最近的那一份。

示例结构：

my-monorepo/
├─ AGENTS.md          # 根级别通用说明
├─ apps/web/
│  └─ AGENTS.md       # 给 Next.js 前端看的
└─ packages/ui/
   └─ AGENTS.md       # 给组件库看的

子包里的内容可以更简单，只写差异点：

# packages/ui/AGENTS.md

## 仅与本包相关
- 运行 Storybook：`pnpm storybook`
- 发布前别忘了 `pnpm build`

5. 常见疑问（FAQ）

Q1：文件名必须叫 AGENTS.md 吗？
可以改吗？
A：最好不改。OpenAI Codex、Cursor、Jules 等主流 AI 都按这个名字找文件。

Q2：跟 README 重复会不会冗余？
A：不会。README 面向人，可以写愿景、贡献者名单；AGENTS.md 面向 AI，只写“下一步按哪个键”。各司其职。

Q3：AI 真的会读吗？
A：会。只要你把指令写成自然语言列表，AI 会把它们当成“待办事项”一条条执行。

Q4：写完要不要提交到 Git？
A：当然要。它是代码的一部分，同事换 AI 工具也能立即生效。

Q5：能不能用 YAML、JSON？
A：Markdown 就够了。YAML 对非技术同事不友好，JSON 又太死板，Markdown 折中。

6. 动手实践：10 分钟把现有文档升级成 AGENTS.md

步骤 1：5 分钟——梳理现有指令

打开 README，把「安装、启动、测试」段落复制出来。

步骤 2：3 分钟——删繁就简

去掉人类阅读才需要的背景故事。把命令写成列表。

步骤 3：2 分钟——加警告

把“不要跑 npm run build”用 ⚠️ 标红。

步骤 4：0 分钟——提交

git add AGENTS.md && git commit -m "docs: add AGENTS.md for AI assistant"

7. 附录：真实示例片段

片段 A：Next.js 项目

# AGENTS.md

## 技术栈
- Next.js 14 App Router
- TypeScript strict
- TailwindCSS
- 单元测试：Vitest + React Testing Library

## 启动
- `pnpm install`
- `pnpm dev` → http://localhost:3000
- 热重载失效？先 `rm -rf .next` 再 `pnpm dev`

## 测试
- 单元：`pnpm test`
- 端到端：`pnpm e2e`
- 覆盖率阈值：80%

## 提交规范
- 使用 Conventional Commits
- PR 模板在 `.github/pull_request_template.md`

片段 B：组件库

# packages/core/AGENTS.md

## 快速开始
1. `pnpm install`
2. `pnpm storybook`

## 构建
- `pnpm build` 输出到 `dist/`
- 发布前确保 `pnpm test` 全绿

## 代码风格
- 每个组件一个文件夹，包含 `index.ts`、`Component.tsx`、`Component.test.tsx`

结语：写给未来的你

三个月后，当你半夜修 bug，打开 Cursor 说 “帮我跑一下测试”，
AI 会因为你提前写了 AGENTS.md，而准确执行 pnpm test，
而不是笨笨地跑去 npm run build 把你的热重载弄挂。

省下的 10 分钟，就是这份小文档的最大价值。

AGENTS.md是什么？如何为AI助手编写高效开发文档