AI 接手你的项目之前，先写好这份说明书：AGENTS.md 实战指南

为什么需要：Agent 每次开工都是失忆的

你有没有遇到过这种情况：新开一个 agent 会话，让它修个 bug，它先花二十分钟满世界找测试命令，最后还跑错了；或者它兴高采烈地重构了你明确不想动的那坨祖传代码。问题不在 agent 笨——问题是它失忆了。每个新会话都是一张白纸，而你的项目有一整套没写下来的潜规则。

AGENTS.md（以及它的亲戚 README、CLAUDE.md、.cursorrules）就是解决这个问题的：一份写给 AI 看的项目说明书。它的经济学很划算：你花一小时写下来，之后每一次 agent 会话都省掉二十分钟的试错，还少踩几个坑。这是 vibe coding 里回报率最高的一小时。

说明书里必须有的 5 样东西

一、项目一句话 + 架构地图。第一行就讲清楚这是什么、给谁用的。然后画一张目录地图：每个顶层目录是干什么的，核心流程走哪几个文件。Agent 最怕的不是代码难，是「不知道从哪下手」——地图解决的就是这个问题。

二、常用命令，一个都不能少。安装依赖、启动开发环境、跑测试、跑 lint、构建、部署——每条命令都要真实可跑，复制粘贴就能用。这是说明书里价值密度最高的部分，也是最容易写错的部分：你以为的命令和实际能跑的命令，经常是两回事。写完自己跑一遍。

三、约定与禁忌。代码风格（用哪个 formatter、命名习惯）、架构约定（新功能放哪一层、状态管理用什么）、以及最重要的——不要碰的地方。比如「migrations 目录不要手改」「这个 API 是给第三方用的，保持向后兼容」。禁忌清单比约定更重要，因为 agent 的默认行为是「看起来合理就动手」。

四、已知的坑（Gotchas）。那些你踩过、但新人（和 AI）一定会再踩的坑：测试必须按顺序跑、某个环境变量本地和 CI 不一样、第三方 API 有诡异的限流。每个坑一句话：现象 + 正确做法。这是你作为项目 owner 独有的知识，文档里没有，代码里看不出来。

五、完工检查清单。改完代码之后必须做什么：跑哪几个测试、更新哪些文档、commit message 什么格式。把「做完」定义清楚，agent 才不会交出一份「看起来做完了」的半成品。

三个反模式：这样写不如不写

反模式一：写成散文。Agent 不读散文，它读的是清单、命令和规则。三段式的项目愿景描述对 agent 毫无用处——它需要的是「跑测试用 npm test，别用 npm run test:watch」这种精确到命令行的指令。能列表就别成段，能给命令就别描述。

反模式二：过期文档。这是最毒的一种：过期的说明书比没有说明书更害人。Agent 会百分之百信任你写的东西，命令跑不通它会先怀疑自己、绕远路，最后才怀疑文档。改了代码不改文档，等于亲手给 agent 下毒。

反模式三：把密钥写进去。说明书会被整个塞进 prompt，而 prompt 会发给模型厂商、记进日志。API key、数据库密码、内部 host——这些东西一个字都不能出现在说明书里。需要 credentials 的地方，只写「从环境变量读」，不写值。

维护纪律：让说明书越用越聪明

说明书不是写完就完事的，它应该是活的。立两条规矩：

第一，agent 每次踩坑，坑就进说明书。这是最关键的纪律。Agent 走错了目录、跑错了命令、用错了 API——别只在心里骂一句，把它变成说明书里的一条禁忌或一条 gotcha。下次开新会话，这个坑就不存在了。你的说明书应该越用越厚（但要定期修剪）。

第二，定期让 agent 自己 review 说明书。每隔几周，开个会话让 agent 对照当前代码检查说明书：哪些命令跑不通了、哪些目录结构变了、哪些约定已经没人遵守。让 AI 维护给 AI 看的文档，闭环了。

一个可以直接抄的最小模板

别追求一次写完美，先让说明书存在。下面这个骨架够大多数项目用：

# 项目名：一句话说什么、给谁用
## 快速开始（复制粘贴可跑的命令）
## 目录地图（每个顶层目录干什么）
## 开发约定（风格、架构、命名）
## 禁忌（不要碰、不要用、不要改）
## 已知的坑（现象 + 正确做法）
## 完工检查（改完代码必须跑什么）

写完之后做一件事：新开一个 agent 会话，只给它看说明书，让它跑一遍快速开始。跑不通的地方，就是说明书要改的地方。这个测试五分钟，但能过滤掉九成的过期和笔误。

我们怎么看：说明书是你和 Agent 之间的契约

往深了说，AGENTS.md 是一份契约：你把项目的隐性知识显性化，agent 承诺按契约干活。契约越清楚，你需要盯着它的时间就越少——这才是「一人团队」的真正含义：不是一个人干所有活，而是一个人定规则，agent 按规则干活。

很多人把 vibe coding 理解成「说话就行了」，其实恰恰相反：越是让 AI 干活，越需要把规则写清楚。随口一句话能启动项目，但只有写下来的说明书能让项目活得久。今天花一小时写好它，明天的每个 agent 会话都会感谢你。