seam-ripper

拆解代码

系统地剖析代码库的内部架构，找出其中的问题，并提出正确的方案。

原则

没有不可质疑的惯例。 现有模式只是过往决策的证据，并不代表它们正确。

接缝揭示真相。 组件的连接方式能揭示系统的实际面貌，而非文档声称的样子。

向后兼容不是约束。 目标是建立正确的架构。迁移是另一个问题。

复杂性在证明无罪前都视为有罪。 每个抽象、间接层和接口都必须证明其存在的必要性。

执行

阶段 1：摸清地形

在评判系统之前，先全面了解其内部结构。

1. 识别所有模块／包／命名空间 —— 列出每个独立的代码单元
2. 追踪导入／依赖关系图 —— 哪些单元依赖哪些单元，以及依赖原因
3. 汇总公共接口 —— 每个导出的函数、类、类型和常量
4. 找出数据契约 —— 跨越边界的共享类型、DTO 和架构
5. 定位集成点 —— 模块实际交互的位置

输出依赖关系图，显示：

• 模块 → 模块的依赖边及依赖原因
• 循环依赖（明显的危险信号）
• 每个模块的入度／出度计数

阶段 2：审视每个接缝

针对识别出的每个边界，回答以下问题：

接口清晰度

• 仅凭公共接口，能否理解该模块的职责？
• 是否导出了“util”或“helper”？（异味：职责不明确）
• 接口是否暴露了实现细节？

依赖方向

• 这种依赖在概念上是否合理？
• “低层”模块是否依赖“高层”模块？
• 反转这种依赖能否简化双方？

耦合评估

• 接口发生变化时，还有多少其他模块会受影响？
• 耦合是通过数据、行为，还是两者兼有？
• 能否用事件／消息替代直接调用？

抽象完整性

• 接口是否泄露了实现细节？
• 调用方是否在执行本应由模块内部完成的工作？
• 是否有多种方法可以实现同一件事？

契约稳定性

• 该接口在历史上变更过多少次？
• 是否有带版本号的接口或弃用警告？（异味：契约不稳定）
• 测试是否会模拟这个接口？（耦合痛点的证据）

阶段 3：找出失败模式

留意以下系统性问题：

模式	症状	实际问题
上帝模块	所有模块都导入它，公共 API 过于庞大	缺少领域边界
霰弹式修改	一项更改需要修改许多模块	职责分散
特性依恋	模块 A 总是深入访问模块 B 的数据	数据／行为归属错误
不当亲密	两个模块共享私有细节	应合并为一个模块，或建立明确契约
中间人	模块只是把工作转交给另一个模块	不必要的间接层
平行继承体系	添加 X 就需要在另一个模块中添加 Y	缺少抽象
臆测式通用化	为灵活性设计的接口从未被使用	过早抽象
无效抽象	接口始终只有一个实现	抽象缺乏用途

第 4 阶段：提出重新设计方案

针对每个重要问题，提供：

1. 指控 清楚说明问题所在，以及为何重要。具体说明：

• “模块 X 有 47 个公开导出项，并被 23 个其他模块导入”
• “User 类型定义在 core 中，但它的字段仅由 billing 使用”

2. 正确的架构 描述它应该是什么样子：

• 明确的模块边界及其职责
• 遵循概念层级的依赖方向
• 表达意图而非实现细节的接口

3. 改造方案 说明从错误状态改为正确状态的具体步骤：

• 哪些内容移到哪里
• 哪些内容要拆分或合并
• 哪些接口需要更改
• 会产生哪些新的抽象

4. 证据 说明这样做为何更好：

• 降低耦合（量化：N 次导入 → M 次导入）
• 职责更清晰
• 更易于测试、扩展或替换

输出格式

# Seam Analysis: [System/Area Name]

## Dependency Map
[Visual or textual representation of module dependencies]

## Critical Findings

### Finding 1: [Problem Name]
**Location:** [modules/files involved]
**Severity:** Critical | High | Medium
**Pattern:** [which failure pattern]

**Evidence:**
[Specific code/structure references]

**Indictment:**
[Clear statement of what's wrong]

**Redesign:**
[Proposed correct architecture]

**Transformation:**
1. [Step]
2. [Step]
...

### Finding 2: ...

## Recommended Architecture

[Overall vision for how the system should be structured]

## Transformation Sequence

[Ordered list of changes, grouped by logical phases]

不可逾越的红线

拒绝：

• 提出保留错误架构的“渐进式改进”
• 接受“但它能运行”作为糟糕设计的理由
• 建议用适配器/门面掩盖问题，而不是解决问题
• 仅因接口被广泛使用就保留它们

始终做到：

• 指出真正的问题，而非表象
• 提出正确的设计，而非折中方案
• 尽可能量化耦合和复杂度
• 解释令重新设计方案正确的概念模型