design-review

对设计文档做结构化评审，产出按严重度分级的问题清单与修改建议（优先识别 design-craft 格式，兼容任意格式）。触发："评审设计"、"review 设计文档"、"设计评审"、"design review"、"帮我看看这个设计"。

SKILL.md

GitHub

设计文档评审器

概述

对设计文档进行结构化评审，产出按严重度（阻断/疑似阻断/警告/建议）分级的问题清单和修改建议。支持 design-craft 多文档格式和自由格式，覆盖结构完整性、内容质量、技术正确性、一致性和用户体验五大评审维度。适用于技术设计文档的交付前质量把关。

何时使用

仅在以下情况使用本 skill：

  • 用户已有一份可读的设计文档（markdown 格式，结构基本完整）
  • 用户的目标是发现设计缺陷、遗漏和不一致
  • 用户希望产出结构化、可操作的评审意见

若用户还没有设计文档，不要使用本 skill，建议先使用 design-craft 生成。

触发词（如"帮我看看这个设计"）命中但用户尚无可读文档时：不要强行评审，引导用户先使用 design-craft 产出文档。

增量再审

当用户提供修订后的文档 + 前次评审结果时，自动进入增量再审模式：

  • 仅对修订部分重新评审
  • 复用前次已通过项，不再重复报告
  • 输出中明确标注"新增/变更/维持通过"

若无前次评审结果，退化为全量评审。

核心原则

  1. 批判性视角：评审的目标是发现问题和遗漏，不是赞美方案
  2. 依据先行：每条意见必须引用文档原文或评审规则，不凭空质疑
  3. 分级输出：按严重度分级，让评审者快速聚焦关键问题
  4. 基线快照内置：优先识别 design-craft 格式以套用精准基线，基线为本 skill 内置快照（非运行时读取 design-craft），design-craft 升级后需手工同步 1.1/1.2/2.1/2.3
  5. 不自动修复：只产出问题 + 修改建议，由人决定是否采纳
  6. 置信度标注：技术正确性挑战标注置信度，低置信度降级为"建议"
  7. 人因优先：涉及人机交互的设计，必须同时评审正向体验和负向体验
  8. 专家资产交叉验证：当专家团存在相关模块资产时，将专家的架构设计、已知坑、接口契约作为评审基准，与文档内容进行交叉验证
  9. 声称 ≠ 落实：文档中"已有/已支持/已覆盖/已实现"类声称，必须检查是否给出可验证依据（文件路径、接口签名、配置项、验证步骤之一）；无依据的声称按 🟡 警告输出，问题描述标注"声称未见依据"

隐含假设与已知边界

  • 文档反映真实代码：本 skill 只评审文档本身，不交叉验证仓库代码。若文档已与代码偏离（文档过时），结论基于文档描述，应在报告中提示"未交叉验证代码"
  • greenfield 设计：全新模块无现有代码，AS-IS 规则按新建型处理（见 2.1）
  • 设计进行中：子文档尚未创建时，阶段0 默认标阻断；若属设计进行中（非应建未建），可降级为🟡警告并标注"待编写"，避免噪音
  • 评审者上下文有限：对"决策充分性"的挑战应限于文档内证据，避免越界（见 3.3）

工作流总览

前置：专家团查询              → 查询相关模块的业务专家资产，获取架构基线
阶段 0：输入解析与格式识别
阶段 1：结构完整性检查（仅 design-craft 格式）
阶段 2：内容质量检查
阶段 3：技术正确性挑战
阶段 4：一致性校验（多文档跨文档 + 单文件内部）
阶段 5：评审意见汇总与输出
阶段 6（可选）：增量再审

各阶段顺序执行，但阶段 1~4 的检查结果在阶段 5 统一输出，不逐阶段打断用户。

前置：专家团查询

