用途
deep-module-refactor 用于探索代码库、发现架构改进机会,核心目标是让代码库更可测试,手段是“加深浅模块”(deepening shallow modules)。它把探索过程交给 AI 自然进行,而不是套用僵化的启发式规则,并最终把重构建议整理成 GitHub issue 形式的 RFC。
核心理念
该技能引用 John Ousterhout《A Philosophy of Software Design》中的“深模块”概念:深模块拥有较小的接口,却隐藏着较大的实现。深模块更可测试、更易被 AI 导航,并且允许在边界处测试,而不是深入内部测试。
主要能力与流程
-
探索代码库:使用 Agent 工具、subagent_type=Explore 自然导航代码库,不遵循僵化启发式,而是有机探索并记录摩擦点。摩擦点本身就是信号,包括:理解一个概念是否需要在许多小文件之间来回跳转;模块是否浅到接口几乎与实现一样复杂;是否仅为可测试性抽取了纯函数,而真正的缺陷却隐藏在调用方式中;紧耦合模块是否在接缝处造成集成风险;代码库哪些部分未被测试或难以测试。
-
呈现候选:给出编号的加深机会列表。每个候选展示:涉及的模块/概念集群;它们为何耦合(共享类型、调用模式、概念共同归属);依赖类别(见 REFERENCE.md 中的四类);测试影响(哪些现有测试会被边界测试取代)。此阶段不提出接口,而是询问用户:“你想探索其中哪一个?”
-
用户选择候选。
-
框定问题空间:在启动子代理之前,为所选候选写一份面向用户的问题空间说明,包括:任何新接口需要满足的约束;它需要依赖的依赖项;一份粗略的示意性代码草图,使约束具体化——这不是提案,只是让约束落地的方式。向用户展示后立即进入第 5 步,用户阅读思考的同时子代理并行工作。
-
设计多个接口:使用 Agent 工具并行启动 3 个以上子代理,每个都必须为加深后的模块产出截然不同的接口。每个子代理收到独立的技术简报(文件路径、耦合细节、依赖类别、被隐藏的内容),该简报独立于第 4 步面向用户的说明。给每个代理不同的设计约束:
- Agent 1:“最小化接口——最多 1-3 个入口点”
- Agent 2:“最大化灵活性——支持多种用例和扩展”
- Agent 3:“为最常见调用者优化——让默认情况变得简单”
- Agent 4(如适用):“围绕端口与适配器模式设计跨边界依赖”
每个子代理输出:接口签名(类型、方法、参数);展示调用者如何使用它的用法示例;它在内部隐藏的复杂度;依赖策略(如何处理依赖,见 REFERENCE.md);权衡。随后依次呈现设计,再用文字进行比较。比较后给出自己的推荐:哪个设计最强及原因。如果不同设计的元素能很好结合,提出混合方案。要有主见——用户想要的是强有力的判断,而不只是一份菜单。
-
用户选择接口(或接受推荐)。
-
创建 GitHub issue:使用 gh issue create 创建重构 RFC 的 GitHub issue,模板见 REFERENCE.md。不要在创建前要求用户审阅——直接创建并分享 URL。
适用场景
适用于希望改善代码库架构、提升可测试性、并借助 AI 探索重构机会的开发者。尤其适合存在大量浅模块、概念分散在多个小文件、紧耦合接缝风险高、或测试难以覆盖边界的代码库。
限制
资料未提供该技能的具体安装命令、支持的平台、收费或价格信息,这些内容暂未提供。