architecture-review

架构评审技能

架构评审技能——根据最佳实践评估系统设计，识别反模式，并确保架构决策符合非功能性需求（可扩展性、可维护性、安全性、性能）。 - 评审系统架构设计 - 识别反模式和架构异味 - 根据 SOLID、DRY、YAGNI 原则进行验证 - 评估非功能性需求 - 提出架构改进建议

步骤 1：收集架构上下文

通过以下方式了解当前架构：

1. 阅读项目结构：使用 Glob 映射目录结构
2. 识别关键组件：查找入口点、服务和数据层
3. 审查依赖项：检查 package.json、导入项和模块图
4. 了解数据流：追踪请求在系统中的流转

步骤 2：评估设计原则

检查对基本原则的遵循情况：

SOLID 原则：

• Single Responsibility（单一职责）：每个类/模块是否只有一个变更理由？
• Open/Closed（开闭原则）：能否在不修改代码的情况下扩展行为？
• Liskov Substitution（里氏替换）：子类型能否替代基类型？
• Interface Segregation（接口隔离）：接口是否专注且精简？
• Dependency Inversion（依赖倒置）：高层模块是否依赖抽象？

其他原则：

• DRY：是否存在不必要的逻辑重复？
• YAGNI：是否存在未使用或仅基于假设的功能？
• 关注点分离：职责是否得到了恰当划分？

步骤 3：检查反模式

识别常见的反模式：

• 上帝类/模块：承担过多职责的类
• 意大利面条式代码：纠缠在一起、难以理解的逻辑
• 循环依赖：相互引用的模块
• 特性羡慕：过度使用其他类数据的类
• 散弹式修改：需要改动许多文件的变更
• 泄漏的抽象：向使用者暴露实现细节

步骤 4：评估非功能性需求

根据非功能性需求进行评估：

• 可扩展性：系统能否应对增加的负载？
• 可维护性：修改和扩展是否容易？
• 可测试性：能否单独测试各个组件？
• 安全性：是否存在潜在漏洞？
• 性能：是否存在明显的瓶颈？
• 可观测性：能否有效监控系统？

步骤 5：生成评审报告

创建结构化报告，包含：

1. 摘要：总体评估和主要发现
2. 优势：架构做得好的方面
3. 问题：需要关注的问题（按优先级排序）
4. 建议：具体的改进方案及其理由
5. 权衡：承认合理的设计权衡

</execution_process>

<best_practices>

1. 保持建设性：关注改进，而非批评
2. 排列问题优先级：并非所有问题都同等重要
3. 结合上下文：了解约束和权衡
4. 提出替代方案：不要只指出问题
5. 引用模式：在适当时引用成熟的模式

</best_practices>

**评审请求示例**：

Review the architecture of src/services/ for scalability and maintainability

回复结构示例：

## Architecture Review: src/services/

### Summary

The service layer follows a reasonable structure but has some coupling issues...

### Strengths

- Clear separation between API handlers and business logic
- Good use of dependency injection

### Concerns

1. **High Priority**: UserService has 15 methods (God Class)
2. **Medium Priority**: Circular dependency between OrderService and InventoryService
3. **Low Priority**: Some magic numbers in validation logic

### Recommendations

1. Split UserService into UserAuthService and UserProfileService
2. Introduce EventBus to decouple Order and Inventory
3. Extract validation constants to configuration

</usage_example>

架构铁律

1. 复杂或史诗级实现开始前，务必审查架构 — 实现后才发现的架构问题，修复成本会高出 10–100 倍；应在设计阶段进行审查。
2. 绝不批准存在未记录单点故障的架构 — 必须明确识别每个 SPOF，并记录相应的缓解计划。
3. 务必根据非功能性需求进行评估 — 性能、安全性、可扩展性、可维护性和可观测性都是必需项；不符合 NFR 的功能正确性并不完整。
4. 绝不将架构权衡视为隐含事项 — 必须明确记录每项权衡及其理由；隐藏的权衡会成为未来的意外和无人负责的技术债务。
5. 批准设计前，务必检查循环依赖 — 模块间的循环依赖会使测试、重构和部署顺序变得难以预测，并且越来越难以解决。

反模式

反模式	失败原因	正确做法
不评估 NFR	设计可能通过功能测试，却无法应对大规模运行或攻击	务必评估性能、安全性、可扩展性和可观测性
只审查顺利路径	系统会在错误边界处出故障，而非顺利路径中	审查故障模式、重试行为和熔断器
未记录权衡就批准	隐藏的权衡会成为未来的意外	明确记录所有权衡及其理由
未记录单点故障	系统存在隐性脆弱性，会在负载下暴露	梳理所有 SPOF；要求为每个 SPOF 制定缓解计划
检查 SOLID，却不检查反模式目录	遵循原则并不保证不存在反模式	同时检查原则和具体反模式（上帝类、霰弹式修改等）
实现开始后才进行架构审查	为修复结构性问题而进行大规模返工，代价太高	在设计阶段、编写任何代码之前进行审查

规则

• 始终提供有建设性的反馈和可执行的建议
• 按影响和修复成本对问题排序
• 考虑现有约束和权衡

相关工作流

此技能对应一个适用于复杂多 Agent 场景的工作流：

• 工作流：.claude/workflows/architecture-review-skill-workflow.md
• 何时使用工作流：适用于需要开发者、架构师、安全架构师和代码审查员等多个 Agent 协调配合的全面审计或多阶段分析
• 何时直接使用技能：适用于快速审查或单 Agent 执行

记忆协议（强制）

开始前：

cat .claude/context/memory/learnings.md

完成后：

• 新模式 -> .claude/context/memory/learnings.md
• 发现问题 -> .claude/context/memory/issues.md
• 做出决策 -> .claude/context/memory/decisions.md

假设任务会中断：你的上下文可能会重置。如果没有记录在记忆中，就等于没有发生。