refactoring-guide

重构指南

LLM 在重构过程中总是会出错的原则。此技能用于纠正其在耦合分析、类型级设计、模块边界和安全迁移策略方面的系统性盲点。

核心问题：LLM 优化的是代码 看起来如何（结构相似性），而良好的模块化优化的是代码 如何一起变化（时间内聚性）。此处的每条原则都旨在弥合这一差距。

自我进化的技能：此技能会在使用过程中不断改进。如果说明有误、参数发生偏移，或需要使用变通方案，请立即修正此文件，不要拖延。仅针对真实且可复现的问题进行更新。

适用场景

• 重构任务：提取模块、拆分文件、降低耦合、重新组织
• 代码审查：发现代码异味并提出恰当的修复方案（而非表面修补）
• 架构决策：模块边界、依赖方向、集成点
• 主动应用：检测到下方“检测启发式”表中的任何信号时

工作流

重构时，请按以下顺序进行：

1. 检测 — 根据“检测启发式”表扫描代码，识别存在的代码异味。
2. 诊断 — 针对每种代码异味，阅读相应的参考文件，了解正确的原则。
3. 规划 — 使用恰当的技术设计重构方案。对于涉及多个文件（>3 个文件）的更改，请使用 Mikado Method（参见 references/architecture.md）。
4. 执行 — 应用更改。对于共享接口，请使用扩展-收缩策略（参见 references/tactical-moves.md）。
5. 验证 — 确认重构降低了第 1 步中识别出的特定耦合类型。

检测启发式

扫描以下信号，确定应应用哪项原则：

信号	可能的异味	原则	参考
同一组参数传递给 3 个或更多函数	数据团块	解析，而非验证——提取参数对象	type-design.md §1
方法使用的其他类字段多于自身字段	特性嫉妒	将方法移到数据所在的位置	module-boundaries.md
if isinstance / 类型分支超过 2 个分支	缺少多态性	用多态替换条件判断	type-design.md §2
模块之间存在导入循环	违反无环原则	提取共享依赖或反转依赖	module-boundaries.md §2
公共 API 中有布尔参数	标志参数	拆分为独立方法或使用枚举	tactical-moves.md §5
# TODO: remove after migration 已超过 3 个月	死代码	立即删除	tactical-moves.md §1
函数既有 return，又有副作用（数据库／文件／网络）	关注点混杂	函数式核心，命令式外壳	architecture.md §1
测试需要模拟超过 3 个依赖	过度耦合	缺少接缝——找出并创建一个	structural-coupling.md §1
更改一项功能会涉及超过 3 个目录	切分方式不当	按功能而非按层组织包	module-boundaries.md §1
两个模块总是在同一个 PR 中一起更改	模块化不足	共同闭包——合并它们	module-boundaries.md §3
一个模块因无关原因而更改	变更分散	按变更原因拆分	structural-coupling.md §4
一项逻辑更改涉及 5 个或更多文件	散弹式修改	合并分散的关注点	structural-coupling.md §4
必须先调用 init()，才能调用 process()	时序耦合	类型状态模式	type-design.md §4
业务逻辑深处使用外部 API 类型	集成泄漏	在边界处设置防腐层	architecture.md §2
同一个结构体在 3 个或更多不同模块中被修改	数据所有权不明确	为每种数据类型指定所属模块	structural-coupling.md §5
核心逻辑中使用供应商 SDK 类型	易变性泄漏	在窄而稳定的接口后封装	structural-coupling.md §6
模块暴露 setter，而非操作	不受保护的不变量	暴露能清楚表达意图的操作	module-boundaries.md §5
基础设施异常泄漏到业务逻辑中	错误泄漏	在模块边界处转换错误	module-boundaries.md §6
没有逻辑的透传层（仅转发调用）	虚假模块化	移除不必要的间接层	tactical-moves.md §9
模块命名为 utils、common、helpers、shared	杂物堆	按实际使用者群组拆分	module-boundaries.md §4
控制器、处理器或作业中包含领域逻辑	业务逻辑位置不当	提取到领域模块	architecture.md §1
分散在各模块的服务自行构建依赖	缺少组合根	在应用入口点集中装配依赖	architecture.md §5
既负责协调又决定一切的上帝服务	编排职责混杂	将编排与计算分离	architecture.md §1

