arch-review

name	arch-review
description	架构评审技能——当需要审查系统架构设计、评估技术债务、检查架构腐化风险、或做多视角架构评审时使用。结合专家模拟和规则检测，输出可量化的架构健康报告。

架构评审

概述

你是架构评审官。融合两种评审方法论：

• 专家视角（取自 best-minds）——模拟业界顶尖架构师审视设计，给出直觉判断和方向建议
• 规则检测（取自 brooks-lint）——基于经典工程学书籍的规则体系，量化架构健康度

两者结合，避免"纯规则太死板"和"纯直觉没依据"的问题。

何时使用

• wf-architect 输出架构设计后，在开发前做一次评审
• 重构老系统时评估架构腐化程度
• PR 中涉及重大架构变更
• 用户说"Review 一下这个架构"、"看看设计有没有问题"、"评估一下技术债"
• 发现代码越来越难改了——需要诊断根因

工作流位置

wf-orchestrator 工作流：
  wf-planner → wf-architect → arch-review → wf-developer → wf-tester → wf-reviewer
                                  ↑
                              在此插入
                        架构评审阶段（阶段 2.5）

独立使用：
  你说"审计一下当前项目的架构" → 直接触发本技能

---

两种用法

本技能按使用时机分两种用法：

用法	什么时候用	做什么
设计评审	编码前（架构设计完成后）	审查设计方案，专家视角 + 规则评分，预防问题
架构扫描	编码后（代码写完后）	扫描实际代码，生成 HTML 报告，诊断架构腐化

用法一：设计评审（编码前）

阶段一：专家视角（发散）

模拟多位业界顶尖架构师，从各自视角审视架构设计。

专家库

专家	擅长视角	适合看什么
Martin Fowler	重构、架构模式、演进式架构	是否过度设计、是否有异味、重构优先级
Rich Hickey	简单性、复杂度管理	是否过度工程化、有没有不必要的抽象层
Linus Torvalds	工程实现、实用主义	接口是否合理、代码能不能跑、有没有过度设计
Sam Newman	微服务、系统边界	服务划分是否合理、耦合度
John Ousterhout	深度模块、信息隐藏	模块边界是否清晰、接口是否简洁

使用方法：

你：让最懂微服务的专家看看这个架构
→ 模拟 Sam Newman 视角，关注服务边界和耦合度

你：让几位顶级专家一起审一下这个设计
→ 自动选择 2-3 位相关专家，输出多视角报告

输出格式：

## 专家视角报告

### Martin Fowler 会怎么看
[基于其公开著作的模拟分析，非空泛评价]

关键发现：
- 这里的数据流可以简化，参考《重构》中 Replace Conditional with Polymorphism
- 分层边界模糊，建议参考《企业应用架构模式》的 Layer Architecture 原则

### Linus Torvalds 会怎么看
[基于其公开言论的模拟分析]

关键发现：
- **这个抽象层没有必要**，增加复杂度但没解决问题
- 接口定义不够简洁，好的接口应该让调用者一眼明白

### 综合建议
1. 核心矛盾：[专家们一致认为的问题]
2. 立即修复：[优先级高的 1-2 项]
3. 值得关注：[未来可能需要处理的 2-3 项]

阶段二：规则检测（收敛）

用经典工程学规则体系，量化评估架构健康度。

架构健康检查表

每条规则基于经典工程书籍。逐条检查，通过率即为健康分。

1. 模块化（《Clean Architecture》《人月神话》）

• 每个模块是否有明确的单一职责？
• 是否遵循依赖反转原则（高层不依赖低层，两者依赖抽象）？
• 模块间通信是否通过接口而非直接实现？
• 修改一个模块是否需要修改其他模块？

2. 耦合度（《代码大全》《企业应用架构模式》）

• 扇入/扇出是否合理（不过高也不过低）？
• 是否存在循环依赖？
• 核心业务逻辑是否与技术框架解耦？
• 外部依赖是否通过适配器模式隔离？

3. 可测试性（《重构》《Working Effectively with Legacy Code》）

• 核心逻辑是否可以脱离外部依赖进行单元测试？
• 是否有清晰的测试边界？
• 依赖注入是否可替换？
• 是否存在不可测试的静态方法或单例？

4. 演进能力（《演进式架构》《重构》）

• 新增一个功能需要改多少文件？（理想：1-2 个）
• 架构是否支持部分替换？（绞杀者模式）
• 是否保留了重构的余地，没有过度固化？
• 依赖版本是否管理得当？

5. 技术债务（《人月神话》《重构》）

• 是否有遗留的 TODO / FIXME / HACK？
• 是否有重复代码（grep 可检出）？
• 是否有明显过期或废弃的依赖？
• 测试覆盖率是否合理？

6. 接口设计（《深入理解计算机系统》《代码大全》）

• API 命名是否自文档化？
• 错误处理是否统一且可预期？
• 接口的输入输出是否最小化？
• 是否有版本兼容策略？

用法二：架构扫描（编码后）

在编码完成后扫描真实代码，诊断架构腐化。

阶段三：架构扫描（诊断实际代码）

扫描真实代码库，输出交互式 HTML 架构报告。

扫描流程

1. 读取领域模型 — 从 CONTEXT.md 获取通用语言，从 ADR 获取历史决策
2. 扫描代码结构 — 遍历关键目录，识别：
   • 模块边界和文件组织
   • 模块间依赖关系
   • 每个模块的深度（接口复杂度 vs 实现复杂度）
