Back to Details

design-review

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Design Review Orchestrator

设计评审编排器

When invoked with $ARGUMENTS, scope the entire review to the specified target. Read the target code first, then proceed through the phases below in order. This skill orchestrates other skills from Clairvoyance (https://clairvoyance.fyi). It works best when the full collection is installed.
This skill does not replace individual lenses. It sequences them into a diagnostic funnel that moves from broad to narrow, skipping work when early phases find nothing actionable.
当使用$ARGUMENTS调用时，将整个评审范围限定在指定目标。首先读取目标代码，然后按顺序执行以下阶段。本Skill会编排来自Clairvoyance（https://clairvoyance.fyi）的其他Skill，安装完整集合时使用效果最佳。
本Skill不会替代单独的评审视角，而是将它们按顺序整合到一个从宽到窄的诊断漏斗中，若早期阶段未发现可操作问题则会跳过后续工作。

Diagnostic Funnel

诊断漏斗

Phase 1: Complexity Triage

阶段1：复杂度分类

Apply complexity-recognition checks against the target.
  • Identify the three symptoms: change amplification, cognitive load, unknown unknowns
  • Trace any symptoms to root causes: dependencies or obscurity
  • Weight findings by the complexity formula: high-traffic code first
This phase determines whether the target has measurable complexity problems. If it does, subsequent phases diagnose where.
对目标应用complexity-recognition检查：
  • 识别三类症状：变更放大、认知负载、未知的未知
  • 追踪所有症状的根本原因：依赖或不透明性
  • 按照复杂度公式对发现的问题加权：高流量代码优先
本阶段会判断目标是否存在可衡量的复杂度问题。如果存在，后续阶段会诊断问题所在位置。

Phase 2: Structural Review

阶段2：结构评审

Apply these lenses to the target's module-level architecture:
  • module-boundaries: Are the boundaries drawn around knowledge domains or around steps in a process?
  • deep-modules: Does each module provide powerful functionality behind a simple interface? Check for classitis, pass-through methods and shallow wrappers.
  • abstraction-quality: Does each layer provide a genuinely different way of thinking, or do adjacent layers duplicate the same abstraction?
Focus on the modules that Phase 1 identified as highest-complexity. If Phase 1 found nothing, scan the largest or most-connected modules.
对目标的模块级架构应用以下评审视角：
  • module-boundaries：边界是围绕知识域划分的，还是围绕流程步骤划分的？
  • deep-modules：每个模块是否在简洁的接口背后提供了强大的功能？检查classitis、透传方法和浅包装的问题。
  • abstraction-quality：每一层是否提供了完全不同的思考方式，还是相邻层重复了相同的抽象？
重点关注阶段1识别出的复杂度最高的模块。如果阶段1未发现任何问题，则扫描最大或关联最多的模块。

Phase 3: Interface Review

阶段3：接口评审

Apply these lenses to the interfaces exposed by the modules from Phase 2:
  • information-hiding: Does the interface leak implementation details? Check for back-door leakage (shared knowledge not in any interface).
  • general-vs-special: Does the interface mix general-purpose mechanisms with special-case knowledge? Check for boolean parameters serving one caller.
  • pull-complexity-down: Are callers forced to handle complexity the module could absorb? Check for exposed edge cases, required configuration and exceptions that could be defined away.
  • error-design: Are errors defined out of existence where possible? Check for catch-and-ignore, overexposed exceptions and error handling longer than the happy path.
对阶段2筛选出的模块暴露的接口应用以下评审视角：
  • information-hiding：接口是否泄露了实现细节？检查后门泄露（任何接口都未定义的共享知识）。
  • general-vs-special：接口是否将通用机制与特殊场景知识混合？检查仅服务于单个调用方的布尔参数。
  • pull-complexity-down：调用方是否被迫处理本可以由模块消化的复杂度？检查暴露的边缘 case、必填配置以及本可以被定义消除的异常。
  • error-design：是否尽可能从根源上消除了错误？检查catch-and-ignore、过度暴露的异常以及比正常路径更长的错误处理逻辑。

Phase 4: Surface Review

阶段4：表层评审

Apply these lenses to naming and documentation:
  • naming-obviousness: Do names create precise mental images? Check the isolation test: seen without context, could the name mean almost anything?
  • comments-docs: Do comments capture what the code cannot say (intent, rationale, constraints)? Check for comments that repeat code and implementation details contaminating interface documentation.
对命名和文档应用以下评审视角：
  • naming-obviousness：命名是否能生成准确的心智图景？检查隔离测试：脱离上下文看，这个命名是不是几乎可以指代任何事物？
  • comments-docs：注释是否记录了代码无法表达的内容（意图、基本原理、约束）？检查重复代码的注释，以及污染接口文档的实现细节。

Phase 5: Red Flags Sweep

阶段5：危险信号排查

Run the full red-flags 17-flag checklist against the target. Any flag triggered in Phases 1-4 will already be marked. This phase catches flags that earlier phases may not have surfaced (especially Process flags 15-17: No Alternatives Considered, Tactical Momentum, Catch-and-Ignore).
对目标运行完整的red-flags17项检查清单。阶段1-4中触发的任何标记都已被标注，本阶段会捕获早期阶段可能未发现的标记（尤其是第15-17项流程类标记：未考虑替代方案、战术惯性、Catch-and-Ignore）。

Early Termination

提前终止

If Phase 1 finds no measurable complexity AND Phase 5 triggers zero flags, stop. Report the target as clean. Do not force findings where none exist.
如果阶段1未发现可衡量的复杂度问题，且阶段5未触发任何标记，则停止评审，报告目标无问题。不要在不存在问题的地方强行生成结论。

Prioritization

优先级排序

Rank findings in this order:
  1. Syndrome clusters: Multiple flags pointing to the same root cause (e.g., information leakage + conjoined methods + repetition all stemming from one misplaced boundary). These indicate systemic issues. Fixing the root cause resolves all flags in the cluster.
  2. Boundary issues: Information leakage, module boundary problems and abstraction mismatches. These compound over time and infect adjacent code.
  3. Canary flags: Hard to Pick Name, Hard to Describe, Non-obvious Code, No Alternatives Considered. These are the cheapest signals. Catch them and the structural flags never materialize.
  4. Structural issues: Shallow modules, pass-through methods, classitis. These require refactoring but affect a bounded area.
  5. Surface issues: Naming and documentation problems. Important but lowest cost to fix and lowest risk if deferred.
按以下顺序对发现的问题排序：
  1. 综合症集群：指向同一根本原因的多个标记（例如，信息泄露+连体方法+重复代码都源自同一个不合理的边界划分）。这些属于系统性问题，修复根本原因即可解决集群内的所有标记。
  2. 边界问题：信息泄露、模块边界问题和抽象不匹配。这些问题会随时间累积并影响相邻代码。
  3. 预警标记：难以命名、难以描述、代码不直观、未考虑替代方案。这些是成本最低的信号，及时捕获就不会演化出结构性问题。
  4. 结构性问题：浅模块、透传方法、classitis。这些需要重构，但影响范围有限。
  5. 表层问题：命名和文档问题。虽然重要，但修复成本最低，延后处理的风险也最低。