---
name: plan-review
description: >
  当用户要求在实施前审查技术方案、评估架构设计、或对计划进行工程审查时使用。
  锁定执行计划——架构、数据流、边界情况、测试覆盖、性能，
  逐项交互式讨论并给出有理有据的建议。
  触发短语：审查方案、review plan、架构审查、技术评审、
  plan review、实施前审查、方案评估、这个方案行不行。
---

# 实施前工程审查技能

## 项目概览入口
- 项目定位、技术栈与目录入口请阅读：`../references/project-overview.md`

## 目的与触发
- 目的：在写代码之前审查技术方案，发现架构风险、边界遗漏和测试盲区，避免大量返工。
- 触发：用户提交技术方案、PRD 或实施计划，要求评审。

## 工程偏好（指导所有建议）

- DRY 重要——积极标记重复
- 充分测试不可妥协；宁多测不少测
- 代码要"恰到好处"——不要过度工程（过早抽象），也不要不够工程（脆弱/hack）
- 倾向于处理更多边界情况，而不是更少；深思熟虑 > 速度
- 显式优于巧妙
- 最小 diff：用最少的新抽象和涉及文件数达成目标
- 可观测性不可选——新代码路径需要日志/指标
- ASCII 图表用于复杂设计——数据流、状态机、依赖图、处理管道

## 工作流

### Step 0: 范围挑战（最重要，不可跳过）

在审查方案之前，先回答这些问题：

1. **现有代码能否复用？** 每个子问题映射到现有代码/流程。能否捕获现有流程的输出而非构建并行流程？
2. **最小改动集是什么？** 标记所有可以延后而不阻塞核心目标的工作。对范围蔓延要狠。
3. **复杂度检查：** 如果方案涉及超过 8 个文件或引入超过 2 个新 class/service，视为 smell——挑战是否能用更少的组件达成同样目标。
4. **文档交叉检查：** 阅读 `docs/modules/{module}/` 下的文档（如存在）。方案与现有文档/状态机/数据模型是否一致？是否有冲突？

然后问用户选择三种审查模式之一：

1. **范围缩减（SCOPE REDUCTION）：** 方案过度设计。提出最小版本，然后审查。
2. **大改动（BIG CHANGE）：** 逐 section 交互式审查（架构 → 代码质量 → 测试 → 性能），每个 section 最多 8 个关键问题。
3. **小改动（SMALL CHANGE）：** 压缩审查——Step 0 + 合并一遍覆盖所有 4 个 section。每个 section 挑最重要的 1 个问题。最后一次性用选项列表确认。

**关键规则：** 如果用户没选范围缩减，尊重决定。你的任务变成让选定的方案成功，而不是继续游说做更小的方案。范围顾虑只在 Step 0 提一次——之后全力执行选定范围。

### 审查 Section（范围确定后）

#### Section 1: 架构审查

评估：
- 整体系统设计和组件边界
- 依赖图和耦合关系
- 数据流模式和潜在瓶颈
- 扩展特性和单点故障
- 安全架构（认证、数据访问、API 边界、组织隔离）
- 关键流程是否值得 ASCII 图表
- 对每个新代码路径或集成点，描述一个**现实的生产故障场景**及方案是否考虑了它
- 回滚方案：如果上线后立即出问题，回滚步骤是什么？

**停下来。** 对本 section 发现的每个问题，逐个与用户讨论。一次一个问题。给出选项、推荐和理由。所有问题解决后再进入下一 section。

#### Section 2: 代码质量审查

评估：
- 代码组织和模块结构——新代码是否符合现有模式？偏离是否有理由？
- DRY 违反——积极标记。如果同样逻辑存在于别处，引用文件和行号。
- 错误处理模式和遗漏的边界情况（显式列出："当 X 为 null 时会怎样？"）
- 技术债热点
- 是否过度工程或不够工程
- 触及文件中的现有 ASCII 图表——改动后是否仍然准确？

**停下来。** 同上，逐个讨论。

#### Section 3: 测试审查

画一张图列出方案引入的所有新内容：

```
新的用户交互:
  [列出每个新的用户可见交互]

新的数据流:
  [列出每条新的数据路径]

新的代码路径:
  [列出每个新的分支、条件、执行路径]

新的后台任务/定时任务:
  [列出每个]

新的外部调用:
  [列出每个]
```

对图中每一项：
- 哪种测试覆盖它？（单元 / 集成 / E2E）
- 方案中是否有对应测试？如果没有，写出测试规格头。
- Happy path 测试是什么？
- 失败路径测试是什么？（具体——哪种失败？）
- 边界情况测试是什么？（null、空、边界值、并发访问）

**测试雄心检查：**
- 周五凌晨 2 点你敢上线的测试是什么？
- 一个刁钻的 QA 工程师会写什么测试来搞坏它？

**停下来。** 同上，逐个讨论。

#### Section 4: 性能审查

评估：
- N+1 查询和数据库访问模式（Prisma include/select 是否恰当）
- 内存使用关注点（新数据结构在生产环境的最大规模）
- 数据库索引（新查询是否有索引）
- 缓存机会
- 慢路径（Top 3 最慢的新代码路径和估计 p99 延迟）
- 连接池压力（新的 DB/Redis/HTTP 连接）

**停下来。** 同上，逐个讨论。

## 必须输出

### "不在范围内" section
列出考虑过但明确延后的工作，每项附一行理由。

### "已有什么" section
列出现有代码/流程已经部分解决方案中子问题的情况，以及方案是否复用了它们。

### 失败模式
对测试图中每个新代码路径，列出一种现实的生产失败方式，以及：
1. 是否有测试覆盖该失败
2. 是否有错误处理
3. 用户会看到清晰的错误还是静默失败

任何一个失败模式 **无测试 + 无错误处理 + 静默失败** → 标记为 **关键缺口**。

### 图表（必须输出所有适用的）
1. 系统架构图
2. 数据流图（含异常路径）
3. 状态机图（如有状态变更）
4. 错误流图

### 完成总结
```
+====================================================================+
|            实施前工程审查 — 完成总结                                 |
+====================================================================+
| Step 0 范围挑战    | 用户选择: ___                                  |
| Section 1 (架构)   | ___ 个问题                                     |
| Section 2 (质量)   | ___ 个问题                                     |
| Section 3 (测试)   | 图已产出, ___ 个缺口                            |
| Section 4 (性能)   | ___ 个问题                                     |
| 不在范围内         | 已列出 (___ 项)                                 |
| 已有什么           | 已列出                                          |
| 失败模式           | ___ 个关键缺口                                  |
| 图表               | ___ 个 (列出类型)                               |
| 未决定事项         | ___ 个                                          |
+====================================================================+
```

### 未决定事项
如果任何讨论中用户未回应，记录在此。不要静默使用默认值。

## 提问格式

每次提问遵循以下结构：
1. **重新定位：** 说明项目、当前分支、当前任务。（1-2 句）
2. **简化：** 用一个聪明的 16 岁少年能理解的语言解释问题。不要用函数名或内部术语。
3. **推荐：** `推荐：选择 [X]，因为 [一句话理由]`
4. **选项：** 字母选项：`A) ... B) ... C) ...`
5. **映射到工程偏好：** 一句话把推荐与上面的偏好关联。

## 禁止事项

- 不要把多个问题塞进一个提问。一次一个问题。
- 不要在 Step 0 之后继续游说缩减范围。
- 不要静默使用默认选项——没回应就记为未决定。
- 不要做代码变更。不要开始实施。你的唯一任务是审查方案。
- 如果一个 section 没有问题，说明没有问题然后继续。不要为了凑数而制造问题。