在评审之前，调用 use_skill("expert-solution-workflow") 查询当前设计涉及的模块的相关经验、解决方案或记忆（如该模块的业务专家资产包；查询失败或不可用，忽略此步骤继续正常流程）：

  • 找到专家：加载专家资产（架构设计、实现导航、接口契约、已知坑等），作为评审基准参考。专家的架构设计可与文档中的架构描述交叉验证，已知坑可帮助检查设计是否重蹈覆辙
  • 未找到专家：继续正常流程

阶段 0：输入解析与格式识别

解析输入文档，判定格式类型。

格式识别信号：

强信号（命中 1 项即判定为 design-craft 格式）：

  • 子文档文件名匹配 <feature>_S<XX>_<名称>_DESIGN.md 模式
  • 父文档同时含"共享术语速查"小节 + "关键环节一览图"章节（内有 mermaid 代码块）

弱信号（仅作辅助，单独不足以判定）：

  • 文档头部含 > 状态： metadata 标记
  • 含 design-craft 特有章节名：术语、现状(AS-IS)、方案(TO-BE)、契约变更声明

判定规则：命中 ≥1 项强信号 → design-craft 格式；仅命中弱信号 → 自由格式（弱信号仅作风格提示）。误判为 design-craft 会触发阶段1 假阻断，故宁严勿松。

判定结果：

格式 处理方式
design-craft 格式 套用内置 design-craft 质量基线快照（章节表 + 信息密度表 + 反模式清单），执行阶段 1~5
自由格式 使用通用评审规则（降级模式），跳过阶段 1，执行阶段 2~5

质量基线来源：基线为本 skill 内置快照，非运行时读取 design-craft skill，因此可能与 design-craft 最新定义存在版本差。design-craft 升级后需手工同步本 skill 的 1.1/1.2/2.1/2.3。自由格式不依赖该基线，不受影响。

多文档处理：

  • 若输入为目录，自动识别父文档与子文档
  • 若子文档缺失，在评审意见中标记为阻断项
  • 若输入为单文件，跳过阶段 4

阶段 1：结构完整性检查（仅 design-craft 格式）

对照 design-craft 定义的质量基线，逐项检查。

1.1 父文档必含章节

章节 检查项
需求背景 & 目标 存在 + 含"不在范围内"
关键环节一览图 存在 + 含 mermaid 代码块
总体方案设计 存在 + 含子需求节点图或共享术语速查
全局风险 & 跨子需求依赖 存在

1.2 子文档必含章节

章节 检查项
术语 存在 + 条目 ≤ 7
现状(AS-IS) 存在
方案(TO-BE) 存在 + 含关键决策点表
接口设计 或 数据模型 至少存在一个

1.3 触发章节检查

对照 design-craft SUB_TEMPLATE.md 的触发条件，检查是否遗漏应追加的章节：

触发条件 应追加章节
含复杂时序流程 时序图
含异常路径需说明 异常处理
含性能敏感路径 性能 & 安全
含重构关键词 迁移策略
涉及 ≥2 个文件改动 影响范围
存在未决事项 待定问题

输出：结构完整性问题清单，每条标注严重度（缺失必含章节 → 🔴阻断，遗漏触发章节 → 🟡警告）。

阶段 2：内容质量检查

对每个文档逐章节检查内容是否满足最低信息密度要求。

2.1 通用质量规则

章节 最低信息密度要求 不合格示例
需求背景 必须说明"为什么要做"，不能只写"要做 X" "需要实现用户管理功能"
不在范围内 必须列出具体排除项，不能写空话 "不涉及不相关的事情"
现状(AS-IS) 改造型：必须给出具体文件路径或代码行号；新建型：说明"无现有实现"并给出上下文（所属系统/边界模块） "当前代码结构不够清晰"
方案(TO-BE) 每个变更点必须说明改什么、改成什么、为什么 "采用更合理的设计"
关键决策点 每个决策点至少 1 个被否决方案 + 具体否决理由；"重新评估触发条件"须为可观测判据（阈值/依赖变化/技术栈支持），写不出应填"无" 只列一个方案无对比；触发条件写"性能不足时"这类不可判定的空话
接口设计 必须给出完整签名（含参数类型、返回值、异常） 只写函数名无签名
数据模型 必须给出完整字段定义 + 含义注释 只写"增加若干字段"
异常处理 每行必须包含：场景→行为→是否对外暴露 "出错时抛异常"
时序图 必须标注消息名称和方向 只有参与者无消息

