07 - 文档写作食谱
让 AI 帮你写出开发者愿意读的技术文档。
适用场景
| 场景 | 典型触发时机 | 产出物 |
|---|---|---|
| 项目 README | 项目初始化、重大功能发布 | 完整 README.md |
| API 接口文档 | 新增/修改 API 端点后 | OpenAPI spec 或 Markdown API 文档 |
| CHANGELOG 生成 | 版本发布前 | 结构化变更日志 |
| 架构决策记录 | 重大技术决策后 | ADR 文档 |
| 内联代码注释 | 代码审查发现注释缺失 | JSDoc / docstring / 行内注释 |
| 用户面向文档 | 功能开发完成、用户反馈文档缺失 | 操作指南、教程、FAQ |
食谱 1：项目 README
场景描述
项目初始化或重大版本发布时，需要一份结构完整的 README，让新用户 30 秒内理解项目价值、3 分钟内跑通示例。
核心模板
text
为项目 {{项目名}} 编写 README.md。
项目定位：{{一句话描述项目用途}}
技术栈：{{主要技术栈列表}}
包管理器：{{npm/pnpm/yarn}}
部署目标：{{部署平台}}
README 结构要求：
1. 项目标题 + 一句话描述 + 徽章行（CI 状态、版本号、许可证）
2. 功能特性列表（3-7 条核心特性）
3. 快速开始（前置条件 → 安装 → 运行，可复制粘贴直接执行）
4. 使用示例（最常见的 2-3 个用法，附代码块）
5. 项目结构概览（只列关键目录，不超过 15 行）
6. 开发指南（本地开发、测试、构建命令）
7. 许可证
参考项目中已有的 {{参考文件路径}} 了解实际目录结构。
徽章使用 shields.io 格式。安装步骤必须可直接执行，不写伪代码。变量说明
| 变量 | 说明 | 示例 |
|---|---|---|
{{项目名}} | 项目名称 | ai-dev-cli |
{{一句话描述项目用途}} | 项目核心价值 | AI 辅助编程工程化 CLI 脚手架 |
{{主要技术栈列表}} | 核心依赖 | Node.js, TypeScript, Commander.js |
{{npm/pnpm/yarn}} | 包管理器 | pnpm |
{{部署平台}} | 运行/部署环境 | npm registry + Cloudflare Pages |
{{参考文件路径}} | 实际结构来源 | package.json 或项目根目录 |
好坏对比
text
❌ "帮我写个 README"
→ 没有项目信息、没有结构要求，AI 会生成通用模板，与实际项目脱节。
✅ "为项目 ai-dev-cli 编写 README.md。
项目定位：个人开发者 AI 辅助编程工程化 CLI 工具。
技术栈：Node.js + TypeScript + Commander.js。
包管理器：pnpm。发布到 npm，用 npx ai-dev-cli init 使用。
参考 package.json 和 cli/src/ 目录结构。
徽章用 shields.io，安装步骤必须可直接粘贴执行。"实战案例
text
为 cli/ 子目录编写 README.md。
项目定位：npx ai-dev-cli init 一键初始化 AI 辅助编程工程化配置。
技术栈：Node.js 18+, TypeScript, Commander.js, Inquirer.js。
README 需要包含：
1. 标题 + npm 版本徽章 + 下载量徽章
2. 一句话描述 + 功能列表
3. 快速开始：npx ai-dev-cli init
4. 命令参数说明表格
5. init 后生成的文件结构说明
6. 本地开发步骤（clone → install → build → link）
7. MIT 许可证
参考 cli/package.json 和 cli/src/commands/ 了解实际命令。Claude 增强 💡
使用 /doc Skill 可在代码变更后自动检测哪些文档需要更新，包括 README。配合 /commit Skill 可在提交时自动检查 README 是否与代码变更同步。
食谱 2：API 接口文档
场景描述
新增或修改 API 端点后，从代码中提取路由、参数、响应格式，生成结构化的 API 文档。
核心模板
text
为 {{API 目录路径}} 下的所有 API 端点生成文档。
文档格式：{{Markdown 表格/OpenAPI YAML/单独页面}}
认证方式：{{JWT/API Key/无}}
每个端点包含：
1. 方法 + 路径 + 一句话描述
2. 请求参数（路径参数、查询参数、请求体）附类型和必填标记
3. 响应格式（成功响应 + 错误响应）附 JSON 示例
4. 认证要求
5. 使用示例（curl 命令）
从代码中提取实际的 zod schema / TypeScript 类型作为文档来源，
不要编造参数。如果代码中没有校验，标注"⚠ 缺少校验"。变量说明
| 变量 | 说明 | 示例 |
|---|---|---|
{{API 目录路径}} | API 路由文件所在目录 | app/api/ 或 src/routes/ |
{{Markdown 表格/OpenAPI YAML/单独页面}} | 输出格式偏好 | Markdown 表格 |
{{JWT/API Key/无}} | 认证机制 | Bearer JWT |
好坏对比
text
❌ "生成 API 文档"
→ 不知道哪些 API、什么格式、从哪里读取类型信息，AI 会编造参数。
✅ "读取 app/api/ 下所有 route.ts 文件，
提取 GET/POST/PUT/DELETE handler。
从 zod schema 提取请求参数类型，
从 NextResponse 提取响应格式。
输出 Markdown 表格，每个端点附 curl 示例。
没有 zod 校验的端点标注 ⚠。"实战案例
text
为 app/api/users/ 下的 API 生成文档。
已有端点：
- GET /api/users — 用户列表（分页）
- POST /api/users — 创建用户
- GET /api/users/[id] — 用户详情
- PUT /api/users/[id] — 更新用户
- DELETE /api/users/[id] — 删除用户
从每个 route.ts 中的 zod schema 提取参数类型。
输出格式：每个端点一个二级标题，包含描述、参数表格、
成功/失败响应 JSON 示例、curl 命令。
基础 URL 使用 http://localhost:3000。Claude 增强 💡
让 Claude 直接读取路由文件并自动发现端点：先读取 app/api/ 下所有 route.ts，列出发现的端点，然后逐个生成文档。 配合 /doc Skill 可在每次 API 变更后自动触发文档更新检查。
- 如果项目已采用 Zod → OpenAPI 自动生成工作流，API 文档无需手写——运行
npm run generate:openapi生成docs/openapi.json，在文档站用 Scalar 渲染。本食谱仍适用于未接入自动生成的项目。详见 doc-17 API 接口维护体系
食谱 3：CHANGELOG 生成
场景描述
版本发布前，根据 git 提交历史生成符合 Keep a Changelog 格式的变更日志，分类清晰、面向用户可读。
核心模板
text
根据 git log 生成 CHANGELOG 条目。
版本号：{{新版本号}}
上一版本 tag：{{上一版本 tag}}
日期：{{发布日期}}
执行步骤：
1. 运行 git log {{上一版本 tag}}..HEAD --oneline 获取提交列表
2. 按 Conventional Commits 前缀分类：
- feat → Added / fix → Fixed / perf,refactor → Changed
- docs,chore,ci → 不记入（除非面向用户的文档变更）
- BREAKING CHANGE → 在顶部单独标注
3. 改写为面向用户的语言（不写实现细节，写用户感知的变化）
4. 追加到 CHANGELOG.md 顶部，保留历史条目变量说明
| 变量 | 说明 | 示例 |
|---|---|---|
{{新版本号}} | 即将发布的版本 | v2.1.0 |
{{上一版本 tag}} | 上个版本的 git tag | v2.0.0 |
{{发布日期}} | 发布日期 | 2026-02-19 |
好坏对比
text
❌ "更新 CHANGELOG"
→ 不知道版本范围、不知道格式要求，可能直接粘贴 git log 原文。
✅ "运行 git log v2.0.0..HEAD --oneline，
按 Keep a Changelog 格式生成 v2.1.0 的条目。
feat → Added，fix → Fixed，其他忽略。
用面向用户的语言描述变更，不写代码细节。
追加到 CHANGELOG.md 顶部。"实战案例
text
为 ai-dev-cli v2.1.0 更新 CHANGELOG.md。
上一版本 tag：v2.0.0，发布日期：2026-02-19。
步骤：
1. 读取 git log v2.0.0..HEAD --oneline
2. 生成条目格式：
## [2.1.0] - 2026-02-19
### Added
- 新增 /features 技能，支持功能清单全景视图
### Fixed
- 修复 Skills 数量统计不一致的问题
3. 追加到 CHANGELOG.md 顶部，不修改历史条目Claude 增强 💡
在 CLAUDE.md 中配置 修改文档后必须同步更新 CHANGELOG.md 规则后，Claude 会在每次文档变更时自动维护 CHANGELOG。使用 /commit Skill 可在提交时自动检查 CHANGELOG 是否跟上代码变更。
食谱 4：架构决策记录（ADR）
场景描述
做出重大技术决策后，从文档写作角度记录决策全貌，供未来回溯。与 01 食谱 6 互补——01 侧重决策过程中的对比分析，本食谱侧重决策完成后的标准化文档产出。
核心模板
text
为以下技术决策编写 ADR（架构决策记录）。
决策主题：{{决策主题}}
决策背景：{{面临的问题和触发原因}}
最终选择：{{选定的方案}}
考虑过的替代方案：{{备选方案列表}}
ADR 格式：
# ADR-{{编号}}: {{决策标题}}
## 状态 — Accepted / Proposed / Deprecated
## 上下文 — 面临什么问题，为什么需要决策（2-3 句话）
## 决策 — 最终选择了什么（1-2 句话）
## 理由 — 为什么选这个，核心论据是什么
## 考虑过的替代方案 — 每个方案附未选择的原因
## 影响 — 正面收益 + 负面代价/约束
保存到 {{ADR 文件路径}}。语言简洁直接，不写空话。变量说明
| 变量 | 说明 | 示例 |
|---|---|---|
{{决策主题}} | 决策的核心问题 | 文档站框架选择 |
{{面临的问题和触发原因}} | 为什么需要做决策 | 需要部署设计文档，支持中文和密码保护 |
{{选定的方案}} | 最终选择 | VitePress + Cloudflare Pages |
{{备选方案列表}} | 曾考虑的其他选项 | Docusaurus, Nextra, Notion |
{{编号}} | ADR 序号 | 003 |
{{ADR 文件路径}} | 存储路径 | docs/adr/ADR-003.md |
好坏对比
text
❌ "记录一下我们为什么选了 VitePress"
→ 缺少结构要求，输出可能是一段散文，无法标准化检索和回溯。
✅ "编写 ADR-003: 文档站框架选择。
背景：需要部署 17 篇设计文档，支持中文路径、密码保护、Cloudflare 部署。
选择：VitePress + Cloudflare Pages。
替代方案：Docusaurus（SSR 配置复杂）、Nextra（依赖 Next.js 过重）、
Notion（不支持自定义域名和密码保护）。
用标准 ADR 格式，保存到 docs/adr/ADR-003.md。"实战案例
text
编写 ADR-003: 文档站框架选择。
上下文：项目有 17 篇中文设计文档，需要部署为可搜索的文档站。
要求：支持中文文件名、密码保护、可部署到 Cloudflare Pages。
候选方案：
1. VitePress — 轻量、Markdown 原生、Cloudflare 部署简单
2. Docusaurus — 功能丰富但 SSR 配置和中文路径处理复杂
3. Nextra — 依赖 Next.js 全栈框架，对纯文档站过重
4. Notion 公开页 — 无法自定义域名，不支持密码保护
最终选择：VitePress + Cloudflare Pages，用 sync.mjs 将中文文件名映射为英文 slug。
用标准 ADR 格式输出，保存到 docs/adr/ADR-003.md。Claude 增强 💡
在 CLAUDE.md 中配置 重大架构决策时创建 ADR 规则后，Claude 在识别到重大决策时会主动提醒。使用 /doc Skill 会在变更检查中提示是否需要新增 ADR。
食谱 5：内联代码注释
场景描述
代码审查发现注释缺失，或需为公开 API 添加 JSDoc/docstring。关键原则：注释解释"为什么"而非"做什么"——过度注释和缺少注释一样有害。
核心模板
text
为 {{文件路径}} 添加内联注释。
注释规范：
- 导出函数/类：添加 {{JSDoc/docstring/GoDoc}}，含功能描述、参数、返回值、异常
- 复杂逻辑块：注释"为什么"，不注释"做什么"（代码本身说明做什么）
- 魔术数字/正则：解释含义和来源
- TODO/FIXME：保留但补充具体原因
- 不注释：简单 getter/setter、一眼能懂的代码
注释语言：英文
不要修改任何代码逻辑，只添加注释。变量说明
| 变量 | 说明 | 示例 |
|---|---|---|
{{文件路径}} | 需要添加注释的文件 | src/services/auth.service.ts |
{{JSDoc/docstring/GoDoc}} | 注释格式规范 | JSDoc（TS）、docstring（Python） |
好坏对比
text
❌ "给代码加注释"
→ 会在每一行都加注释，包括 i++ 这种显而易见的代码，产生噪音。
✅ "为 src/services/auth.service.ts 添加注释。
导出函数加 JSDoc（描述、@param、@returns、@throws）。
复杂逻辑只注释'为什么'，不注释'做什么'。
魔术数字解释含义。注释用英文。不修改任何代码逻辑。"实战案例
text
为 cli/src/commands/init.ts 添加内联注释。
要求：
1. 文件顶部添加模块描述注释
2. 导出函数添加 JSDoc（@description, @param, @returns, @example）
3. 复杂条件判断添加 "why" 注释，例如：
// Skip if .claude/ already exists to avoid overwriting user config
4. 正则表达式添加含义说明
5. 不在简单赋值或显而易见的代码上加注释
注释语言：英文。不修改任何代码逻辑。Claude 增强 💡
可以批量处理：读取 src/services/ 下所有 .ts 文件，找出缺少 JSDoc 的导出函数，列出清单后逐个补充。 结合代码审查流程，使用 /commit Skill 在提交前确认关键函数有注释覆盖。
食谱 6：用户面向文档
场景描述
功能开发完成后，为终端用户编写操作指南、教程或 FAQ，确保"用户读了就能用"。
核心模板
text
为 {{功能名称}} 编写用户文档。
目标读者：{{读者画像}}
文档类型：{{快速入门/操作指南/教程/FAQ}}
前置知识：{{读者需要具备的基础知识}}
文档结构：
1. 概述 — 这个功能解决什么问题（1-2 句话）
2. 前置条件 — 需要准备什么（环境、权限、账号等）
3. 操作步骤 — 分步骤说明，每步附预期结果
4. 常见问题 — 3-5 个高频问题及解答
5. 下一步 — 引导到相关功能或进阶用法
写作要求：
- 每步只做一件事，命令用代码块包裹可直接复制
- 关键操作附截图占位符 
- 专业术语首次出现时给出简短解释
- 不假设读者了解项目内部实现变量说明
| 变量 | 说明 | 示例 |
|---|---|---|
{{功能名称}} | 要文档化的功能 | CLI 初始化工具 |
{{读者画像}} | 目标用户描述 | 有基础命令行经验的前端开发者 |
{{快速入门/操作指南/教程/FAQ}} | 文档类型 | 快速入门 |
{{读者需要具备的基础知识}} | 前提知识 | 了解 npm/npx 基本用法 |
好坏对比
text
❌ "写个使用文档"
→ 不知道读者是谁、需要什么深度，输出可能过于技术化或过于浅显。
✅ "为 ai-dev-cli init 命令编写快速入门文档。
读者：有基础命令行经验的前端开发者，首次接触本工具。
结构：概述→前置条件→三步上手→常见问题→下一步。
每步附命令代码块和预期输出。
专业术语首次出现附解释。不假设读者了解项目内部实现。"实战案例
text
为 AI 辅助编程工程化 CLI 工具编写快速入门指南。
目标读者：个人开发者，有 Node.js 基础，首次使用本工具。
前置条件：Node.js 18+，已有项目仓库。
文档结构：
## 概述 — 一句话说明 ai-dev-cli 解决什么问题
## 三步上手
步骤 1：npx ai-dev-cli init → 展示交互式选项和预期输出
步骤 2：检查生成的文件及用途（CLAUDE.md、.claude/skills/ 等）
步骤 3：在 Claude Code 中使用 Skills
## 常见问题
- 已有 CLAUDE.md 怎么办？/ 可以选择性安装吗？/ 支持哪些项目类型？
## 下一步 — 链接到进阶配置、Skills 列表、设计文档
写作风格：简洁友好，命令可直接复制执行。Claude 增强 💡
使用 /doc Skill 在代码变更后自动检测是否需要更新用户文档。对于文档站场景，可将用户文档同步到 VitePress 站点并用 /commit Skill 确保文档变更被正确提交。
组合技巧
新版本发布文档全流程
text
即将发布 {{版本号}}，请执行文档更新全流程：
1. 根据 git log {{上一版本}}..HEAD 生成 CHANGELOG 条目
2. 更新 README.md 中的版本号和新增功能描述
3. 检查 API 文档是否需要更新（对比 API 路由文件的 diff）
4. 如有重大技术变更，提醒我是否需要新建 ADR
每步完成后报告结果，不要一次性全部执行。从零搭建项目文档体系
text
为项目搭建最小文档体系：
1. 生成 README.md（徽章 + 安装 + 使用 + 项目结构）
2. 创建 docs/approved-deps.md 依赖白名单
3. 为核心模块的导出函数补充 JSDoc
4. 创建第一个 ADR（项目技术栈选择）
先列出计划，我确认后再逐步执行。代码变更后文档同步
text
刚完成 {{功能描述}} 的代码实现。请检查以下文档是否需要更新：
- README.md — 新功能是否需要添加到特性列表
- API 文档 — 是否有新增/修改的端点
- CLAUDE.md — 是否有新模块/命令需要记录
- 用户文档 — 是否影响用户操作流程
列出需要更新的文档及更新要点，我确认后再执行。相关资源
- doc-06 文档体系 — 文档层级设计与 ADR 模板
- doc-15 §3.8 知识沉淀 — Prompt 理论框架与高频速查表
- /doc Skill — 代码变更后自动检查文档更新
- /commit Skill — 提交时检查文档同步状态
- 01-架构设计食谱 §食谱6 — ADR 的架构决策视角（与本文食谱 4 互补）
- 06-重构优化食谱 — 重构后的文档同步场景