关于 tech-review-doc
将代码密集型设计文档转为面向产品、QA 和非深度开发读者的技术评审文档。流程先确认业务背景与目标，再按需生成图表和评审章节，并要求用户明确批准 §1 后才能继续。
主要功能
- 01按模板生成技术评审文档
- 02先澄清并确认业务目标
- 03使用 Mermaid 绘制必要图表
- 04按需比较方案并总结核心内容
- 05设置评审确认门槛与输出规则
适用场景
- 01将实现设计整理为产品与 QA 可读的评审材料
- 02在写评审文件前确认背景、目标和验收重点
- 03从复杂设计中提炼模块变更、数据流与风险
安装
复制下面的命令，在终端中运行。
npx skills add https:/安装后在 Claude Code 中输入/tech-review-doc确认已加载。
附带文件template.md
详细介绍
技术设计 → 技术评审文档
将代码密集型设计文档转换为面向不深入了解代码的产品、QA 和工程师的技术评审文档。
核心原则
| 原则 | 要求 |
|---|---|
| 受众 | 不深入了解代码的读者能够独立理解第 1–4 节 |
| 语言 | 简洁明了；第 1–3 节不含任何代码；从第 4 节起，仅保留必要接口／字段／表格的用途 |
| 图表 | 使用 Mermaid；节点使用业务／模块名称，而非类名或文件名 |
| 事实来源 | 设计文档是事实依据；用户确认的内容优先于含糊的设计表述 |
| 简洁 | 对每一节都问：“评审会议上有人需要这些内容吗？”——如果不需要，就省略 |
| 模板 | 使用同级目录中的 template.md |
输入
| 输入 | 说明 |
|---|---|
| 设计文档路径（必填） | 用户输入的 @ 或路径 |
| 评审类型（可选） | 方案／实现／验收评审；默认为方案评审 |
开始前完整阅读设计文档；必要时查阅相关 PRD 或 OpenSpec 变更。
如果设计文档超过约 1500 行，先浏览结构和标题，再按需深入阅读相关章节。
输出
在输入文档所在目录生成文件，命名为 tech-review-{topic}-{YYYY-MM-DD}.md。
从设计文档标题关键词中提取 {topic}；YYYY-MM-DD 使用当前日期。
流程（五个步骤，设有硬性门槛）
Step 0 Startup check
↓
Step 1 Background & goals (clarify; no file write until user approves §1)
↓ user explicitly approves §1
Step 2 Generate §2 necessary diagrams (ask if unsure)
↓
Step 3 Multi-option comparison → §3 (skip if none)
↓
Step 4 Core content summary → §4
↓
Step 5 Complete §§5–7 and write the file
前置技能检查
加载时，确认 clarifying-question-discipline 可用。如果缺失，则中止并输出：
npx skills add FuDesign2008/open-skills -g --skill clarifying-question-discipline --yes
不得悄悄采用替代方案。
步骤 0：启动检查
- 确认设计文档路径；如果缺失或无效，则询问用户
- 阅读同级目录中的
template.md - 从设计文档中提取：标题、界面／模块、是否存在多方案比较、现有 Mermaid 图表
- 用 3–5 句话复述理解，并说明接下来将开始步骤 1 的澄清
步骤 1：背景与目标（必做）
设计背景通常是为工程师撰写的。评审文档第 1 节必须使用面向产品／QA 的业务语言。
遵循 clarifying-question-discipline：每轮只问一个问题，进行多轮提问，直到信息清晰；如果 Agent 支持，优先使用结构化单选题；如果可以确定默认答案，则提供推荐选项。只描述提问意图——不要硬编码特定平台的提问工具。
1.1 目标
共同确认并完善第 1 节：背景与目标。将设计文档中的背景视为草稿——绝不要原样粘贴。
1.2 覆盖范围（根据需要分轮提问）
业务动机、用户场景、成功标准、非目标，以及产品／QA 需要了解的术语。
在请求确认之前，先将技术动机转化为业务语言。
1.3 建议问题（每次选择一个）
- 这主要要解决谁的什么问题？
- 如果不采取行动，会带来什么业务成本？
- 用户／运营人员能够直接感知到什么变化？
- 最重要的一项 QA 验收检查是什么？
- 哪些内容明确不在范围内？
- 是否有术语需要改成对产品／QA 更友好的说法？
1.4 交付内容与门槛
- 提交第 1 节草稿（仅使用业务语言，不含代码）
- 询问：“这份背景和目标是否准确？您确认后，我会生成图表和完整文档。”
- 只有在用户明确确认后，才能进入步骤 2
步骤 2：第 2 节解决方案概览（图表）
2.1 需要时选择图表
| 图表 | 适用情况 |
|---|---|
| 系统拓扑图 | ≥2 个客户端／部署边界 |
| 架构图 | 模块职责需要单独展示 |
| 数据流图 | 配置／状态跨模块流转，或涉及迁移 |
| 逻辑流程图 | 主流程包含分支、校验或失败路径 |
不确定时请询问用户。只绘制必要的图表；从文档中省略未使用的图表类型。
2.2 绘图规则
- 重写 Mermaid 图表以反映设计；不要复制包含代码符号的图表
- 每张图表：包含标题和 1–2 句说明，并联系 §1 中的目标
- §2.1 解决方案摘要：2–3 句
第 3 步：§3 方案与选择（有条件）
| 情况 | 操作 |
|---|---|
| 存在实质性的多方案比较 | 生成 §3（仅包括决策背景、比较表和选择结论） |
| 仅有一个选定方案，没有比较 | 跳过 §3 |
比较维度：目标契合度、用户体验、交付成本、风险／回滚、长期维护。
第 4 步：§4 核心内容摘要
保留
- 变更范围（产品模块名称）
- 主要流程；关键数据／配置的含义；存储和迁移
- 接口变更的业务含义（融入流程叙述；不单独列出 API 表）
删除或精简
- 函数签名、类名、大段代码／JSON
- 单元测试文件名、提交级别的改动
- 独立的接口／契约表
自检：对业务不熟悉的开发者读完 §4 后，能够回答“哪些区域会变更、数据如何流转、旧数据会如何处理”。
第 5 步：§§5–7 并写入文件
| 部分 | 要点 |
|---|---|
| §5 风险与边界 | 风险列表（必需）+ 已知限制（必需）；仅在相关时提及安全／合规 |
| §6 发布与运维 | 有条件：仅在涉及金丝雀发布／逐步发布或服务端数据回填时包含；否则省略 |
| §7 结论 | 起草结论 + 待办事项 |
写入文件后，移除模板末尾的“模板使用说明”部分。在聊天中报告：输出路径、§1 是否已确认、生成了哪些图表、是否跳过 §3／§6，以及留给用户的任何占位符。
语言转换参考
| 技术表述 | 评审表述 |
|---|---|
| 调用 API / RPC | A 向 B 请求数据 |
| 写入 Redis / 缓存 | 暂时记住此状态，以便下次使用 |
| 数据库迁移 | 按新规则重新整理旧数据 |
| 推送配置 | 管理员规则同步到客户端 |
| 降级／回退 | 失败时自动回退到旧路径 |
| 幂等 | 重复执行不会产生额外副作用 |
| 事务 | 要么全部成功，要么不做任何更改 |
优先说明“谁对谁做了什么，以及用户看到什么”，而非实现细节。
宿主自动模式约定
在 write-workflow 自动模式下调用时：
- §1 的 HARD-GATE 仍然适用——用户明确批准 §1 之前，不得写入文件，也不得执行第 2–5 步。
- §1 获得批准后，第 2–5 步可连续执行（图表 → 其余章节 → 写入文件），无需逐步确认。
- 独立调用或手动宿主调用仍遵循第 1.4 步中的交互式 §1 门槛。
与其他技能的关系
| 技能 | 关系 |
|---|---|
clarifying-question-discipline | 第 1 步的强依赖 |
write-workflow | 可选宿主（八阶段），默认将此技能用于技术评审写作 |
成功标准
- 用户明确确认了第 1 步
- §§1–3 除 Mermaid 外不含代码块
- §2 仅包含必要图表
- 按规则生成或跳过 §3
- 按规则生成或跳过 §6
- §4 不是代码堆砌
- 文件已写入，并包含可追溯至设计文档的链接
- 路径和命名符合输出规则