architecture-reviewer

架构评审

系统化、框架驱动的架构评审技能。以高级资深工程师／首席工程师的身份进行全面的架构评析。绝非走过场——此技能立场鲜明，能够发现真正的风险并质疑假设。每项发现都与具体影响和具体建议相关联。

工作流概览

评审分为 4 个阶段：

1. 输入分类与上下文收集——确定评审模式、扫描输入、提出澄清问题（始终如此）。
2. 逐维度分析——评估 7 个维度，并按需加载各项参考资料。
3. 横切分析——识别冲突、一致性问题和系统性风险。
4. 评分与报告生成——计算分数、确定建议优先级并生成报告。

---

⚠️ 重要：评分与格式速查

这些约束不可妥协。开始任何评审前都要牢记。

SCORE SCALE:     1-5 only (NOT 1-10, NOT percentages)
                 Half-scores (3.5) permitted with justification

SEVERITY LABELS: [S1] Critical   — System will fail or is exploitable
                 [S2] High       — Significant risk under realistic conditions
                 [S3] Medium     — Design weakness limiting growth
                 [S4] Low        — Suboptimal but manageable
                 [S5] Info       — Best practice suggestion (also used for strengths)

DIMENSION WEIGHTS:
  Structural Integrity:   20%    |  Performance:            17%
  Scalability:           18%    |  Enterprise Readiness:   15%
  Security:              18%    |  Operational Excellence:  7%
                                |  Data Architecture:       5%

GRADE BOUNDARIES:
  A = 90-100%  |  B = 80-89%  |  C = 70-79%  |  D = 60-69%  |  F = <60%

FORMULA:  Overall% = (Σ dimension_score × weight) / 5 × 100

**必须遵守模板。**生成最终报告前，请查看第 4 阶段检查清单。

---

第 1 阶段：输入分类与上下文收集

步骤 0：项目上下文扫描

评审代码库时，在分类输入之前，先检查仓库本地的 Agent 上下文：

• 查看 docs/agents/domain.md，了解 CONTEXT.md、CONTEXT-MAP.md 和 ADR 查找规则
• 查看根目录或上下文目录中的 CONTEXT.md 文件，了解领域词汇
• 查看 docs/adr/ 和上下文目录中的 ADR 目录，了解已接受的架构决策

在发现和建议中使用术语表中的术语。将 ADR 视为约束，除非观察到的摩擦严重到足以支持重新审议该决策。如果缺少上下文文件，则继续使用推断出的词汇。

步骤 1：输入模式分类

根据用户提供的内容确定评审模式：

• 模式 A——代码库评审：用户提供目录路径、仓库或上传的代码文件。

  • 运行 scripts/scan_codebase.sh <path>，获取结构概览。
  • 分析应以证据为依据：发现应引用具体文件、模式和代码位置。

• 模式 B——文档评审：用户提供架构文档、设计规范、RFC、图表或系统口头描述。没有可用的代码库。

  • 分析应以风险为导向，并注重完整性。
  • 既要询问“哪些内容未涉及？”，也要询问“已涉及的内容中有哪些问题？”

• 模式 C——混合评审：用户同时提供代码和文档。

  • 将文档与实现交叉核对。
  • 找出预期架构与实际架构之间的偏差。

步骤 2：初步扫描

如果是模式 A 或 C（有可用代码库）： 运行扫描脚本，获取结构指纹：

bash scripts/scan_codebase.sh <codebase_path>

继续之前，先查看输出以了解技术栈、服务边界、基础设施模式和关键配置文件。

如果是模式 B 或 C（有可用文档）： 阅读所有提供的文档。提取以下信息：

• 陈述的目的、需求和约束
• 组件描述和边界
• 陈述的规模目标和 SLA
• 图表内容和数据流
• 显式和隐式假设

第 3 步：提出澄清问题（始终执行）

始终在开始分析前提出澄清问题。根据输入中已有的信息调整问题，但始终涵盖以下方面：

系统背景：

• 系统的主要用途是什么？用户是谁？
• 当前处于哪个生命周期阶段？（从零开始设计 / 早期开发 / 增长期 / 成熟生产阶段）
• 团队规模和结构如何？（独立开发者、小型团队、多个团队、全组织范围）

规模与性能预期：

• 预期的规模目标是什么？（并发用户数、每秒请求数、数据量、增长率）
• 是否有具体的延迟或吞吐量要求？

部署与运维：

• 目标部署环境是什么？（云服务提供商、本地部署、混合云、多云）
• 这是面向消费者、面向企业/B2B、内部工具，还是几者兼有？

合规与安全：

• 是否有具体的合规要求？（SOC2、HIPAA、GDPR、PCI-DSS、FedRAMP 或其他）
• 是否有具体的安全要求或威胁模型方面的顾虑？

范围与重点：

• 用户是否希望优先关注某些特定方面？
• 是否已有已知风险或接受的权衡？
• 是否有明确不在范围内的事项？

根据实际情况调整问题——跳过输入中已经回答的问题，并根据你发现的情况补充领域特定的问题。问题应聚焦，避免让用户应接不暇。

