技术文档生成 Prompt：让 AI 写出人能看懂的文档

用法

把代码 / API / 功能描述粘进来，配合下面的 prompt。

什么时候用 / 别用

用它：

• 一个已经能跑的功能要有对外文档，而作者本人懒得写（这是它最对的场景）。
• 你要把「口头讲过三遍的部署步骤」固化成一份可复制链接的东西。
• API 已经定稿，需要给接入方一份任务指南。

别用：

• API 还没定稿就先写文档——你会得到一份漂亮的、即将过期的东西。先出 API 设计再写文档，顺序见 API 设计 Prompt。
• 要写的是决策记录 / 架构说明（为什么这么设计、权衡了什么）。这类文档的价值在取舍，而这条 prompt 明确禁止写「设计理念」，会把它写成操作手册。
• 合规 / 法务 / 对外承诺类文本。AI 生成的确定性措辞在法律文本里是风险不是效率。

最容易犯的错：把整仓代码一次粘进去。这条 prompt 一次只该处理一个模块——范围一大，「常用操作按使用频率排序」这条就会退化成「按目录顺序列一遍」。

Prompt

帮我把以下内容写成技术文档。不要写成说明书（「X 是一个用于 Y 的工具」），写成任务指南（「你想做 Z？这样做」）。

## 文档结构

### 这个文档解决什么问题
（1 句话：读者看完能做什么）

### 30 秒上手
（最小可运行示例，不超过 5 步，能 copy-paste 直接跑）

### 常用操作
（按使用频率排序，不是按功能分类排序。每个操作格式：）
- **做 X**：`命令或代码` → 预期结果
- **做 Y**：`命令或代码` → 预期结果

### 常见问题
（列出 3 个最可能遇到的报错，每个给解决方案。不要列「什么是 X」这种概念问题）

### 进阶
（只给链接和一句话描述，不要在这里展开。读者需要时会自己点进去）

## 规则
- 不要写「概述」「背景」「设计理念」——没人看
- 代码示例必须能直接运行，不能有伪代码
- 如果某个操作需要前置条件，在步骤里写明
- 中文输出，代码注释也用中文

---

内容来源：
（粘贴你的代码 / API 定义 / 功能描述）

效果

不加 prompt 时 AI 写的文档通常是：「X 是一个强大的工具，它提供了 A、B、C 功能……」——正确但没人看。

加了这条 prompt 后输出变成任务导向：「你想部署？这样做。你想调试？这样做。」——读者可以直接找到自己要做的事。

一个对照例子

给同一个"图片上传 API"写文档：

说明书式（没人看）：

"本模块提供图片上传能力，支持多种格式，具备完善的错误处理机制和灵活的配置选项……"

读者看完还是不知道怎么传一张图。

任务指南式（这条 prompt 的产出）：

30 秒上手

curl -F "file=@photo.jpg" https://api.x.com/upload -H "Authorization: Bearer $TOKEN"
# 返回 {"url": "https://cdn.x.com/abc.jpg"}

常见问题

• 413 Payload Too Large：单文件上限 10MB，压缩后重试。
• 415 Unsupported Media Type：只收 jpg/png/webp。

后者读者复制就能跑，报错也知道怎么办——这才是文档的目的。

验收判据：怎么判断这次生成是合格的

别用「读起来通顺」当标准，那是一条任何人都能自我说服的标准。用这四条：

最狠的一条是第二条。 AI 生成文档最典型的失败不是写错，而是写出一个看起来很专业、但你的代码里根本不会发生的错误场景——因为它见过一千个同类项目，而你这个不是其中之一。

变体

A. 一次只改一段（适合已有文档的增量维护）

下面是一份现有文档的一个小节，以及本次的代码变更 diff。
只重写受影响的小节，其他部分原样保留，不要重写整篇。
如果变更不影响任何小节，明确回答「无需更新」。

B. 面向「接手的人」而非「使用者」

把读者假定为刚接手这个模块、没有上下文的新同事。
每个操作步骤都要说明「为什么必须这一步」，以及跳过会怎样。
最后补一节「历史包袱」：列出三处看起来不合理但不能改的地方，并说明原因。

C. 管道化（把文档生成接进终端流水线）

# 只 regenerate 变更模块，输出到 stdout 直接看 diff
changed=$(git diff --name-only origin/main...HEAD -- "src/**")
[ -n "$changed" ] && cat "$changed" | claude -p "$(cat prompts/doc-generation.txt)" > /tmp/doc.md

# 与现有文档对比，人工 review 增量而不是全文
diff -u docs/upload.md /tmp/doc.md | less

claude -p 是非交互管道模式；同理可用于 Codex / Gemini CLI / Qwen Code。管道化的价值在于「文档 diff」变成可 review 的产物，而不是每次重写全文。

为什么有效

• 指定读者：文档灾难的头号原因是「写给所有人」，写进 prompt 的受众约束会直接改变用词与深度。
• 要求「为什么」而非只写「怎么做」：没有动机说明的文档三个月后没人敢改，因为没人知道哪些是历史包袱。
• 强制给出可运行示例：示例是唯一能被自动验证的部分，也是读者真正会复制粘贴的部分。

进阶（自动化）

把文档生成挂到 CI，让「文档过期」变成可检测事件：

# 只 regenerate 变更模块对应的文档，人工 review diff
changed=$(git diff --name-only origin/main...HEAD -- "src/**")
[ -n "$changed" ] && ai-doc --files "$changed" --out docs/ && git diff --stat docs/

延伸阅读

• API 设计 Prompt — 先设计好 API 再写文档
• 什么是 Prompt Engineering — 为什么"给反例约束"比"夸要求"更有效