SuperAPI AI 工具集

improve-codebase-architecture

编程与开发

查看项目

更新于 10-15 21:39

技能介绍

用途:发现代码库中的架构摩擦,提出“深化”机会——把接口几乎与实现一样复杂的浅模块,重构为接口简洁、实现内聚的深模块,目标指向可测试性与 AI 可导航性。

主要能力:基于项目领域模型与共享设计词汇工作。运行 /codebase-design 获取架构词汇(module、interface、depth、seam、adapter、leverage、locality)及原则(删除测试、“接口即测试面”、“一个适配器是假设缝隙,两个才是真缝隙”)。使用 Agent 工具(subagent_type=Explore)浏览代码库,寻找理解需跨多模块跳转、接口过于暴露、实现迫使进入低层机制、纯函数抽取但缺少局部性、模块跨缝隙泄漏、难测试或未测试等摩擦点。对疑似浅模块应用删除测试。

使用方式:先读 CONTEXT.md 领域词汇表,并尊重 docs/adr/ 中已接受的 ADR。将候选方案写成自包含 HTML 文件放到系统临时目录(由 $TMPDIR、/tmp 或 %TEMP% 解析),文件名为 <tmpdir>/architecture-review-<timestamp>.html,并用 xdg-open、open 或 start 打开,告知绝对路径。报告通过 CDN 使用 Tailwind 和 Mermaid,每个候选卡片包含文件、问题、解决方案、收益(局部性、杠杆、渐进披露、测试改进)、前后对比图与推荐强度徽章(Strong、Worth exploring、Speculative),结尾给 Top recommendation。此阶段不提出接口,而是询问用户想探索哪一个。

后续为打磨循环:用户选定后运行 /grilling 走设计树,涉及约束、依赖、深化模块形态、缝隙后的内容、哪些测试保留。决策清晰时内联运行 /domain-modeling 更新领域模型:新概念加入 CONTEXT.md(文件不存在则惰性创建),模糊词就地更新;用户以承重理由拒绝候选时,可提议记成 ADR 供未来架构评审参考,仅当对后续探索者有用时才提议。用户接受后循环止于设计与文档,本技能不写实现,可交接给 to-issues 跟踪或 tdd 测试先行。想探索替代接口可用 /codebase-design 的 design-it-twice 并行子代理模式。

限制:不负责实现;若候选与已接受的 ADR 冲突,仅当摩擦真实且值得重开时才呈现并明确标注;不列出 ADR 禁止的所有理论重构。