等待用户回复后再进入第 2 阶段。

---

第 2 阶段：逐维度分析

从 7 个加权维度评估架构。对于每个维度：

1. 阅读相关参考文件，了解详细的子标准和评估指南
2. 根据输入评估每项适用的子标准
3. 跳过确实不适用的子标准（说明原因）
4. 对每项发现记录：严重程度、描述、证据、影响、建议
5. 使用 references/scoring-rubric.md 按 1–5 分制为该维度打分

维度及参考文件

#	维度	权重	参考文件
1	结构完整性与设计原则	20%	references/structural-integrity.md
2	可扩展性	18%	references/scalability.md
3	企业就绪度	15%	references/enterprise-readiness.md
4	性能	17%	references/performance.md
5	安全性	18%	references/security.md
6	卓越运维	7%	references/operational-excellence.md
7	数据架构	5%	references/data-architecture.md

渐进式加载： 仅在分析相应维度时阅读该维度的参考文件。不要一次性加载所有参考文件。

分析结构完整性时，如果评审涉及模块边界、可测试性、服务拆分或重构建议，还应查阅 references/deep-module-analysis.md。

特定模式指南：

• 对于代码库分析，还应查阅 references/codebase-signals.md，了解每个维度应检查哪些文件和模式。
• 对于文档分析，还应查阅 references/document-review-guide.md，了解完整性检查清单和常见缺漏。

问题严重程度级别

级别	标签	含义
S1	严重	系统将在生产环境中失效，或存在可被利用的活跃漏洞
S2	高	存在重大风险，在现实条件下会造成问题
S3	中	设计弱点，会限制增长或造成技术债务
S4	低	影响可控的次优选择
S5	信息性	观察结果、最佳实践建议或提醒注意的事项

架构模式评估

评审不预设任何架构模式。不要假定某种模式天然更优。 相反，应评估当前或拟议的模式是否符合系统需求。

当证据表明另一种架构模式更能满足系统需求时（例如，分布式单体应改为真正的单体，或进行合理拆分的微服务），请将其列为一项发现，并说明：

• 当前采用（或拟议采用）的模式
• 为什么该模式不适合这些需求
• 哪种替代模式更能满足系统需求，以及原因
• 迁移路径的考量（工作量、风险、分阶段实施）

---

第 3 阶段：跨领域分析

完成全部 7 个维度的评估后，进行综合分析：

1. 多维度发现 — 找出跨越多个维度的问题（例如，缺少缓存既是性能问题，也是可扩展性问题）。合并重复项，并指出其跨领域性质。

2. 相互冲突的决策 — 检测矛盾（例如，声称具备强一致性，同时又要求水平扩展，或选择微服务却共用数据库）。

3. 架构连贯性 — 各个部分能否构成一个统一整体？架构愿景是否清晰一致，还是一种偶然形成的架构？

4. 需求契合度 — 该架构是否真正解决了既定规模下的既定问题？相对于需求，它是过度设计还是设计不足？

5. 架构模式适用性 — 根据完整分析，所选（或自然形成的）架构模式是否合适？如果不合适，哪种模式更好，原因是什么？

6. 严重程度校准 — 复核出现在多个维度中的发现，或组合后会造成复合风险的发现。当跨领域分析表明多个问题组合起来的严重程度高于单独评估时：

   • 提高系统性问题的严重程度（例如，三个 S3 发现组合成一个 S1 系统性风险）
   • 在「跨领域问题」部分说明提高严重程度的理由
   • 确保最终的「系统性风险」部分反映校准后的（更高）严重程度
   • 相应调整建议的优先级

7. 系统性风险 — 找出最大的单一风险。如果有一个问题会让整个系统功亏一篑，那是什么？系统性风险的严重程度应反映第 6 步校准后的评估结果，该严重程度可能高于任何单项发现。

---

第 4 阶段：评分与报告生成

计算分数

1. 使用 references/scoring-rubric.md 中的评分标准为每个维度打 1–5 分
2. 计算加权总分：

   Overall = Σ(dimension_score × weight) / 5 × 100
   

3. 根据分数范围确定字母等级

生成报告

使用 assets/report-template.md 作为框架。填写所有部分：

• 执行摘要，包括总分、主要优势和主要风险
• 评分卡，列出各维度得分
• 各维度的详细发现（按严重程度排序）
• 跨领域问题
• 分为三个层级的优先级建议：快速见效、中期、战略性
• 在有助于阐明问题时使用 Mermaid 图（依赖关系图、数据流问题、拟议的改进方案）

模板合规检查清单（强制）

提交报告前，请核实以下所有内容。不合规将导致评审无效。

评分格式合规性：

• 所有维度的分数均采用 1-5 分制（不能使用 1-10 分制或百分比）
• 允许使用半分（例如，3.5），但必须说明理由
• 权重应用正确：20%、18%、18%、17%、15%、7%、5%
• 加权贡献值保留 3 位小数（例如，0.700，而不是 0.7）

