code-design-review

代码设计评审

角色：针对涉及代码变更的方案，在实施前进行设计质量评审。评估拟议代码是否设计精良——是否易于维护、可测试、解耦得当，而不仅仅是能否解决问题。这是 solution-review 的代码专用搭档；solution-review 负责任何类型方案的决策层面评审。PDCA 宿主会在 frontmatter dependencies 中声明此技能，并在前置检查后调用；若缺少此技能，宿主会在启动时中止。

详细框架条目（作者、年份、阈值、来源）以及完整的阻塞／非阻塞标准，见 reference.md。

此技能存在的原因

代码方案可能正确（能够解决问题），但设计仍然很糟糕——引入耦合，让下一次变更更困难；复杂度超出问题本身的要求；或者造成团队并未意识到的技术债。这些设计缺陷无法通过“能不能运行”的测试发现；数月后，它们会表现为维护的痛苦、连锁回归，以及对变更的畏惧。

AI 时代的前提：当实现成本低廉（包括借助 AI 编码）时，“能运行且近期易于维护”已是一个过低的标准。架构优雅性和长期可维护性必须在评审中占有更高权重——重写为更好的结构，往往比长期背负技术债成本更低。

此技能运用软件工程理论——而非主观意见——在编写任何代码之前评估代码设计质量。每项检查都追溯到一个具名框架（Brooks、Myers、Yourdon-Constantine、Fowler、McCabe、ISO 25010、Clean Architecture、OWASP）。核心经验是：

能运行但设计糟糕的代码，会成为明天的维护危机。应在实施前评审设计质量，此时调整方向的成本仍然很低；不要仅仅因为较弱的架构更容易交付，就推迟采用明显更好的架构。

何时使用

明确的信号（符合任意一项即可）：

• 拟议方案涉及代码变更，你需要在实施前评估其设计质量。
• 你正在评审设计文档、技术提案或包含代码结构决策（新模块、API 设计、重构、依赖变更）的方法。
• 有人询问“这段代码设计得好吗？”“将来易于维护吗？”或“这样的耦合可以接受吗？”
• 方案涉及架构层面的决策（新增抽象层、更改依赖方向、调整模块边界）。

此技能仅适用于代码方案。对于非代码方案（配置、流程、工具、无代码变更的架构决策），请使用 solution-review。方案涉及代码时，请同时使用两者：用 solution-review 评审决策，用此技能评审代码设计。

与其他技能的关系

技能	职责	与此技能的关系
solution-review	决策层面评审（有效性、风险、可逆性、可运维性、成本）	范围更广。对于代码方案，solution-review 评审决策；此技能评审代码设计。两者都要使用。
PDCA 宿主	宿主工作流	PDCA 宿主通过 frontmatter dependencies 引用此技能（缺失时 → 宿主中止）。深入评审其“评审方案”阶段中影响代码的方案。宿主是这一关系的 SoT。

代码设计质量模型

分为三个层次，按重要性排序——架构优先；评审深度根据方案范围调整。呈现顺序体现评审优先级：评审者应先关注架构层面的属性和长期可维护性，再关注代码层面的工艺。

A 层 — 架构级质量属性

这些属性评估解决方案对系统级质量属性的影响——这一层承载着架构设计和长期可维护性方面的要求。当解决方案新增模块、改变依赖方向、跨越模块边界、跨越进程或层级边界，或变更公开契约时，请完整执行 A 层评估。快速路径（改动较小且独立，不引入新边界，也不影响依赖方向）可以快速浏览 A 层——在报告中说明这一限制。不要因为实现看起来简单就跳过 A 层。

