写给 AI 看的文档：你的 README 正在被 Agent 当说明书读

有个 quietly 发生的转变：你仓库里文档的第一读者，已经从人变成了 AI。Agent 读你的 README、CONTRIBUTING、注释，不是为了"学习"，而是直接拿来当行动指令。你写给人看的文档讲究娓娓道来，写给 AI 看的文档讲究精确、无歧义、可执行——这是两种完全不同的文体。

三层文档，各司其职

实践下来，写给 AI 的文档分成三层最顺手。

第一层：项目宪法（CLAUDE.md / AGENTS.md）。放在仓库根目录，Agent 一进仓库先读它。写什么？技术栈和版本（"用 pnpm，不用 npm"）、绝对禁区（"不要改 migrations/"、"不要引入新依赖先问我"）、常用命令（dev/build/test 一行一个）。记住一个原则：只写"不写就会错"的东西，写多了等于没写——Agent 对超长指令的遵守率是递减的。

第二层：任务技能（SKILL.md）。这是可复用的工作流：比如"发版流程""新增一个 API 端点的标准步骤""写迁移脚本的 checklist"。和宪法不同，skill 是按需加载的——Agent 遇到发版任务才读发版 skill。判断标准：如果一个流程你向 Agent 口述过两遍以上，就该把它写成 skill。

第三层：决策记录（ADR）。Architecture Decision Records，回答"为什么这样设计"。这是最容易被 vibe coder 跳过、又最有长期价值的一层。Agent 没有项目记忆，它看到"为什么用 Postgres 而不用 SQLite"这类上下文时，做出的后续决策质量完全不同。每条 ADR 不用长：背景、决定、后果，三段话就够。

写给 AI 的文体要点

第一，用祈使句，少用描述句。"本项目使用 TypeScript 严格模式"不如"所有新文件必须用 TypeScript 严格模式，禁止 any"。AI 对"必须/禁止"的遵守远好于对"我们通常"的理解。

第二，给反例。光说"怎么写对"不够，要写"别怎么写错"。比如："错误：在组件里直接 fetch；正确：所有数据请求走 lib/api.ts"。Agent 是模式匹配机器，反例能精准切断它最爱走的那条错路。

第三，保持文档和代码同步，否则不如不写。过时的文档对 AI 是毒药——人看到过时文档会怀疑，AI 会直接照做。每次改架构顺手更新相关文档，应该成为你工作流里的固定步骤，甚至可以让 Agent 自己来做这件事（"改完代码后同步更新相关文档"写进宪法）。

一个冷知识：文档也是获客

当别人的 Agent 在帮主人调研"有没有现成的库能做 X"时，它读的就是你的 README 和文档。写给 AI 看得懂的文档，等于让你的项目在 Agent 驱动的选型里更容易被选中。清晰的安装步骤、明确的适用边界、一句说清"这是什么"——这些既是给人看的，也是给 Agent 看的。在这个意义上，文档已经是你的项目的 API。