architecture-review

架构评审

识别架构摩擦，并提出至多三个有证据支撑的改进机会。唯一交付物是一份供后续优化 AI 使用的中文 Markdown 报告。

不得修改产品代码、创建任务票、启动其他 skill、开始设计访谈，或实施任何建议。

确定审视范围

在扫描前先决定审视方向：

• 如果用户指定了模块、子系统、痛点或功能 spec，就围绕该方向审视。
• 否则，检查一段有代表性的近期 Git 历史，以反复变更的路径识别热点。
• 如果 Git 历史不可用，或无法揭示热点，只按需要扩大扫描范围，并说明证据较弱。

阅读相关代码、测试和已有项目文档。不要求项目采用特定文档结构。仅在当前执行环境支持时使用并行探索或子 agent。

寻找什么

寻找架构摩擦，而不是泛泛的清理项：

• 理解一个概念需要在许多细小模块之间来回跳转。
• 一个接口暴露的复杂度几乎与其隐藏的实现复杂度相当。
• 关键逻辑越过模块边界泄漏到调用方。
• 测试必须穿透接口，或组装过多内部细节。
• 一个抽象只为假设中的未来变化而存在。

对每个候选项应用删除测试：如果移除该模块只会让复杂性扩散到调用方，它就不是改进机会。优先关注正在频繁变化的区域，或与用户下一个功能直接相关的区域。

不要将格式整理、重命名、依赖升级或推测性的抽象报告为架构改进机会。

撰写报告

如有需要，在仓库根目录创建 docs/architecture-reviews/。写入或更新一份稳定的报告：

• 用户指定的范围使用 docs/architecture-reviews/<scope-slug>.md。
• 基于近期变更推断的审视使用 docs/architecture-reviews/hotspots.md。

更新相同范围已有的报告。不得覆盖不同范围的报告。

使用中文撰写报告。只有当模块关系、调用流程或边界通过图示会显著更清晰时，才使用 Mermaid。不要为了装饰而添加图。

使用以下结构：

# 架构评审：<范围>

状态：当前

## 审视范围与证据

- 审视对象：<模块、痛点、spec 或热点>
- 代码与测试：<检查过的关键路径>
- 变更证据：<相关提交、频繁变化的路径，或“无可靠历史证据”>
- 证据限制：<如有>

## 摘要

<当前最值得处理的架构摩擦，或“当前不建议进行架构优化”。>

## 候选优化机会

### 1. <候选名称>

**建议强度：** Strong | Worth exploring | Speculative

**涉及范围：** <文件、模块或调用路径>

**观察到的摩擦：** <当前为什么难理解、难改或难测>

**证据：** <代码、测试、变更历史或用户说明中的具体依据>

**建议方向：** <要集中、隐藏或简化的复杂性，不规定最终接口或实现细节>

**预期收益：** <locality、测试面、调用复杂度或变更成本的改善>

**风险与非目标：** <不应借此顺带改变的行为，及主要风险>

## 头号推荐的执行简报

**优化目标：** <下一位优化 AI 应达成的结果>

**起始范围：** <应先阅读的文件或模块>

**必须保持不变：** <对外行为、接口、数据或测试语义>

**验收信号：** <可观察的成功条件与需要保持通过的测试>

**未决点：** <下一位 AI 必须先调查或确认的选择>

候选项不得超过三个。只有当摩擦和收益都获得证据支持时，才使用 Strong。当方向合理但取决于近期工作时，使用 Worth exploring。谨慎使用 Speculative，且不得为它提供执行简报。

如果没有值得做的改进，请在摘要中明确说明，省略执行简报，也不要为了凑数而编造候选项。

执行简报只属于最强的推荐候选项。它必须能帮助后续优化 AI 开始工作，同时将最终接口设计和实现选择留给该 AI 基于仓库调查来决定。

结束

写入报告后，说明报告路径并停止。由用户决定是否将执行简报交给另一个 AI。