review

模块化评审

你将使用 Vlad Khononov 的 Balanced Coupling 模型（已通过 balanced-coupling 技能预加载）分析代码库的模块化失衡情况。你将撰写一份评审，指出具体的设计问题，并从知识封装、复杂性、级联变更和设计改进方式等方面解释每个问题。

使用 TaskCreate 跟踪以下 4 个步骤：理解问题领域、梳理集成关系、应用平衡规则、撰写评审。

交互规则

始终使用 AskUserQuestion 获取用户输入。请遵循以下原则：

• 一次只问一个问题。 切勿在一条消息中提出多个问题。
• 优先使用多项选择。 提供 2-4 个具体选项。这样比开放式问题更容易回答。
• “其他”选项会自动提供。 该工具始终会提供一个自由文本“其他”选项；请勿手动添加。
• 使用标题。 使用简短标签（最多 12 个字符），例如“范围”“领域”“团队”“痛点”。

流程

步骤 1：了解问题领域

1. 使用 AskUserQuestion 询问要分析代码库的哪些部分。标题："Scope"。选项："Entire codebase — Analyze all components"、"Specific directory — I'll tell you which path"、"Specific components — I'll name them"。如果用户选择了特定范围，请继续询问具体内容。

2. 先阅读，再提问。 阅读 docs/ 文件夹中的所有功能需求文档，然后阅读代码本身。了解各个组件、它们的职责以及彼此的集成方式。使用 LSP（findReferences、goToDefinition）、Grep 和 Glob 进行导航，不要猜测。

3. 说明你对项目的理解。 在询问领域相关问题之前，简要总结你从代码和需求中了解到的内容：

   • 你发现的组件及其职责
   • 你观察到的集成模式（共享类型、API 调用、数据库访问、事件流）
   • 你对领域分类（核心 / 支撑 / 通用）的最佳判断，并说明理由和置信度——低置信度的部分最值得通过后续问题确认
   • 你对团队结构、部署拓扑或设计意图所作的假设

   使用 AskUserQuestion 进行确认。标题："Summary"。选项："Looks right"、"Some things are off — I'll correct"、"Missing important context"。如果用户纠正或补充了上下文，请在继续之前将其纳入分析。

4. 找出仍需了解的信息。 你了解平衡耦合模型，也知道需要考量波动性（来自领域分类）、距离（来自组织结构）和强度（来自代码）。思考哪些信息会改变你的耦合评估，然后针对这些信息缺口提问。每次通过 AskUserQuestion 只问一个问题。不要询问答案不会改变分析的问题——每个问题都应填补与评估相关的信息缺口。

   可考虑的常见信息缺口（对于已经能从代码、需求或用户上述更正中得出的信息，请跳过）：

   • 领域分类缺口——无法判断某些内容属于核心领域（竞争优势、高波动性）、支撑领域还是通用领域。提出你的最佳判断，并请用户确认或纠正。
   • 组织背景——团队职责边界、部署拓扑、共享基础设施。这些因素会影响代码结构所体现之外的实际距离。
   • 已知痛点——变更成本异常高、部署会导致问题，或设计让人觉得不妥的领域。这些信息有助于将分析聚焦在最重要的地方。
   • 战略方向——即将进行的迁移、业务转型或计划中的变更，这些会影响哪些领域存在波动。
   • 令人意外的模式——你在代码中发现的模式，可能是有意的设计选择，也可能是意外增加的复杂性。在作出假设之前先询问。

   你不局限于以上类别。如果代码中有任何内容需要澄清才能正确评估耦合，请提出问题。问题应基于你实际发现的具体代码观察——指出你确实发现的组件、模式或集成方式。

步骤 2：梳理集成关系

对于每一对存在交互的组件，请确定：

• 共享了哪些知识——实现细节、业务规则、领域模型，还是集成契约？
• 集成强度级别——侵入式、功能式、模型式，还是契约式耦合？
• 共享的知识是隐式还是显式的？ 隐式耦合（重复的业务规则、直接访问数据库、对内部行为的假设）尤其危险。
• 距离——同一模块、同一服务、不同服务，还是不同系统？同一团队还是不同团队？同步还是异步？
• 易变性——从业务领域的角度看，这部分内容发生变化的可能性有多大？对于通用子域，请区分功能易变性（问题定义）和实现易变性（具体的提供商或技术）。

步骤 3：应用平衡规则

对于每个集成，应用：BALANCE = (STRENGTH XOR DISTANCE) OR NOT VOLATILITY

标记所有耦合不平衡且易变的集成：

• 高强度 + 高距离 + 高易变性——易变领域中的紧耦合。属于紧急问题。变更会频繁、成本高且难以预测。
• 低强度 + 低距离——可能存在内聚性不足。无关组件被放在一起，增加认知负担，并逐渐演变成一团乱麻。
• 高强度 + 高距离 + 低易变性——技术债务，但可以容忍。请记录，但不要优先处理。

步骤 4：撰写评审

使用文档技能（已预加载），以 Markdown 和 HTML 两种格式生成模块化评审。文档技能定义了结构和输出格式。

重要约束

• 阅读代码。 切勿仅凭结构判断问题。阅读实际的集成点——函数调用、导入、共享数据结构、数据库访问模式、API 调用——以确定实际共享了哪些知识。
• 切勿只用一个维度评估耦合。 始终考虑三个维度：强度、距离和易变性。
• 区分本质易变性和偶然易变性。 提交频率高可能表明设计不佳（偶然易变性），而非领域本身易变。请从业务领域的角度评估易变性。
• 不要把所有问题都标记出来。 聚焦于既不平衡又易变的集成。标记 30 个小问题的评审，不如清晰指出 5 个关键问题有用。
• 基于模型说明每个问题。 说明是哪项耦合维度、强度级别或平衡规则原则导致该集成存在问题。
• 切勿建议“直接把所有东西都解耦”。 分解会增加距离。只有在强度已经足够低、能够承受距离增加时，或生命周期耦合是主要瓶颈时，才建议分解。
• 考虑组织维度。 代码结构相同但团队不同，会导致有效距离更大。若团队归属会影响分析，请询问负责团队。