lilyjem/dev-docs

开发文档自动化 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

1. 频率优先于完美：每次提交都顺手补一行 CHANGELOG，胜过一周后回忆。
2. 用户视角描述：CHANGELOG 写"用户能感知的变化"，不是"哪个文件改了"。
3. PRD 与代码互链：PRD 链 API.md，API.md 顶部链 PRD，便于追溯。
4. 中文注释、中文文档：与代码注释保持一致语种。
5. 脚本优先于手改：能用 update_docs.py 完成就别手改 Markdown，避免破坏链接定义与格式。
6. 校验进 CI：把 validate_docs.py 接入 CI，未通过禁止合并。

---

Cross-References

• 写 SKILL 本身：参见 superpowers:writing-skills
• TDD 实现：参见 superpowers:test-driven-development
• 验证完成：参见 superpowers:verification-before-completion