用途
该技能旨在让复杂度可见,解释哪些复杂度是必需的,并识别哪些可以简化。它借鉴“展示给我看”的方法:使用最能说明问题的最小视觉图,将证据放在旁边,并保持文字简短。
主要能力
- 确定范围:根据对话识别目标与用户需要做出的决策。对于变更,建立比较基线,并包含相关的已暂存、未暂存和新文件。对于提案,区分提议设计与现有代码。
- 收集证据:从适用的项目指南、包文档、文件清单、入口点和调用方搜索开始。在判断抽象之前,区分生产使用的 API、仅测试使用的 API 和看似未使用的代码。在宣布入口点未使用之前,检查注册和受支持的外部消费者。对于看似重复的实现,确定生产调用方实际使用哪一个。
- 选择关键工作流:从清单中选择有后果的工作流,追踪其调用方、状态、依赖关系和失败路径,并阅读管理它们的需求。仅当解决可能改变分类或建议的命名问题时才扩大发现范围。
- 分类负担:对单条规则、关系或机制进行分类,而不是将整个模块标记为必要或偶然。
- E(必要):在满足相同需求和约束的更简单设计下仍然存在的复杂度。需要命名不变量或约束、其来源以及移除后会破坏什么。
- A(偶然):源于所选实现、可在保留需求的同时减少的复杂度。需要展示一个合理的更简单设计,并解释它如何保留行为。
- ?(未确定):分类取决于尚未确立的事实。需要命名缺失的事实以及如何解决。
- 选择可视化:以主要发现和一个紧凑视图开头。使用检查材料中的真实名称,并包含 E/A/? 图例。仅在回答不同问题时才添加另一个视图。可用视图包括:带注释热点和检查覆盖范围的浅层责任树、显示所有权、间接性和变更耦合的调用树或依赖图、显示决策、失败路径和协调的状态或序列图、前后树或结构差异、当前/提议视图。在足够时使用文本树、伪代码或 Mermaid。标注箭头含义(如调用、数据流或依赖)。保持提议标签与观察到的行为区分开。显式折叠重复细节,以免图表暗示省略的工作消失了。同时使用文本标签和颜色。
- 评估简化:简化发现需要具体的负担和一个合理的替代方案,其收益证明其成本和风险是合理的。如果已评估范围内的工作流没有候选方案达到该阈值,则停止并报告在检查范围内未发现值得的简化。评估每个实质性简化时考虑:哪些规则、状态、依赖、翻译或协调步骤消失,以及哪些具体代码或配置可以移除;责任去向何处,之后谁必须理解或操作它;哪些行为和约束保持不变,以及支持该说法的证据;替代方案引入什么权衡、迁移工作或新失败模式;什么标记完成,命名要保留的附带代码或测试以及现有验证边界,或识别验证缺口。
- 给出决策:在视觉图之后,给出简洁、按优先级排列的建议。如果发现值得的简化,以最多三个短要点呈现最高价值的建议。否则,简要解释当前设计为何合理。仅在未解决的事实可能改变结论时才包含它们。每条建议应命名移除的负担、引用其证据,并提及任何决定性权衡。引用视觉图中已有的注释,而不是再次解释。当某些内容可能被误认为可移除的复杂度时,提及要保留的内容。保持当前设计是一个有效的结论。
使用方式
该技能通过对话触发,用户可要求分析特定项目、模块、工作流或变更的复杂度。技能将按照上述步骤执行:确定范围、收集证据、选择关键工作流、分类负担、选择可视化、评估简化并给出决策。当主题需要更丰富的视觉图或用户要求时,可创建一个聚焦的、自包含的 HTML 制品,并通过可用的预览工具展示。
适用场景
- 代码审查中评估变更引入或移除的复杂度。
- 架构评估中定位复杂度集中区域。
- 理解模块难以理解或修改的原因。
- 分析工作流难以协调的原因。
- 评估更简单设计是否有帮助。
限制
- 分类基于已确立的事实;缺失理由视为不确定性,而非机制不必要的证据。
- 偶然复杂度并不意味着现在就值得移除;需记录所选机制的收益和替换成本。
- 复杂度评估需与范围成比例;小删除只需简短交接。
- 不实现重构,除非用户要求。
- 不编造复杂度评分或百分比,优先使用具体观察。