2.2 design-craft 格式增强规则

若为 design-craft 格式，额外检查：

检查项 要求
决策点否决理由 不能写"不合适"/"不推荐"，必须是具体技术/成本/风险理由
非功能性需求假设 方案章必须显式标注默认假设（如"默认单机低量级"）
待定问题 不能写"无"但方案中存在未决依赖
共享术语 跨子需求使用的术语必须在父文档第 4 章有速查条目
一览图 必须同时包含用户视角步骤和子需求编号

2.3 反模式扫描

扫描文档是否命中 design-craft 定义的反模式清单：

结构层面：

  • ❌ 需求含流程变化但用单文档承载
  • ❌ 拆分后不提供一览图
  • ❌ 术语表跨子需求混排
  • ❌ 子文档引用父文档不存在的接口定义

内容层面：

  • ❌ 含"众所周知"/"显而易见"/"业界通用做法"等空话
  • ❌ 章节内容堆砌（"为了让本章看起来饱满"）
  • ❌ "不在范围内"写成空话
  • ❌ 子文档间重复写共享术语和背景
  • ❌ 子文档接口签名与父文档不一致
  • ❌ 决策点无被否决方案
  • ❌ 非功能性需求未显式标注默认假设
  • ❌ 待定问题写"无"但方案中存在未决依赖
  • ❌ 复制需求 PRD 大段原文
  • ❌ 用"已支持/已覆盖/已具备"声称能力但不给可验证依据（路径/签名/步骤）

阶段 3：技术正确性挑战

从独立视角挑战方案的技术合理性。这是本 skill 最有价值也最需谨慎的阶段。

挑战辅助——强关联关系查询：挑战涉及调用链、依赖关系、模块间影响时，可调用 use_skill("ki-memory-lookup") 检索相关模块的强关联关系（跨模块契约/业务耦合），核实设计方案的模块间牵动是否完整（查询失败或无可用记录，忽略继续）。

挑战核对——决策记忆查询：挑战方案时，可调用 use_skill("ki-memory-lookup") 的决策记忆策略，核对当前方案是否与模块的历史决策冲突——若方案推翻了某条历史决策，将该点标记为需说明项，要求给出推翻理由（查询失败或无可用记录，忽略继续）。

3.1 挑战维度

维度 典型问题
方案可行性 提出的方案在给定约束下是否真的可行？
边界条件 是否覆盖了空输入、极大值、并发冲突等边界？
隐性假设 方案是否依赖未声明的假设（如"网络始终可用"）？
决策充分性 被选择的方案是否真的优于被否决方案？否决理由是否成立？
遗漏场景 是否有未覆盖的用户操作路径或异常路径？
性能瓶颈 方案在高负载下是否会出现瓶颈？
安全风险 是否存在未考虑的攻击面或权限越界？
用户体验 涉及人机交互时，正向和负向体验是否都被考虑？（见 3.4）

3.2 置信度标注

每条技术挑战必须标注置信度：

置信度 含义 严重度映射
🔴 高 有明确依据（如违反已知约束、存在逻辑矛盾） 按实际严重度
🟡 中 有合理怀疑但缺乏完整依据 降一级但保留原标记：标为"疑似阻断/疑似警告"，不计入🔴阻断计数，但需人工确认
🟢 低 纯粹的探索性提问 固定为建议

3.3 关键约束

  • 不凭空质疑：每条挑战必须引用文档原文或已知技术事实
  • 不替代设计：只指出问题和可能方向，不给完整替代方案
  • 不超出范围：不评审文档范围外的问题（如"为什么不选另一个产品"）

3.4 用户体验评审（有人参与时触发）

当设计文档的交互对象中包含用户角色（非纯模块间调用）时，自动触发此维度评审。

