用 AGENTS.md 写好 AI 的项目说明书

让 AI 修改代码并不难，难的是让它在动手前真正理解项目。新会话缺少技术栈、目录职责和团队规范等背景时，即使任务描述清楚，Agent 仍可能选错文件或采用不合适的实现方式。AGENTS.md 正是用来补齐这层长期上下文的项目说明文件。

本篇是《从头重新学 AI 编程》系列第 3 篇。

上一篇我们聊了 Spec，怎么在让 AI 动手之前把需求写清楚。

但 Spec 解决的是「这一次要做什么」的问题。还有一个更大的问题它没管到，AI 对你的项目一无所知。

你想想看，你每次开一个新会话，AI 都是从零开始的。它不知道你的项目用什么技术栈，不知道目录结构长什么样，不知道你们团队有什么编码规范，不知道哪些文件是禁区。

所以你每次都得重新解释一遍。

我以前经常碰到一种情况，开了一个新会话，写了一段 Spec，AI 开始动手了，改了两个文件之后我发现，它用了一种我完全不想要的写法。比如在组件里直接 fetch，而我项目里所有请求都走 src/api/ 那一层。

它不是不听话，它是真的不知道。

然后我就得停下来解释，「我们这个项目请求走 api 层的，你改一下」。改完之后下一个功能又犯了。因为每个会话都是一张白纸。

后来我就想，有没有一种办法，让 AI 一进来就自动知道这些东西？

有的。就是在项目根目录放一个叫 AGENTS.md 的文件。

你可以把它理解成给 AI 看的 README。README 是给人看的，新人来了先看 README 了解项目全貌。AGENTS.md 是同样的东西，只不过读者是 AI Agent。

AI 在每次会话启动时会自动读取它。读完之后它就知道了，这个项目是什么，用什么技术栈，目录怎么组织，有什么规矩不能破。

不用你每次开口都先花五分钟介绍背景。

那这个文件里应该放什么？我自己写了一段时间之后，总结出来六类东西比较有用。

第一类，项目简介。一两句话说清楚这个项目是什么、用什么技术栈。

## 项目简介
待办事项 Web 应用。前端 React + TypeScript，后端 Node.js + Express，数据库 SQLite。

看起来很简单对吧。但你不写，AI 就得从代码里猜。它猜对了还好，猜错了你可能到第三轮对话才发现方向不对。

第二类，目录地图。这个我觉得是整个 AGENTS.md 里最重要的部分。

## 目录结构
- src/components/ — 前端组件
- src/api/ — 前端 API 调用层
- server/ — 后端服务
- server/routes/ — API 路由
- server/db/ — 数据库 schema 和迁移

为什么最重要？因为 AI 改代码之前得知道去哪改。你给它一张地图，它就不用自己扫描整个项目猜来猜去。省时间不说，还不容易改错地方。

第三类，常用命令。

## 常用命令
- 启动开发 npm run dev
- 测试 npm test
- Lint npm run lint
- 构建 npm run build

你不告诉它怎么跑项目，它可能会猜。猜错了命令跑不起来，又浪费一轮对话。

第四类，编码规范。

每个团队都有自己的习惯。有些东西你觉得理所当然，AI 不知道。

## 编码规范
- 组件用函数式写法，不用 class
- 样式用 CSS Modules，不用行内样式
- API 调用走 src/api/ 层，不要在组件里直接 fetch
- 错误处理统一用 try-catch，不要吞掉错误

这些规范你不说，AI 可能用一种你完全不习惯的方式写代码。技术上没问题，能跑，但团队里其他人看了一脸懵。

第五类，红线。这个比什么都重要。

## 红线
- 不要修改已有 migration 文件
- 不要引入新的 UI 框架
- 所有 API 变更必须同步更新测试
- 不要在生产代码里加 TODO

红线就是绝对不能碰的事。你不说，AI 不知道这是禁区。它可能觉得改一下 migration 文件没什么大不了的，但对你来说这可能意味着整个开发环境要重来。

我自己的经验是，每一条红线背后都应该有一个你踩过的坑。如果你发现自己反复跟 AI 说「不要做 X」，那就把它写进 AGENTS.md。写一次，后面就再也不用重复了。

第六类，容易踩的坑。