原则概要

每项原则都在 references/ 中详细介绍。遇到相应的代码异味时，请阅读相关文件。

结构耦合（references/structural-coupling.md）

1. 识别接缝 — 提取前先找到自然接缝；不要横跨接缝进行切分
2. 耦合谱系 — 耦合有 9 个强度级别；重构时应趋向较弱的形式
3. 稳定性指标 — 沿稳定性更高的方向依赖（不稳定性更低）
4. 发散式变更与霰弹式修改 — 两者相反，需要采取相反的修复方式；不要混淆
5. 数据所有权 — 每个数据结构都由一个模块负责；其他模块通过契约读取，绝不修改
6. 隔离易变因素 — 将高频变更的依赖封装在狭窄、稳定的接口后

类型级设计（references/type-design.md）

1. 解析，而非验证 — 在边界处解析为有类型的结果；绝不将原始输入传递到下游
2. 让非法状态无法表示 — 使用带判别值的联合类型，而非布尔字段或可选字段
3. 新类型 / 品牌类型 — 用不同类型包装基本类型，避免语义混淆
4. 时序耦合 → 类型状态 — 返回新类型，只公开当前有效的方法

架构（references/architecture.md）

1. 函数式核心、命令式外壳 — 用纯函数处理决策，用精简的 IO 外壳处理副作用
2. 防腐层 — 在集成边界转换外部模型
3. 绞杀者模式 — 渐进式迁移，绝不进行大爆炸式重写
4. Mikado 方法 — 用于大型重构：尝试、记录失败、还原，然后自底向上推进
5. 组合根 — 在一个入口点完成所有装配，不要将其散落在各模块中

模块边界（references/module-boundaries.md）

1. 按功能而非按层组织包 — 垂直切片可让功能变更局限在局部
2. 无环依赖 — 模块图必须是有向无环图（DAG）
3. 共同闭包原则 — 按变更原因分组，而非按技术相似性分组
4. 接口隔离 — 不要强迫使用者依赖未使用的导出项
5. 不变式保障 — 模块负责维护自身的不变式；公开操作，而非 setter
6. 错误边界转换 — 每个模块都将错误转换为自身领域的术语

战术手段（references/tactical-moves.md）

1. 将删除作为重构 — 最好的重构往往会减少代码行数
2. 三次规则 — 等出现三个实例后再进行抽象
3. 先内联，再重新提取 — 先展平混乱的代码，再清晰地重新分解
4. 扩展-收缩 — 对于共享接口：新增接口并保留旧接口，完成迁移后再移除旧接口
5. 禁止布尔参数 — 拆分参数，或改用枚举
6. 将配置作为显式依赖 — 传入配置，不要全局导入
7. 先编写特征测试 — 重构前固定现有行为
8. 与康威定律保持一致 — 模块边界应与团队边界相符
9. 检查是否过度模块化 — 边界必须提升变更隔离性，而不只是整理文件
10. 模块文档模板 — 每个模块都应说明：职责、所有权、依赖、不变式、错误模型

Rust 特定说明（references/rust-specific.md）

重构 Rust 代码库时阅读。内容涵盖：可见性作为架构手段、公共 API 表面控制、crate 与模块边界、Cargo features、工作区 feature 统一，以及依赖策略工具。

Swift/macOS 特定说明（references/swift-macos-specific.md）

在 macOS 上重构 Swift 代码库时阅读。内容涵盖：访问控制作为架构手段（package 修饰符）、显式导入可见性（SE-0409）、target/framework 边界选择、宏隔离，以及 API 治理工具。

执行后反思

此技能执行完毕后，关闭前请检查：

1. 命令是否成功？ — 如果没有，修复导致失败的指令或错误表。
2. 参数或输出是否发生变化？ — 如果底层工具的接口发生偏移，请更新 Usage 示例和 Parameters 表以保持一致。
3. 是否需要变通方案？ — 如果你不得不临时调整（更换标志、增加步骤），请更新此 SKILL.md，以便下次调用时无需采用相同的变通方案。

只有问题确实存在且可复现时才进行更新，不要基于猜测更新。