Architecture Review

---
name: architecture-review
description: 根据实际代码解释模块关系与数据流，对照设计分析架构问题，默认产出架构评审文档并给出有证据的优化优先级。用于 v1 后复盘、全局架构评审或明确的重构请求；不强制修改代码。
---

# 架构复盘与改进

读取 [开发流程契约](../shared/workflow-contract.md)、项目指南、架构、PRD、目标发布或提交基线及现有决策。用户只请求描述或分析时不修改业务代码，默认仍产出评审文档；明确要求执行优化时才在指定范围内修改代码。不把发布后复盘当作前期集成和质量检查的替代。

从实际入口、模块边界、依赖声明和核心调用路径还原模块职责、依赖方向与关键数据流，以具体文件/符号为证据。先覆盖核心流程，再针对疑点深入；大仓库不强求一次读完每个文件，说明评审覆盖和未覆盖范围。有助理解时用简短 Mermaid 图表达关系，区分运行时调用、静态依赖及外部服务。

分析使用 [codebase-design](../mattpocock/codebase-design/SKILL.md) 的术语，用删除测试判断模块是否过浅。寻找改进机会时按 [improve-codebase-architecture](../mattpocock/improve-codebase-architecture/SKILL.md) 从近期变更热点找加深候选，候选写进评审文档，HTML 报告可选。

对照设计检查依赖环、跨边界耦合、重复业务规则、错误语义不一致及实际扩展难点。相似代码不自动意味着需要抽象，风格差异也不自动构成架构缺陷。性能问题需要测量或明确标为待验证，不能由目录形状推断。

每项有效建议写明问题证据、实际影响、建议变化、成本/风险及验证方式，区分现在修复、后续任务和暂不处理。对设计偏差判断是文档过时还是实现错误，不机械恢复原设计。没有值得修改的问题时可以直接说明，不为凑建议强行重构。

## 评审文档交付

每次评审默认生成或更新一份 Markdown 评审文档。优先使用用户指定位置或项目既有评审记录（可为现有架构/决策文档中的评审章节）；无约定时写入目标项目的 `docs/architecture-review.md`，不要写入 Skill 安装目录。复用现有文件并标明本次基线，保留仍有价值的历史结论，不无故覆盖或重复新建报告。

文档包含以下内容，详略与评审范围相称：

- 评审日期、目标发布或提交基线、已覆盖与未覆盖范围，以及资料或验证缺口。
- 实际模块职责、依赖方向、关键数据流及具体文件/符号证据；有助理解时附 Mermaid 图。
- 与设计的差异及关键发现，区分已确认事实、推断和待验证项。
- 按现在修复、后续任务、暂不处理组织建议，逐项记录证据、影响、建议变化、成本/风险与验证方式。
- 实际修改、已执行验证及结果、未完成事项；仅评审时明确建议尚未实施。没有有效问题时仍记录评审范围、依据和结论。

报告记录本次评审证据与建议，引用现有架构和决策正文；需要长期保留的已确认架构事实或决策更新原权威位置，不将建议当成已采用设计。要求建立后续任务时调用 [project-plan](../project-plan/SKILL.md)，交接报告位置，外部发布遵循已有授权。

用户明确要求只读、仅在对话回答或不落盘时，仅在对话中交付上述内容，不创建文件。目标项目不明或无法写入时，先交付可审阅的报告正文并说明落盘缺口，不声称文档已保存。正常落盘后核对文件存在、内容完整及引用有效，最终答复提供实际文档链接和关键结论。

## 执行与收尾

获授权执行重构时按 task-implement 的验收与纠错规则，先确认现有行为基线，小步修改并验证受影响功能及项目必要回归。契约变化同步权威文件，不能把行为变更伪装成内部重构。大规模改造拆为后续任务，不在一次复盘中无限扩张。

发生文件修改时最终调用 task-closeout 一次；纯只读评审不触发 Git 操作。报告评审基线、模块关系、关键发现、实际修改及验证，不把建议说成已落地。