用途
该技能用于在代码库中识别架构摩擦,并提出“加深”型重构候选:把接口复杂度接近实现复杂度的浅模块,重构为在较小接口后隐藏大量行为的深模块。目标包括可测试性,以及在 AI 代理参与维护时提升上下文经济性与影响范围可控性。
主要能力
- 在指定目标($ARGUMENTS)或整个代码库中探索架构摩擦,不依赖固定检查清单。
- 以领域模型词汇命名接缝,并读取 CONTEXT.md 与 docs/adr/ 中的架构决策记录,避免重复讨论已有决定。
- 对疑似浅模块应用“删除测试”:若删除会把复杂度集中到调用方,则作为候选提出。
- 输出候选卡:标题、涉及文件、问题、解决方案、依赖类别(in-process、local-substitutable、ports-and-adapters、mock)、收益(locality、leverage)、推荐强度,以及可选的 ADR 冲突提示。
- 将探索报告写入 .start/architecture-reviews/architecture-review-<timestamp>.md,包含前后对比 Mermaid 图与 Top recommendation。
- 用户选定候选后进入设计对话,按依赖类别选择测试策略,并就地更新 CONTEXT.md 或新建 ADR。
- 在接口达成一致后,交接给 refactor 技能执行(在测试保护下),大型改动可交接给 implement 技能,并可选择写入 docs/patterns/。
使用方式
以目标参数调用该技能;它会先读取参考材料与领域文档,再委派探索型代理进行代码库漫步,生成报告并询问用户希望探索哪个候选。之后通过挑战循环与用户共同设计深模块接口、接缝与适配器,并处理领域词汇与 ADR 副作用。该技能只负责设计,不直接执行重构;也不提议行为变更或功能开发。
适用场景
- 代码库中理解一个概念需要在多个小模块间来回跳转。
- 模块接口几乎和实现一样复杂,测试困难或未被测试覆盖。
- 单一功能分散在多个层(handler、service、持久化)中,希望收敛为一个深接口的特性模块。
- 希望为 AI 代理维护优化上下文经济性与局部性。
限制
- 不执行重构、不改变行为、不做功能开发。
- 仅在至少两个适配器存在时才论证接缝;单一适配器视为间接层而非接缝。
- 探索报告只写入 .start/architecture-reviews/,不写入 docs/ 或源码目录;只有达成一致的加深才可进入 docs/patterns/。
- 不在用户选定候选前提议接口;不提出 ADR 禁止的重构,除非摩擦确实值得重开 ADR。
- 描述候选时须使用词汇表中的术语,而非用 component、service、boundary 或 API 替代。
- 具体定价、平台支持等信息暂未提供。