1. 可测试性（Clean Architecture — Uncle Bob）— 能否在不依赖 UI、数据库、Web 服务器或外部服务的情况下测试业务逻辑？如果解决方案导致逻辑无法单独测试，就违反了架构原则。难以测试的信号：隐藏依赖、静态方法调用、单例、违反迪米特法则。
2. 模块化（ISO/IEC 25010 — 可维护性 → 模块化）— 一项变更是否能将对其他组件的影响降至最低？
3. 可靠性／韧性（ISO/IEC 25010 — 可靠性 → 容错性、可恢复性）— 解决方案是否考虑了故障场景（降级、重试、熔断）？
4. 可扩展性（ISO/IEC 25010 — 性能效率 → 容量）— 解决方案能否应对预期的数据量／并发增长，还是引入了瓶颈？
5. 依赖方向（稳定依赖原则 + Clean Architecture 依赖规则）— 依赖是否指向稳定性更高的模块（不稳定模块依赖稳定模块），还是稳定模块依赖不稳定模块（方向反转，容易出问题）？架构边界验证（针对跨进程或跨层级的解决方案）：（a）运行时初始化位置 — 实际由哪个进程／层级初始化被调用的能力（FFI 句柄、数据库、缓存、服务单例）；（b）边界合法性 — 调用方是否可以合法访问该能力，还是跨层静态或动态导入会将被调用方的依赖树（及其循环依赖）引入调用方的打包图中？打包工具的静态预扫描意味着动态 require/import 无法绕过这一限制；（c）归属分类 — 该能力是系统能力（应归属壳层／宿主层），还是数据／产品能力（应归属服务／产品层），且这是否符合调用层的定位？

第 B 层 — 代码级设计指标（每次代码变更均适用，强制要求）

这些指标适用于任何规模的代码变更。每项指标都对应一个具名的软件工程框架：

6. 意外复杂性（Fred Brooks，《No Silver Bullet》，1986）——解决方案是否引入了与问题固有复杂性无关的间接层、配置或抽象？每个新抽象都必须有一个 当下 存在的理由；“以后可能会需要”属于意外复杂性——在评审时将其删掉。
7. 耦合分类（Myers 耦合分类法 + Connascence，Page-Jones 1996）——变更引入了哪种类型的耦合？数据耦合（传递数据，可接受）→ 印记耦合（共享复合结构，风险较低）→ 控制耦合（传递标志来控制另一个模块的逻辑，泄露决策）→ 公共耦合（共享可变状态，风险高）→ 内容耦合（直接操作另一个模块的内部结构，不可接受）。Connascence 进一步细化了这一分类：名称／类型同生关系无害；算法／执行／时序同生关系则很脆弱。
8. 内聚性梯度（Yourdon & Constantine，《Structured Design》，1979）——变更之后，模块中的元素是否围绕单一目的汇聚（功能内聚，最强），还是仅仅因时间／逻辑／偶然性而捆绑在一起（时间内聚／逻辑内聚／偶然内聚，最弱）？内聚性下降是设计劣化的早期信号。
9. 变更放大（Fowler，《Shotgun Surgery》代码异味 + 开闭原则）——解决方案是将频繁变更局限在特定位置，还是让一项逻辑变更散落在多个文件中？良好的设计会将易变决策（业务规则、配置）与稳定核心（数据模型、算法）分离。
10. 技术债分类（Fowler，技术债四象限）——这项债务属于审慎且有意（明知而选择，并有偿还计划，可以接受），还是鲁莽且无意（因不了解更好的设计而引入，例如上帝对象、推测性通用化、原始类型偏执）？必须阻止鲁莽且无意的债务，因为持有者不知道债务存在，也永远不会偿还它。
11. 复杂度指标——圈复杂度（McCabe，1976）：决策点数量 + 1；超过 10 应评审，超过 15 风险较高，超过 20 则单个函数不可接受。认知复杂度（SonarSource，2016）：通过对嵌套、递归和逻辑运算符加权，衡量人类阅读和理解的难度；超过 15 应评审。优先使用认知复杂度——它能捕捉圈复杂度遗漏的情况（即使分支很少，深层嵌套读起来也很困难）。
12. 得墨忒耳定律（Lieberherr & Holland，1989）——方法只应与直接的关联对象交互，而不应与陌生对象交互：a.b().c().d()（“火车残骸”）会使调用方与远处对象的内部结构耦合。若拟议设计中的链式调用深度超过 2 层，应标记出来。

第 C 层 — 安全审查（解决方案涉及信任边界时）

13. OWASP Top 10 轻量审查——当解决方案涉及身份验证、授权、输入处理、数据存储或外部通信时，进行一次轻量级 OWASP 审查：注入（未参数化的查询）、身份验证失效、敏感数据泄露、XXE、访问控制失效、安全配置错误。这不是完整的安全审计；它旨在在设计阶段发现安全错误，避免它们演变为代码问题。

每项指标的详细方法、阈值和来源引文见 reference.md。

如何应用

