用 AI 写技术文档和 README
更新 2026-10-12 25 分钟（含评审） 难度 ★★☆☆☆作者 Skills 编辑部
相关搜索
这篇用到的 skill（3）
主力。和 AI 协作撰写文档，适合 README / 设计文档 / 教程。
npx skills add anthropics/skills -g写 API 文档时对齐设计原则， endpoint 描述更稳。
npx skills add wshobson/agents -g写之前先取最新官方文档，避免凭记忆编接口。
npx skills add affaan-m/ECC -g
写文档最怕"AI 写得像那么回事，但接口名是编的"。核心纪律是：让 AI 基于真实代码 / 真实文档写，写完后把每段和源码对一遍，别让它凭记忆编 API。
这篇适合谁 / 不适合谁
适合：
- 要给项目补 README、设计文档、接口说明
- 文档要对齐真实代码和真实接口
- 愿意写之前先让 AI 去翻代码 / 文档
不适合：
- 文档要对外的正式 SLA / 合规承诺（人必须审）
- 代码本身还没稳定（文档会反复作废）
- 要求完全零人工介入的文档工厂
开始前准备什么
- 代码 / 接口：要让 AI 基于真实内容写，而不是凭空编。
- 读者是谁：开发者 / 用户 / 运维，决定详略。
- 模板（若有）：公司文档模板先给。
操作步骤
1. 装 skill
doc-coauthoring 是文档协作撰写技能包，复制目录到客户端技能目录（与一般 Agent Skill 装法一致）：
| 客户端 | 目录 |
|---|---|
| Claude Code | ~/.claude/skills/ |
| Codex | ~/.codex/skills/ |
| Cursor | ~/.cursor/skills/ |
| Trae | ~/.trae/skills/ |
| CodeBuddy | ~/.codebuddy/skills/ |
| 通义灵码 | ~/.lingma/skills/ |
2. 先取真文档，再写
写接口文档前，用 documentation-lookup 拉最新官方文档；写代码说明，让 AI 先读仓库里的真实定义，不要凭记忆。
3. 给结构，不要给空话
text
为这个 CLI 写一份 README，结构固定为：
一句话定位 / 安装 / 5 个最常用的命令（含真实参数）/ 一个端到端例子 / 常见报错。
所有命令必须先读仓库源码确认存在，编出来的命令用 [待验证] 标出。4. 逐段对源码
写完后让 AI 把每个接口名、命令、参数和源码比对一次，确认无误再发布。
会踩的坑
| 坑 | 现象 | 怎么绕 |
|---|---|---|
| 编接口 | 文档里的 endpoint 不存在 | 写前先读真实代码 / 文档 |
| 例子跑不通 | 命令参数错 | 例子要基于真实 CLI 验证 |
| 对口读者错 | 太技术或太浅 | 开头就定读者和详略 |
| 无结构 | 一大段难读 | 固定小节结构再写 |
| 过期 | 代码改了文档没改 | 文档随 PR 一起更新，别单独攒 |
FAQ
AI 会编 API 吗？
会，所以纪律是"基于真实代码写 + 写完后逐段比对"。编出来的内容用 [待验证] 标出。
接口文档怎么对齐官方？
写之前用 documentation-lookup 取最新官方文档，再写，别凭记忆。
README 要多长？
够用就行：定位 / 安装 / 常用命令 / 一个例子 / 常见报错。长文档按读者拆页。
文档怎么不跟着代码过期？
把文档更新绑进 PR 评审，代码改了文档要同步改，别单独攒。
能写设计文档吗？
能，doc-coauthoring 同样适合设计文档和教程，结构给清楚即可。
相关指南
顺着这些场景接着看：
相关源码
- anthropics/skills · doc-coauthoring 源码
- wshobson/agents · api-design-principles 源码
- Agent Skill 开放格式规范
一句话结论
结论：让 AI 基于真实代码和文档写，写完后逐段对源码，别让它凭记忆编 API。