Module Deepening 是一个用于软件架构决策的技能,其核心目标是发现并规划将浅模块转变为深模块的重构机会,或帮助用户为一个选定的模块确定接口形状与接缝位置。深模块指将大量行为隐藏在小型接口之后,并位于清晰的接缝处,从而让调用方获得杠杆、维护方获得局部性,测试也通过调用方相同的接口进行。该技能旨在提升可测试性和 AI 可导航性:智能体应能通过阅读一个模块来理解并安全地变更一个概念。
使用方式与工作流程: 该技能有两种模式:扫描模式和设计模式。如果用户指定了模块、已选的候选项或接缝问题,进入设计模式;如果用户询问在哪里深化、只给出方向或痛点、或未指定任何内容,进入扫描模式;若意图不明确,则询问一个问题以确定模式。
扫描模式: 先确定范围(YAGNI),若用户给出方向则以该方向为范围,否则在整个仓库中通过 git log(最近 200 条提交的文件名)寻找重复出现的文件或目录作为热点。若不是 git 仓库,则仅扫描用户给出的方向,并记录热点证据不可用。接着阅读领域上下文和 ADR,然后进行只读探索(可利用子代理),寻找理解一个概念需在多个小模块间跳转、接口复杂度接近实现复杂度、纯函数仅为可测试性而抽取导致调用处隐藏真实 bug、模块紧耦合跨越接缝、以及难以通过当前接口测试等问题。对每个疑似浅模块应用删除测试:想象删除它,若复杂度消失则为直通式,若复杂度在多个调用方重现则值得保留。将候选项的依赖分类为进程内、本地可替换、端口与适配器、真正外部,并写入离线 HTML 报告,输出到操作系统临时目录,打开并打印绝对路径。报告中的卡片即选项,顶部推荐即推荐答案,询问用户选择哪个候选项。扫描完成的条件是报告存在、每个卡片包含必需字段、顶部推荐指定一个候选、用户被询问选择。若零候选,也写报告记录范围和每个被检查模块及丢弃原因,然后停止,不要求用户选择。
设计模式: 识别模块并阅读其实现、调用方和测试,用领域语言确认名称。向用户框定问题空间:新接口必须满足的约束、依赖及其分类、以及一个粗略的示意代码草图(标注为草图而非提案)。然后进行“设计两次”,至少产生三种截然不同的接口方案(最小接口、最大灵活性、常见调用方优先、依赖跨越接缝时使用端口与适配器),每种方案包含五部分输出。依次展示并比较各方案在深度、局部性和接缝位置上的优劣。给出有主见的推荐,必要时提出混合方案。通过一次一个问题的交互契约,直到用户同意接口形状和接缝位置,或拒绝深化。设计完成的条件是用户对具体推荐方案做出决定:接受时需说明接口的不变量、错误模式和接缝,测试策略说明哪些现有测试被替换;拒绝时记录原因并检查是否符合 ADR 候选测试,然后结束。没有推荐的三设计不算完成。
交互契约: 两种模式均遵循一次一个问题,每个问题附带选项和推荐答案,等待回答后再问下一个,不批量问卷。按决策树顺序推进:约束、依赖及其类别、深化模块的形状、接缝之后是什么、哪些测试保留。当用户同意决策或拒绝候选时停止,不继续进入计划或实施。即使被要求“直接做”,也不编辑代码,而是交接给其他工具。
决策交接: 领域术语若缺失或模糊,应交给 domain-modeling 包;当用户基于重要理由拒绝候选或选择设计时,若满足不可逆、无上下文时令人惊讶、真实权衡三个条件,则建议记录为 ADR 并交给 adr-writer;实施交接给 codebase-advisor 获取可执行计划,或交给 /tdd 命令以测试先行构建接口。本技能不实施代码修改。
输出: 扫描模式输出报告绝对路径、范围、候选列表(含标题和强度标签)、顶部推荐及理由、询问用户选择的问题。设计模式输出问题框架、每个设计(接口、用法示例、接缝后隐藏内容、依赖策略与适配器、权衡)、比较和推荐,然后逐个提问。最终决策输出包括决策、模块领域名及文件路径、接口、接缝与适配器、测试、交接项,并注明此处不进行代码变更。
错误处理: 非 git 仓库时若有方向则扫描并记录热点证据不可用,否则询问方向;历史太短则扩大窗口,仍无热点则询问方向;无领域上下文时使用代码中的名称,可选提供 domain-modeling;零候选时写零候选报告并停止;临时目录不可写则回退到 /tmp,失败则报错;无浏览器打开器则打印路径并说明未打开;无子代理支持则顺序执行并注明;用户要求重构时拒绝编辑并交接;候选与 ADR 矛盾时仅在摩擦足够大时标记。
限制: 该技能只读,不编辑任何源代码、测试、配置、CONTEXT.md 或 ADR,唯一写入的文件是扫描报告,且写入操作系统临时目录而非仓库。它需要领域上下文和 ADR 信息以正确命名和避免重新争论已决策事项。它不实现代码,所有实施均需交接。它依赖 git 历史发现热点,非 git 环境需用户提供方向。它使用特定词汇(模块、接口、实现、深度、浅、接缝、适配器、杠杆、局部性),避免使用“组件”、“服务”、“API”、“边界”等词。所有事实均来自提供的技能说明,未提及收费、价格、平台要求或具体效果数据,这些信息暂未提供。