Design Review

---
name: design-review
description: 对设计文档进行结构化评审，产出按严重度分级的问题清单和修改建议。优先识别 design-craft 格式以获得更精准的评审，同时兼容任意格式的设计文档。适用于"评审设计"、"review 设计文档"、"帮我看看这个设计"、"设计评审"、"design review"、"review design doc"、"审查设计"等场景。仅在用户已有一份可读的设计文档时使用，不替代设计文档的生成。
---

# 设计文档评审器

## 概述

对设计文档进行结构化评审，产出按严重度（阻断/疑似阻断/警告/建议）分级的问题清单和修改建议。支持 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 的评审报告，维度列标注为"体验"：

```text
| # | 维度 | 位置 | 问题描述 | 修改建议 | 来源 |
|---|------|------|---------|---------|------|
| 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 的所有发现汇总，按严重度排序输出。

### 输出格式

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

文档：<文件名/目录>
格式：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（可选）：增量再审

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

### 输入要求

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

### 处理逻辑

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

### 输出格式

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

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

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

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

━━━ 新增发现 ━━━

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

━━━ 继承通过项 ━━━

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

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

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

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

---

## 反模式（不要做）

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

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

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

## 附加资源

- 评审规则示例 / 反模式示例：[reference.md](reference.md)

## 需求管理集成

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

### 自动触发条件

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

### 集成步骤

1. **获取需求上下文**：评审设计文档时，如果关联了 REQ-ID，先读取需求信息作为评审背景：

```bash
req list --id {REQ-NNN} --deps
```

2. **写入评审报告**到需求目录后，调用 `req update` 注册文档关联并追加变更记录：

```bash
req update {REQ-NNN} \
  --docs add design/design-review.md,review --changelog "完成设计评审"
```

3. **错误处理**：
   - 需求 ID 不存在 → 提示用户先创建需求，跳过集成
   - 文件锁超时 → 自动重试 1 次，仍失败则告知用户

### 存储路径映射

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