3.4.1 正向体验检查

聚焦理想路径下用户的操作感受：

检查项 典型问题 严重度
操作步骤 完成核心任务需要几步操作？步骤是否可以进一步合并？ 🟡
反馈明确性 每一步操作完成后，用户是否得到清晰的反馈（成功/进行中/完成）？ 🟡
等待感知 耗时操作是否有进度提示或骨架屏？用户是否会觉得"卡住了"？ 🟡
学习成本 新用户是否需要额外学习才能理解操作方式？是否有引导？ 🟢
信息可发现性 关键信息/操作入口是否容易被用户找到？ 🟢

3.4.2 负向体验检查

聚焦异常/失败路径下用户的感知和恢复能力：

检查项 典型问题 严重度
错误可理解性 错误提示是"500 Internal Error"还是"服务器繁忙，请稍后重试"？ 🔴
异常反馈 API 调用超时、网络断开时用户看到什么？是白屏还是明确提示？ 🔴
权限不足 无权限操作时是直接报错还是清晰告知"你没有权限执行此操作"？ 🟡
输入校验 用户输入不合法时，是提交后才报错还是实时校验提示？ 🟡
可恢复性 出错后用户能否自行恢复（重试/返回），还是会陷入死胡同？ 🔴
数据安全感知 删除/修改等敏感操作是否有二次确认？操作失误是否有撤销机会？ 🟡

3.4.3 输出格式

用户体验评审结果与其他维度统一纳入阶段 5 的评审报告，维度列标注为"体验"：

| # | 维度 | 位置 | 问题描述 | 修改建议 | 来源 |
|---|------|------|---------|---------|------|
| 1 | 体验 | §异常处理 | 网络超时未定义用户提示，用户会看到白屏 | 补充超时时前端提示"网络超时，请检查连接后重试" | 阶段3 |
| 2 | 体验 | §方案 | 核心操作为 5 步点击，可合并为 3 步 | 将步骤 B/C 合并为一个确认页 | 阶段3 |

阶段 4：一致性校验

多文档检查跨文档一致性（4.1~4.4，仅多文档执行）；单文档检查内部一致性（4.5，始终执行）。

4.1 术语一致性

检查项 规则
同名异义 两个子文档定义相同术语但含义不同 → 🔴阻断（除非父文档已标注）
异名同义 不同术语描述相同概念 → 🟡警告
孤儿术语 子文档使用但未定义且未引用父文档的术语 → 🟡警告

4.2 接口一致性

检查项 规则
签名不匹配 子文档引用的接口签名与父文档定义不一致 → 🔴阻断
孤儿接口 父文档声明但无子文档引用的接口 → 🟡警告
幽灵接口 子文档引用但父文档不存在的接口 → 🔴阻断

4.3 依赖一致性

检查项 规则
DAG 断裂 子文档声明依赖另一个子需求但无对应文档 → 🔴阻断
循环依赖 子文档间存在循环依赖 → 🔴阻断
一览图不匹配 一览图中的节点/连线与实际子文档不一致 → 🟡警告

4.4 范围一致性

检查项 规则
越界 子文档"不在范围内"超出父文档边界 → 🟡警告
范围缺口 父文档目标中提到但无子文档覆盖 → 🟡警告

4.5 单文件内部一致性（始终执行）

单文件设计跳过 4.1~4.4，但仍需自检内部一致性：

检查项 规则
术语自洽 同一术语全文含义一致；同名异义 → 🟡警告
接口自洽 同一接口全文签名一致；前后矛盾 → 🔴阻断
一览图自洽 一览图节点/连线与正文描述一致；不一致 → 🟡警告
范围自洽 "不在范围内"与正文目标不冲突；越界 → 🟡警告

阶段 5：评审意见汇总与输出

将阶段 1~4 的所有发现汇总，按严重度排序输出。

输出格式

🔍 设计文档评审报告
━━━━━━━━━━━━━━━━

