微信扫一扫开发文档自动化 Skill
Overview
把"开发完成"和"文档完成"绑定。本 Skill 提供：
- 4 套标准模板（PRD、API、CHANGELOG、API CHANGELOG）位于
templates/ - 3 个自动化脚本（变更分析、文档更新、文档校验）位于
scripts/ - 3 个 AI prompt 模板（让 LLM 根据 git diff 生成更智能的文档描述）位于
prompts/ - 多语言 API 识别能力：Python（FastAPI/Flask/Django）、Node.js（Express/Koa/NestJS）、Java（Spring）、Go（Gin/Echo/net-http），以及通用 OpenAPI/Swagger 解析
核心原则：每次代码变更都应有对应文档变更——CHANGELOG 是必填项，PRD 在新功能时创建，API 文档在接口变更时同步。
When to Use
应当使用的场景：
- 完成新功能开发，需要补 PRD 和 CHANGELOG
- 修改/新增/废弃 API 接口
- 修复 bug 后需要追加 CHANGELOG（Fixed 段）
- 准备发版，需要把
[Unreleased]转为正式版本 - 收到"生成文档"、"更新文档"、"维护 changelog"、"补充 API 文档"等请求
- 代码 review 时发现文档与代码不同步
不应使用的场景：
- 临时探索性脚本、一次性实验代码（不需要文档化）
- 仅修改注释、格式化、重命名（无用户可见变化）
- 内部重构且不影响外部接口（除非影响显著，仅在 CHANGELOG
Changed段记录） - 项目尚未初始化文档目录（先运行
python scripts/update_docs.py init）
Quick Reference
| 场景 | 必更文档 | 命令入口 |
|------|----------|----------|
| 新功能 | PRD + CHANGELOG（Added）+ API 文档（如有接口） | req → changelog -t added → api -t add |
| 接口变更 | API.md + API_CHANGELOG + CHANGELOG | api -t change → 手动改 API.md |
| Bug 修复 | CHANGELOG（Fixed） | changelog -t fixed |
| 废弃接口 | API_CHANGELOG（标注迁移路径） | api -t deprecate |
| 移除接口 | API_CHANGELOG + CHANGELOG（Breaking） | api -t remove → changelog -t removed |
| 发版 | 把 [Unreleased] 转正 + 打 tag | release --version x.y.z |
| 文档校验 | 校验格式/链接/版本 | validate |
| 文件 | 路径 | 作用 |
|------|------|------|
| PRD 模板 | templates/PRD.md | 需求文档结构 |
| API 模板 | templates/API.md | 接口文档结构 |
| CHANGELOG 模板 | templates/CHANGELOG.md | Keep a Changelog 格式 |
| API CHANGELOG 模板 | templates/API_CHANGELOG.md | 接口变更追踪 |
| 变更分析 | scripts/analyze_changes.py | 解析 git diff，识别 API 改动 |
| 文档更新 | scripts/update_docs.py | 维护 CHANGELOG / API CHANGELOG / PRD |
| 文档校验 | scripts/validate_docs.py | 校验格式、链接、版本一致性 |
| API 文档生成 | scripts/generate_api_doc.py | 从代码/OpenAPI 生成完整 API.md |
| AI Prompt 模板 | prompts/*.md | 让 LLM 写更智能的描述 |
Core Workflow
决策流：来了变更，该走哪条路？
变更类型？
├─ 新功能 ──────────► [W1: 新功能流程]
├─ 接口变更 ────────► [W2: 接口流程]
├─ Bug 修复 ────────► [W3: 修复流程]
└─ 准备发版 ────────► [W4: 发版流程]
W1：新功能流程
# 1. 分析变更，识别 API 改动（多语言自动识别）
python scripts/analyze_changes.py
# 2. 创建需求文档
python scripts/update_docs.py req -n "feature-name" -t "功能标题" -a "Jem"
# → 生成 docs/requirements/REQ-feature-name.md，按 templates/PRD.md 结构
# 3. 追加 CHANGELOG
python scripts/update_docs.py changelog -t added -m "支持邮箱登录"
# 4. 如有新接口
python scripts/update_docs.py api -t add -e "POST /api/auth/login" -d "邮箱密码登录"
# 5.（可选）从代码自动生成 API.md
python scripts/generate_api_doc.py --source ./src --output docs/api/API.md
# 6. 校验文档
python scripts/validate_docs.py
W2：接口变更流程
python scripts/update_docs.py api -t change -e "GET /api/users" -d "新增 status 筛选参数"
# 手动同步 docs/api/API.md 中该接口的参数表与示例
python scripts/update_docs.py changelog -t changed -m "用户列表接口支持按状态筛选"
Breaking Change 必须在 API_CHANGELOG 条目前加
⚠️ Breaking并在 CHANGELOG 中独立成段。
W3：Bug 修复流程
python scripts/update_docs.py changelog -t fixed -m "修复日期跨时区解析错误"
W4：发版流程
# 把 [Unreleased] 段落转换为正式版本，自动注入日期与对比链接
python scripts/update_docs.py release --version 1.2.0
# 同时处理 API_CHANGELOG（如有变更）
python scripts/update_docs.py release --version 1.2.0 --target api
# 打 tag（手动）
git tag -a v1.2.0 -m "Release 1.2.0"
Documentation Structure
每次启动新项目，先运行：
python scripts/update_docs.py init
生成的目录结构：
docs/
├── CHANGELOG.md # 项目变更日志
├── architecture.md # 架构文档（已有则跳过）
├── api/
│ ├── API.md # API 接口详细文档
│ ├── API_CHANGELOG.md # API 变更日志
│ └── openapi.yaml # （可选）OpenAPI 规范
└── requirements/
└── REQ-{feature}.md # 各功能的需求文档
Multi-Language API Recognition
analyze_changes.py 自动识别以下框架的接口定义。所有模式集中在 scripts/api_patterns.py，方便扩展。
| 语言 | 框架 | 识别模式 |
|------|------|----------|
| Python | FastAPI | @app.get(...)、@router.post(...) |
| Python | Flask | @app.route("/path", methods=["POST"]) |
| Python | Django | path("...", view)、url(r"...") |
| Node.js | Express/Koa | app.get("/path", ...)、router.post(...) |
| Node.js | NestJS | @Get(...)、@Post(...) 控制器装饰器 |
| Java | Spring | @GetMapping、@PostMapping、@RequestMapping |
| Go | Gin | r.GET("/path", handler)、r.POST(...) |
| Go | Echo | e.GET(...)、e.POST(...) |
| Go | net/http | http.HandleFunc("/path", ...)、mux.Handle(...) |
| 通用 | OpenAPI 3.0 | 解析 openapi.yaml / openapi.json |
AI Prompt Templates
当 git diff 信息丰富时，仅靠正则无法生成高质量描述。prompts/ 提供了三个为 LLM 设计的 prompt 模板：
| 模板 | 用途 |
|------|------|
| prompts/changelog_from_diff.md | 把 git diff + commit messages → CHANGELOG 用户视角条目 |
| prompts/api_doc_from_code.md | 从代码 + docstring → 完整接口文档段落 |
| prompts/prd_from_feature.md | 从功能描述 + 代码改动 → PRD 草稿 |
在 Cursor / Claude Code 中使用：
用户：帮我用 prompts/changelog_from_diff.md 模板，根据当前 git diff 生成 CHANGELOG
AI 会读取模板、注入 diff、产出符合 Keep a Changelog 风格的条目。
Common Mistakes
| 错误做法 | 正确做法 |
|----------|----------|
| CHANGELOG 写"修改 auth.py" | 写"支持邮箱密码登录"（用户视角） |
| 废弃接口直接删除 | 先用 api -t deprecate 标注迁移路径，下个大版本再删 |
| Breaking Change 不显式标注 | API_CHANGELOG 条目前必须加 ⚠️ Breaking |
| PRD 占位符不替换就交付 | 用 validate_docs.py 检查残留的 {xxx} 与 [待填写：] |
| API 路径硬编码到 PRD | PRD 只列接口清单，详情链接到 API.md |
| 多人同一天编辑 [Unreleased] 冲突 | 让脚本插入新条目（自动避免格式破坏） |
| 一次发版混入未发布的实验功能 | 发版前 review [Unreleased] 段落，移除未发布特性 |
Red Flags - STOP
如果你有这些念头，停下来检查：
- "改动很小，不用更新 CHANGELOG" → 任何用户可见变更都要记录
- "改完代码再补文档" → 代码合并 = 文档同步合并，否则永远不会补
- "API 变了但只改了实现" → 任何外部可观察的行为都是 API 的一部分
- "直接编辑 docs/CHANGELOG.md 更快" → 用脚本以保证格式与链接正确
- "PRD 模板太重，简化几节吧" → 删占位符可，但保留 8 个一级章节框架
Validation Checklist
提交前自检（也可用 python scripts/validate_docs.py）：
- [ ] CHANGELOG 中所有变更条目都从用户视角描述
- [ ] 每个新接口都同时出现在 API.md（详情）和 API_CHANGELOG.md（条目）
- [ ] Breaking Change 已显式标注
⚠️ Breaking - [ ] PRD 已无
{占位符}与[待填写：] - [ ] CHANGELOG 版本号与
package.json/pyproject.toml等一致 - [ ] 文档内的相对链接均可访问
- [ ] 发版条目包含日期，且日期格式为
YYYY-MM-DD
Best Practices
- 频率优先于完美：每次提交都顺手补一行 CHANGELOG，胜过一周后回忆。
- 用户视角描述：CHANGELOG 写"用户能感知的变化"，不是"哪个文件改了"。
- PRD 与代码互链：PRD 链 API.md，API.md 顶部链 PRD，便于追溯。
- 中文注释、中文文档：与代码注释保持一致语种。
- 脚本优先于手改：能用
update_docs.py完成就别手改 Markdown，避免破坏链接定义与格式。 - 校验进 CI：把
validate_docs.py接入 CI，未通过禁止合并。
Cross-References
- 写 SKILL 本身：参见
superpowers:writing-skills - TDD 实现：参见
superpowers:test-driven-development - 验证完成：参见
superpowers:verification-before-completion