SuperAPI AI 工具集

improve-codebase-architecture

通用与其它

查看项目

更新于 10-16 01:17

技能介绍

用途:在代码库中识别架构摩擦点,提出“深化”重构机会——把接口复杂、实现单薄的浅模块改造为接口小、行为丰富的深模块,目标是提升可测试性与 AI 可导航性。该技能需结合项目领域语言(CONTEXT.md)与已有架构决策记录(docs/adr/)。

主要能力与术语:使用固定词汇描述建议,包括 Module(含接口与实现的函数、类、包等)、Interface(调用者需知道的一切:类型、不变量、错误模式、顺序、配置)、Implementation、Depth(接口杠杆:小接口背后大量行为为深)、Seam(接口所在处,行为无需原地修改即可替换,替代“boundary”)、Adapter、Leverage(调用者从深度获益)、Locality(维护者从深度获益:变更、缺陷、知识集中一处)。关键原则包括删除测试(删除该模块后复杂度消失则为直通,复杂度转移至 N 个调用者则值得保留)、接口即测试面、一个适配器是假设 seam、两个适配器才是真实 seam。

流程:第一步探索,先读领域术语表与相关 ADR,再用 Agent 工具以 subagent_type=Explore 有机遍历代码库,记录摩擦点(理解一个概念需在多个小模块间跳转、接口与实现等复杂、纯函数仅为可测试性而抽取但真正缺陷隐藏在调用处、紧耦合模块跨 seam 泄漏、难以通过当前接口测试的部分),并对疑似浅模块应用删除测试。第二步以编号列表呈现候选,每项含 Files、Problem、Solution、Benefits(用 locality、leverage 及测试改进说明),使用 CONTEXT.md 领域词汇与 LANGUAGE.md 架构词汇;若候选与现有 ADR 冲突,仅在摩擦足够大到值得重审时提出并标注,不列举所有被 ADR 禁止的理论重构;此阶段不提出接口,询问用户选择哪一项探索。第三步进入追问式讨论,围绕约束、依赖、深化模块形态、seam 背后内容、幸存测试展开;副作用即时处理:将新概念加入 CONTEXT.md(必要时惰性创建)、即时锐化模糊术语、当用户以关键理由拒绝候选时提议记录为 ADR(仅限未来探索者需要该理由以免重复建议的情形),可参考 INTERFACE-DESIGN.md 探索替代接口。

适用场景:希望在保留 ADR 决策的前提下改进代码结构、提高模块可测试性与 AI 可理解性的工程团队。

限制:该技能为流程性指导,不自动执行重构;不提出具体接口设计直至用户选定候选;未提供价格、平台支持或效果保证等信息。