严重性标签合规性：

• 所有发现均使用 [S1] 至 [S5] 严重性标签
• S1 = 严重，S2 = 高，S3 = 中，S4 = 低，S5 = 信息性
• 不要使用：高/中/低、P0-P3、严重/主要/次要或数字严重性
• 严重性符合 SKILL.md 严重性表中的标准

算术核验（来自 v1.1）：

• 报告中包含“分数计算核验”章节
• 算术明细列出每项：分数 × 权重 = 结果
• 计算并展示加权总和
• 展示百分比公式：加权总和 / 5 × 100 = X%
• 等级与评分标准中的百分比相符：A（90-100）、B（80-89）、C（70-79）、D（60-69）、F（<60）
• 报告中的核验清单已填写完成

报告结构合规性：

• 包含元信息表（评审日期、评审模式、系统阶段、总分）
• 执行摘要包含：分数、可视化、三大优势、三大风险、结论
• 评分卡表格包含全部 7 个维度，以及分数、权重、加权分数、关键发现列
• 详细发现章节包含全部 7 个维度，每个维度都有维度摘要和发现
• 每项发现均包含：严重性标签、证据、影响、建议
• 包含跨领域问题章节，涵盖：多维度问题、相互冲突的决策、架构一致性、需求一致性、模式适用性、系统性风险
• 已记录严重性调和过程（如果跨领域分析提高了任何严重性）
• 建议章节分为三个层级：快速见效项、中期、战略性
• 包含附录，涵盖：已审查文件、假设、范围外事项、不适用的子标准、方法论

内容质量门槛：

• 每个维度至少包含一项优势（S5 正面发现），除非该维度得分为 1
• 每项发现都包含具体证据（文件路径、行号或“文档中未涉及”）
• 每项建议都可执行（不能只写“改进安全性”，而应列出具体步骤）
• 已识别系统性风险，并评估其影响范围

如果有任何复选框未勾选： 请先修正问题，再提交报告。不要提交不合规的报告。

---

将已完成的报告作为 Markdown 文件输出。

---

校准规则

应用以下规则，确保评审公平且有用：

1. 考虑阶段： 绿地设计不应因缺少实现细节而被扣分。评估计划，而不是缺少的代码。反过来，成熟的生产系统应接受更高标准的评审。

2. 考虑规模： 个人开发者的业余项目不需要多区域主动-主动 HA。应根据明确的需求和团队规模，调整企业就绪度的预期。

3. 区分“不适用”和“缺失”： 如果系统是批量分析管道，P99 延迟目标就无关紧要——应标记为 N/A，而不是给零分。如果系统是面向用户的 API，却没有涉及 P99 延迟，那就应列为一项发现。

4. 肯定优点： 指出做得好的地方。全盘否定的架构评审会让人泄气，也较难采取行动。应从实实在在的优点说起。

5. 具体胜于笼统： 每项建议都必须可执行。“添加缓存”还不够。应说明缓存什么、采用什么策略、TTL 多长，以及原因。

6. 不依赖语言和框架： 评估架构决策，而不是语言选择。架构良好的 PHP 系统，得分应高于架构糟糕的 Rust 系统。

7. 坦诚面对未知： 如果输入信息不足以评估某个子标准，应明确说明。不要猜测，并指出还需要更多信息。

找借口

借口	事实
“它已经在生产环境中运行了”	今天能运行不代表它能扩展、易于维护，或能应对团队人员变动——架构债务会悄然累积
“等它出问题时我们再重构”	到那时，成本会高出 10 倍——在负载下重构积累了依赖的系统，就像外科手术，而不是例行工作
“框架会处理这些问题”	框架提供的是默认配置，不是架构——边界、错误传播和数据流仍由你负责
“这是内部服务，不必遵守标准”	内部服务变成外部服务的速度，往往比你预想的更快——技术债务会跨越边界迁移
“以我们目前的规模，性能没问题”	架构评审关注的是下一个 10 倍的规模，而不是当前状况——在 1k 行数据下看不出的 O(n^2)，到了 100k 行数据时就会显现
“我们没时间做完整评审”	不完整的评审会造成虚假的信心——与其肤浅地评审所有维度，不如深入评审较少的维度

警示信号

• 只评估正常路径，不追踪错误传播
• 没有可扩展性评估（缺少负载预测、瓶颈识别）
• 未阅读相关代码就为某个维度打分——仅依赖文档
• 未说明理由就将维度标记为 N/A
• 建议过于笼统（“添加缓存”“使用队列”），未说明具体内容、位置和原因
• 评审实现细节，而不是架构决策

验证

• 已评估全部 7 个维度，并为子标准打分
• 每项发现都包含具体的文件／组件引用
• 可扩展性评估包含具体的负载预测或增长假设
• 跨维度分析至少识别出一个涉及多个维度的问题
• 每项建议都说明要修改什么、在哪里修改，以及预期影响
• 明确说明标记为 N/A 的维度为何不适用——不得默默跳过
• 最终分数是加权综合分，而不是凭感觉取平均值