03｜AGENTS.md：给 AI 的项目说明书

本篇是《从头重新学 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 进来就知道这个项目的基本情况，不用你每次都从头介绍。