文档：<文件名/目录>
格式：design-craft / 自由格式
评审时间：YYYY-MM-DD

━━━ 🔴 阻断（必须修复） ━━━

| # | 维度 | 位置 | 问题描述 | 修改建议 | 来源 |
|---|------|------|---------|---------|------|
| 1 | 完整性 | S-01 §4 | 接口设计缺少返回值类型 | 补充 `Result<T>` 返回类型及异常列表 | 阶段1 |
| 2 | 一致性 | S-02 §4a.1 | `getUser(id)` 签名与父文档 §4.2 不一致 | 对齐为 `getUser(id: string): User` | 阶段4 |

━━━ ⚠️ 疑似阻断（需人工确认） ━━━

> 中置信度技术挑战降级项（见 3.2）。不计入 🔴 阻断计数，但存在 ≥1 项时结论为"⚠️ 有条件通过（需人工确认）"。无则填"无"。

| # | 维度 | 位置 | 问题描述 | 修改建议 | 来源 |
|---|------|------|---------|---------|------|
| - | - | - | 无 | - | - |

━━━ 🟡 警告（强烈建议修复） ━━━

| # | 维度 | 位置 | 问题描述 | 修改建议 | 来源 |
|---|------|------|---------|---------|------|
| 3 | 质量 | S-01 §2 | 现状描述缺少具体文件路径 | 补充涉及的源文件路径和行号 | 阶段2 |
| 4 | 正确性 | S-03 §3 | 假设网络始终可用，未考虑超时重试 | 增加超时与重试策略说明 | 阶段3 |

━━━ 🟢 建议（可选优化） ━━━

| # | 维度 | 位置 | 问题描述 | 修改建议 | 来源 |
|---|------|------|---------|---------|------|
| 5 | 质量 | 父文档 §1 | "不在范围内"仅写"不涉及其他" | 列出具体排除的功能或模块 | 阶段2 |

━━━ 📊 评审统计 ━━━

| 维度 | 🔴 | 🟡 | 🟢 | 合计 |
|------|----|----|----|----|
| 完整性 | 1 | 0 | 0 | 1 |
| 质量 | 0 | 1 | 1 | 2 |
| 正确性 | 0 | 1 | 0 | 1 |
| 体验 | 1 | 1 | 0 | 2 |
| 一致性 | 1 | 0 | 0 | 1 |
| 合计 | 3 | 3 | 1 | 7 |

> 注：⚠️ 疑似阻断项单独列入上方"疑似阻断"区，不计入 🔴 列。

评审结论：❌ 不通过 / ⚠️ 有条件通过（含需人工确认） / ✅ 通过

下一步建议：
- 修复所有 🔴 阻断项后可重新提交评审
- 修复后建议使用增量再审模式（提供本文档作为前次评审结果）

评审结论规则

条件 结论
存在 ≥1 个 🔴阻断 ❌ 不通过
存在 ≥1 个"疑似阻断"（中置信度降级项）且未人工否决 ⚠️ 有条件通过（需人工确认）
无 🔴阻断/疑似阻断，但存在 ≥1 个 🟡警告 ⚠️ 有条件通过
仅存在 🟢建议或无问题 ✅ 通过

阶段 6（可选）：增量再审

当用户提供修订文档 + 前次评审结果时触发。

输入要求

  • 修订后的设计文档
  • 前次评审报告（完整文本或摘要均可）

处理逻辑

  1. 结构变化检测（前置）：对比前后文档的章节标题树，估算结构相似度。若结构重排（章节重编号/合并/拆分）导致相似度低，放弃增量对比，退化为全量评审并在输出中提示"文档结构变更较大，已切换全量评审"
  2. 定位变更：对比前次评审报告中的问题项，识别文档中对应位置的修订（基于章节标题 + 内容指纹，而非行号）
  3. 验证修复：逐项检查前次问题是否已修复
  4. 扫描新增：对修订部分重新执行阶段 1~4（仅扫描修订涉及的章节和文档）
  5. 继承通过项：前次评审中未涉及修订的通过项，直接继承，不再重复检查