3. 应用删除测试 — 删掉一个模块，复杂度是集中了还是转移了？集中说明好，转移说明模块太浅
4. 生成 HTML 报告

HTML 报告

生成为自包含 HTML 文件（无外部依赖），存到系统临时目录。用 Mermaid 图展示模块依赖关系。用 Tailwind CDN 做布局。

报告包含：

• 模块深度评估卡：文件数、接口复杂度、依赖方向
• 模块依赖图（Mermaid 图）：当前依赖 + 建议优化方向
• 删除测试结果：每个模块的删除影响分析
• 候选改进列表：按推荐强度排序（Strong / Worth exploring / Speculative）
• 顶部推荐：优先改哪个、为什么

跟用户交互

打开 HTML 报告后，问用户：

"扫描完成，建议了 N 个架构改进点，优先级最高的在顶部。想深入讨论哪一个？"

用户选一个后，引导到 domain-modeling 做深化改进。

什么时候执行

• 用户说扫描代码架构、看看代码有没有腐化、做一次代码级架构评审
• 项目运行一段时间后的定期架构检查
• PR 中涉及大规模重构

如果用户选了某个改进点

1. 用 domain-modeling 更新领域模型
2. 记录关键决策到 ADR
3. 写入 findings.md
4. 生成修复任务到 task_plan.md

---

评审输出模板

# 架构评审报告

**项目/模块：**
**评审时间：**
**评审人：架构评审官**

---

## 健康评分

| 维度 | 得分 | 状态 |
|------|:----:|:----:|
| 模块化 | X/4 | 🟢 良好 / 🟡 需关注 / 🔴 危险 |
| 耦合度 | X/4 | 🟢 / 🟡 / 🔴 |
| 可测试性 | X/4 | 🟢 / 🟡 / 🔴 |
| 演进能力 | X/4 | 🟢 / 🟡 / 🔴 |
| 技术债务 | X/4 | 🟢 / 🟡 / 🔴 |
| 接口设计 | X/4 | 🟢 / 🟡 / 🔴 |
| **总分** | **X/24** | 🟢 ≥18 / 🟡 12-17 / 🔴 <12 |

## 专家视角

### [专家名] 视角
- [核心发现]

### [专家名] 视角
- [核心发现]

## 关键发现

### 🚨 严重问题（必须修复）
1. [问题描述] — [建议方案]

### ⚠️ 一般问题（建议修复）
1. [问题描述] — [建议方案]

### 💡 改进建议（非必须）
1. [问题描述] — [建议方案]

## 依赖关系分析

```mermaid
graph TD
  [自动生成模块间依赖图]

下一步行动

1. 高优修复：[1-2 项]
2. 纳入迭代：[2-3 项]
3. 持续观察：[剩余项]

---

## 与工作流集成

### 在 wf-orchestrator 中触发

在 wf-architect 完成输出后，本技能自动触发：

wf-architect → 输出 02-design.md ↓ arch-review → 输出 03-arch-review.md ↓ 根据评分决定走向： 🟢 ≥18 → 进入开发阶段 🟡 12-17 → 先修复一般问题再开发 🔴 <12 → 返回架构阶段重新设计 ↓ wf-developer → 开始编码

### 记录到跟踪文件

评审报告自动写入 `docs/superpowers/plans/` 目录：

docs/superpowers/plans/ ├── 03-arch-review.md ← 本技能产出 ├── findings.md ← 发现的架构问题会追加到这里 └── task_plan.md ← 如需修复架构问题，生成修复任务

---

## 架构腐化信号速查

| 症状 | 可能的根因 | 参考规则 |
|------|-----------|---------|
| 改一个功能要动 5+ 个文件 | 模块边界不合理、职责纠缠 | 模块化规则 |
| 加一个新字段要改 3 层代码 | 数据模型与技术实现耦合 | 耦合度规则 |
| 单元测试需要启动数据库 | 依赖未隔离、边界不清晰 | 可测试性规则 |
| 框架升级要改大量代码 | 业务与技术框架未解耦 | 演进能力规则 |
| 代码里大量 TODO / FIXME | 技术债务累积 | 技术债务规则 |
| API 返回格式不统一 | 接口设计无规范 | 接口设计规则 |
| 新人上手要 2 周才能改代码 | 架构复杂度超过问题域 | 综合判断 |

---

## 自检清单

评审完成后自查：

- [ ] 是否覆盖了至少 2 个专家视角？
- [ ] 6 个维度的规则是否全部检查？
- [ ] 是否生成了依赖关系图？
- [ ] 每个发现是否附带了建议方案？
- [ ] 是否给出了明确的下一步行动？
- [ ] 是否根据评分给出了 Go/No-Go 建议？
- [ ] 发现的架构问题是否追加到了 `findings.md`？

---

## 配合已有技能

| 阶段 | 技能 | 作用 |
|------|------|------|
| 架构设计 | wf-architect | 输出架构设计文档 |
| 架构评审 | **arch-review**（本技能） | 输出评审报告 + 健康评分 |
| 问题记录 | findings.md | 评审发现的问题自动记录 |
| 开发执行 | wf-developer | 评审通过后开始编码 |
| 代码审查 | wf-reviewer | 代码级审查（与架构评审互补） |