SuperAPI AI 工具集

improve-codebase-architecture

编程与开发

查看项目

更新于 11-15 16:06

技能介绍

用途

该技能用于发现代码库中的架构摩擦点,并提出“深化机会”(deepening opportunities):把浅模块(接口复杂度几乎等同实现复杂度)重构为深模块(用小接口承载大量行为),目标是提升可测试性与 AI 可导航性。该技能适合在用户希望改进代码架构时使用。

主要能力

  • 依据项目领域模型工作:领域语言为好的接缝(seam)提供命名,ADR 记录该技能不应反复推翻的决策。
  • 使用统一架构术语给出建议:Module(模块,具有接口与实现的任何事物)、Interface(调用者使用模块所需了解的一切,不仅是类型签名)、Implementation(内部代码)、Depth(接口杠杆)、Seam(接缝,接口所在之处)、Adapter(在接缝处满足接口的具体实现)、Leverage(调用者从深度中获得的收益)、Locality(维护者从深度中获得的收益,即变更、缺陷和知识集中于一处)。
  • 关键原则包括:删除测试(想象删除该模块,若复杂度消失则是传递层,若复杂度在 N 个调用者处重新出现则值得保留);接口即测试面;一个适配器是假设性接缝,两个适配器才是真实接缝。

使用方式

  1. 探索:先阅读项目领域术语表、ADR 以及相关 docs/specs/ 文件,再使用 Agent 工具(subagent_type=Explore)有机地遍历代码库,记录摩擦点:理解一个概念是否需要在多个小模块间来回跳转;哪些模块浅;哪些纯函数仅为可测性而抽取、真实缺陷却藏在调用方式中;哪些紧耦合模块跨越接缝泄漏;哪些部分未被测试或难以通过现有接口测试。对疑似浅模块应用删除测试。
  2. 呈现候选:输出带编号的深化机会清单,每项包含 Files(涉及文件/模块)、Problem(当前架构为何造成摩擦)、Solution(以平实语言描述将发生的变化)、Benefits(从 locality、leverage 及测试改善角度说明)。使用 CONTEXT.md 的领域词汇和 LANGUAGE.md 的架构词汇。若候选与现有 ADR 冲突,仅当摩擦足够真实、值得重新审视时明确标注(如“与 ADR-0007 冲突——但值得重新开启,因为……”)。此阶段不提出具体接口,而是询问用户想深入探索哪一个。
  3. 讨论循环:用户选定候选后,围绕约束、依赖、深化模块的形态、接缝背后有什么、哪些测试能保留展开对话。随决策明确同步产生副作用:若深化模块以 CONTEXT.md 中不存在的概念命名,则把该术语加入 CONTEXT.md(文件不存在时按需创建);对话中澄清了模糊术语也即时更新;用户以有分量的理由拒绝候选时,提议将其记录为 ADR,以免未来架构评审重复提出(仅当该理由确为未来探索者所需时提供);若讨论暴露出代码级陷阱或不变式(如“修改此模块时必须保证 X”),写入 docs/specs/<area>.md,格式为:[条件] → [必须保持的不变式] + [违反后果]。

适用场景

适用于希望改善代码库架构、重构浅模块、提升模块可测试性和 AI 可导航性的开发场景,尤其是项目已有领域术语表和 ADR 的代码库。

限制

该技能不提出具体接口设计,需另行参考 INTERFACE-DESIGN.md;不主动列出 ADR 禁止的所有理论性重构,仅在摩擦真实时提示重新审视 ADR。