SuperAPI AI 工具集

improve-codebase-architecture

前端与建站

查看项目

更新于 10-16 03:10

技能介绍

用途:扫描代码库,找出架构摩擦点并提出"深化"重构机会——把浅模块变为深模块,目标是提升可测试性与 AI 可导航性。该命令依据项目领域模型和一套共享设计词汇工作。

前置与词汇:先运行 /codebase-design 获取架构词汇(module、interface、depth、seam、adapter、leverage、locality)及其原则(deletion test、"interface is the test surface"、"one adapter = hypothetical seam, two = real"),并在每条建议中严格使用这些术语,避免用 component、service、API、boundary。CONTEXT.md 的领域语言给出好的 seam 名称,docs/adr/ 中的 ADR 记录不应被重新争论的决策。

流程:

  1. 探索。先定范围(YAGNI),若用户指定方向则采用,否则用 git log --oneline 回溯提交历史找热点,优先关注近期变更区域;先读 CONTEXT.md 词汇表与相关 ADR。随后派生子代理有机地走查代码,关注:理解一个概念是否需要来回跳转多个小模块;哪些模块浅(接口复杂程度接近实现);为可测试性抽出的纯函数是否掩盖了调用处的真实 bug;紧耦合模块是否跨 seam 泄漏;哪些部分未测试或难以通过当前接口测试。对疑似浅模块应用删除测试:删除它是集中复杂度还是只是移动它?
  2. 以 HTML 报告呈现候选。将自包含 HTML 写入系统临时目录(由 $TMPDIR 解析,回退 /tmp,Windows 为 %TEMP%),文件名为 <tmpdir>/architecture-review-<timestamp>.html,不要落入仓库;用 xdg-open、open、start 打开并告知绝对路径。报告通过 CDN 使用 Tailwind 和 Mermaid,图形式关系用 Mermaid,编辑式视觉用手写 CSS/SVG,每个候选含前后对比图。每张卡片包含:涉及文件、问题、方案、收益(locality 与 leverage、测试改善)、前后对比图、推荐强度徽章(Strong、Worth exploring、Speculative)。结尾给 Top recommendation。使用 CONTEXT.md 领域词汇与 /codebase-design 架构词汇。若候选与 ADR 冲突,仅在摩擦足够真实时呈现并明确标注。此阶段不要提出接口,写完后询问用户选择哪一个。参见 HTML-REPORT.md 获取完整 HTML 脚手架与样式指引。
  3. 提问循环。用户选定后运行 /grilling 走过决策树;决策成形时内联执行副作用:新概念写入 CONTEXT.md(不存在则懒创建)、模糊术语即时更新、用户以关键理由否决时提议记录 ADR(仅当未来探索者确实需要该理由时);若想探索替代接口,运行 /codebase-design 的 design-it-twice 并行子代理模式。

限制:资料未提供支持的编程语言、平台范围、版本要求与具体价格信息。