输出格式

🔍 增量评审报告
━━━━━━━━━━━━━━━━

基于前次评审：<前次评审时间>
修订范围：<修订涉及的文档和章节>

━━━ 前次问题验证 ━━━

| # | 前次问题 | 严重度 | 状态 | 说明 |
|---|---------|--------|------|------|
| 1 | S-01 §4 接口缺少返回值 | 🔴 | ✅ 已修复 | 已补充 Result<T> |
| 2 | S-02 §4a.1 签名不一致 | 🔴 | ❌ 未修复 | 签名仍为旧版本 |
| 3 | S-01 §2 缺少文件路径 | 🟡 | ✅ 已修复 | 已补充路径 |

━━━ 新增发现 ━━━

（格式同阶段 5，仅列出新增问题）

━━━ 继承通过项 ━━━

前次评审中 N 项未涉及修订的通过项维持原判，不再重复列出。

━━━ 📊 增量评审统计 ━━━

| 类别 | 数量 |
|------|------|
| 前次问题已修复 | 2 |
| 前次问题未修复 | 1 |
| 新增问题 | 0 |
| 继承通过项 | N |

评审结论：❌ 不通过 / ⚠️ 有条件通过 / ✅ 通过

反模式（不要做）

评审态度层面

  • ❌ 只夸不批：评审的目标是发现问题，不是背书
  • ❌ 为挑而挑：没有依据的质疑比没有质疑更有害
  • ❌ 越俎代庖：给完整替代方案而非修改建议，剥夺设计者决策权
  • ❌ 超出范围：评审文档范围外的架构决策或产品方向

评审流程层面

  • ❌ 逐阶段打断：阶段 1~4 应完整执行后统一输出，不应每步都等用户确认
  • ❌ 忽略置信度：技术挑战不标注置信度，导致低质量质疑浪费评审者注意力
  • ❌ 重复报告：增量再审时重复列出已修复的问题
  • ❌ 遗漏继承：增量再审时对未变更部分重新全量评审
  • ❌ 忽略专家资产：专家团存在相关模块资产时，未将专家的架构设计、已知坑作为评审基准进行交叉验证

评审内容层面

  • ❌ 模糊建议："建议优化"不是修改建议，必须具体到改什么、改成什么
  • ❌ 空泛质疑："这个方案可能有问题"不是有效挑战，必须说明什么条件下有问题
  • ❌ 忽略上下文：不考虑文档声明的约束和假设就提出挑战

附加资源

需求管理集成

当项目配置了 .requirements/config 时，design-review 在输出评审报告（阶段 5/6）后自动执行以下集成操作：

自动触发条件

项目中存在 .requirements/config 且 storage_path 指向有效目录。

集成步骤

  1. 获取需求上下文：评审设计文档时，如果关联了 REQ-ID，先读取需求信息作为评审背景：
req list --id {REQ-NNN} --deps
  1. 写入评审报告到需求目录后，调用 req update 注册文档关联并追加变更记录：
req update {REQ-NNN} \
  --docs add design/design-review.md,review --changelog "完成设计评审"
  1. 错误处理：
    • 需求 ID 不存在 → 提示用户先创建需求，跳过集成
    • 文件锁超时 → 自动重试 1 次，仍失败则告知用户

存储路径映射

产出物 存储路径 docs 类型
设计评审报告 design/design-review.md review

Похожие навыки: other

limits-colimits

Context management for Claude Code. Hooks maintain state via ledgers and handoffs. MCP execution without context polluti...

Автор: parcadei
3,392

ddttom-allaboutv2-claude-skills-block-collection-and-party

The Block Collection and Block Party are repositories for existing AEM blocks, build tools, code snippets, integration p...

Автор: mattnigh
20

nodnarbnitram-claude-code-extensions-claude-skills-esphome-confi

This skill should be used when the user asks to "create an esphome config", "set up an esp32 device", "configure esphome...

Автор: mattnigh
20