1. 确认解决方案涉及代码。 如果不涉及，请改用 solution-review。
2. 运行 Layer A（架构），遵循其范围规则——完整路径或快速路径；报告中务必说明所用路径。
3. 对每项代码变更运行 Layer B。 针对 7 项指标分别给出通过／不通过结论，并结合拟议的代码结构说明具体理由。
4. 仅当解决方案涉及信任边界（身份验证、输入、数据、外部通信）时运行 Layer C。否则跳过。
5. 生成结构化审查报告（见下方“输出”），逐项给出结论、阻塞／非阻塞分类及总体结论。
6. 以阻塞问题作为门槛。 存在阻塞问题意味着代码设计不通过。即使实现成本低（包括借助 AI），也不能因此将实质性的架构缺陷降为非阻塞备注。

阻塞与非阻塞（摘要）

阻塞（任意一项成立 → 代码设计不通过）：

• 依赖方向颠倒——稳定模块依赖不稳定模块（违反 SDP）。
• （Layer A，完整路径） 业务逻辑无法脱离外部依赖进行隔离测试（违反整洁架构的可测试性），且没有补偿措施。
• （Layer A，跨边界解决方案） 被调用的能力在调用方进程／层中没有运行时，或跨层导入将无关的依赖树引入调用方——除非明确接受将其作为 Prudent-Deliberate 债务，并制定偿还计划，否则阻塞。短期成本优势（复用现有实现、在同一仓库中修改、无需跨团队协调）不能降低此判定等级。
• 存在内容耦合（直接操纵其他模块的内部）或公共耦合（共享可变状态），且没有替代方案。
• 引入了鲁莽无意的技术债——在未意识到有更优设计的情况下引入上帝对象／推测性通用化／基本类型偏执。
• 单项业务变更需要对 3 个或更多没有直接业务关系的模块进行连锁修改（散弹式修改），且没有收敛策略。
• （安全） 在设计层面违反 OWASP Top 10 中的某个类别（例如，设计允许注入或访问控制失效）。
• 已确定一种明显更优的模块化／依赖／边界设计，该设计在当前变更范围内可行，且能实质性提升长期可维护性，而团队又未明确接受将其作为 Prudent-Deliberate 债务并制定偿还计划。不能仅因较弱的设计正确且近期易于维护，就判定通过。

非阻塞（记录为建议，不阻塞）：

• 不改变结构、耦合或变更放大效应的风格或命名偏好。
• 有文档化偿还计划的 Prudent-Deliberate 技术债（包括明确接受的较弱架构）。
• 在本身复杂的领域中，圈复杂度／认知复杂度略高于阈值（需记录理由）。
• 存在更优雅的实现细节（架构相同），但当前实现正确，且不会降低长期可维护性。

含特定框架阈值的完整阻塞／非阻塞标准见 reference.md。

输出

代码设计审查报告，结构如下：

【Code design review report】
- Subject: [solution name / code area]
- Path: [quick / full] + [security pass: yes/no]
- Layer A architecture quality attributes (full path):
  1. Testability: ✅/❌/N/A
  2. Modularity: ✅/❌/N/A
  3. Reliability / resilience: ✅/❌/N/A
  4. Scalability: ✅/❌/N/A
  5. Dependency direction: ✅/❌/N/A
- Layer B code-level design metrics:
  6. Accidental complexity: ✅/❌ [reasoning]
  7. Coupling type: ✅/❌ [type identified + risk level]
  8. Cohesion: ✅/❌ [cohesion level + trend]
  9. Change amplification: ✅/❌ [shotgun surgery check]
  10. Tech-debt classification: ✅/❌ [quadrant identified]
  11. Complexity measures: ✅/❌ [cyclomatic / cognitive estimate]
  12. Law of Demeter: ✅/❌ [train-wreck check]
- Layer C security pass (trust boundary):
  13. OWASP lightweight pass: ✅/❌/N/A
- Issue list: [#] [description] [severity: blocking/non-blocking]
- Verdict: ✅ pass / ❌ fail
- [On ❌] Optimization guidance: [per-issue improvement direction]

反模式（禁止的做法）

1. 未经设计审查就批准“能运行”的代码——正确性是必要条件，但并非充分条件；仅因测试通过就完全跳过 Layer A/B/C，正是设计债务在不知不觉中累积的原因。
2. 对所有变更都运行 Layer C（安全）——OWASP 审查仅适用于涉及信任边界的变更。过度应用会浪费审查精力；而在涉及信任边界时未予应用则很危险。