## 容易踩的坑
- SQLite 不支持 ALTER TABLE DROP COLUMN，需要重建表
- 前端 dev server 端口是 3000，后端是 3001
- 测试数据库和开发数据库是分开的，跑测试前不用手动清数据

这些东西你踩过一次就知道了，但 AI 每次都是新的。写进去，它就不用再踩一遍。

好，把上面这些合在一起，我们这个待办事项应用的 AGENTS.md 大概长这样，

# AGENTS.md

## 项目简介
待办事项 Web 应用。前端 React + TypeScript，后端 Node.js + Express，数据库 SQLite。

## 目录结构
- src/components/ — 前端组件
- src/api/ — 前端 API 调用层
- server/ — 后端服务
- server/routes/ — API 路由
- server/db/ — 数据库 schema 和迁移

## 常用命令
- 启动开发 npm run dev
- 测试 npm test
- Lint npm run lint
- 构建 npm run build

## 编码规范
- 组件用函数式写法
- API 调用走 src/api/ 层
- 错误处理用 try-catch，不要吞掉错误

## 红线
- 不要修改已有 migration 文件
- 不要引入新的 UI 框架
- 所有 API 变更必须同步更新测试
- 组件内不要直接 fetch，走 src/api/ 层

不长，二十几行。但有了它，AI 进来就知道这个项目的基本情况，不用你每次都从头介绍。

顺着这个再聊一下，你可能还会看到一个叫 CLAUDE.md 的文件。这两个是什么关系？

很简单。AGENTS.md 是通用的，大多数 AI 工具都能读，Cursor、Codex、Copilot 都认。CLAUDE.md 是 Claude Code 专用的，可以放一些只针对 Claude 的配置。

怎么让它们共存？最简单的办法是在 CLAUDE.md 第一行写 @AGENTS.md，这样 Claude Code 启动时会自动把 AGENTS.md 的内容导入进来，你不用维护两份。

如果你只用一个工具，直接写一个文件就够了。不用纠结命名这种小事。

回到 AGENTS.md 本身，聊几个我自己踩过的坑。

第一个，不要写太长。

我一开始写的时候恨不得把整个项目的架构文档都塞进去，后来发现太长了 AI 反而抓不到重点。现在我控制在 200 到 400 行之间，只放 AI 每次都需要知道的核心信息。详细的架构文档放 docs/ 目录就好，需要的时候再让 AI 去看。

第二个，不要用 /init 生成完就不管了。

Claude Code 和 Codex 都有 /init 命令，能一键扫描项目生成一份初稿。这个东西很好用，但它是冷启动工具，不是日常维护工具。生成完之后你得自己过一遍，把真正重要的东西补进去，把不相关的删掉。之后随着项目演进，手动更新。

第三个，也是我觉得最实用的一条，每次被 AI 坑了，就补一条。

每次我发现 AI 又犯了同一个错误，比如又在组件里直接 fetch 了，或者又改了不该改的 migration 文件，我就会打开 AGENTS.md 加一条规则。

时间长了，这份文件就变成了你和 AI 之间的「教训合集」。每条规则背后都有一个真实的坑。这也是为什么你不应该把它当成一次性的文档，它跟上一篇聊的 Spec 一样，是活的。

说到这里，这三篇聊下来你可能已经感觉到了，Vibe Coding 的核心其实不是什么高深的技术。

第 1 篇讲的是，你的角色变了，从写代码变成管 Agent 的注意力。

第 2 篇讲的是，每次给任务之前先写 Spec，把意图、约束、验收标准想清楚。

第 3 篇讲的是，把项目层面的信息写进 AGENTS.md，让 AI 每次进来都自带背景知识。

三件事加在一起，你跟 AI 协作的起点就完全不一样了。不是每次都从零开始，而是每次都从一个有背景、有边界、有规矩的状态开始。

给你一个小练习。

打开你现在手头正在做的项目，花十分钟写一份 AGENTS.md。不用写得很完整，先把这几样东西放进去，

1. 项目是什么，用什么技术栈
2. 目录结构（最重要的几个目录是什么）
3. 怎么跑起来
4. 什么东西绝对不能碰

然后下次开一个新会话让 AI 做点什么，看看它的表现有没有不一样。

下一篇我们聊一个实操问题，接手一个旧项目的时候，怎么让 AI 先看懂代码再动手。