SuperAPI AI 工具集

improve-codebase-architecture

编程与开发

查看项目

更新于 10-16 09:15

技能介绍

改进代码库架构(improve-codebase-architecture)是一个面向 AI 编程助手的技能,用于发现并放大代码库中的架构改进机会。其核心目标是暴露 architectural friction(架构摩擦),并提出 deepening opportunities(深化机会)——即把 shallow modules(浅模块)重构为 deep modules(深模块)。这一工作的目标在于提升 testability(可测试性)与 AI-navigability(AI 可导航性)。

用途与定位

该技能不直接修改代码,而是先扫描、分析并呈现候选项,再由用户选择要深入探索的方向。它适用于希望改善代码结构、减少模块间跳转成本、提升测试覆盖与可维护性的项目。

术语与依据

该命令由项目的 domain model 提供信息,并建立在共享 design vocabulary 之上。它会调用 codebase-design 技能获取架构词汇(module、interface、depth、seam、adapter、leverage、locality)及其原则(deletion test、“the interface is the test surface”、“one adapter = hypothetical seam, two = real”)。每条建议都会准确使用这些术语,而不会漂移到 “component”、“service”、“API” 或 “boundary” 等词。GLOSSARY.md 中的 domain language 用于为好的 seams 命名;docs/adr/ 中的 ADRs 记录该命令不应重新争论的 decisions。

流程

一、探索

扫描范围先划定,遵循 YAGNI 原则。由于深化 module 的收益在于让未来修改更容易,因此更关注最近仍在变化的 codebase 区域。开始探索前先决定去哪里看:如果用户点名了方向(module、subsystem 或 pain point),就按该方向探索;否则,向前回看一段足够长的 commit history(git log --oneline),找出反复出现的 files 和 areas,让这些 hot spots 成为首要关注点。如果变更分散、没有明显 hot spot,再扩大范围。随后先读取项目 domain glossary(GLOSSARY.md)以及将触碰区域的 ADRs。

然后 spawn 一个 sub-agent 来遍历 codebase。不套用死板启发式规则,而是自然探索,并记录感到 friction 的地方,包括:理解一个概念是否需要在许多小 modules 之间来回跳;哪些 modules 是 shallow 的(interface 几乎和 implementation 一样复杂);是否存在为了 testability 抽出的 pure functions,但真正 bugs 藏在它们如何被调用之处(没有 locality);哪些 tightly-coupled modules 泄漏到了 seams 之外;codebase 的哪些部分未测试,或很难通过当前 interface 测试。对任何怀疑 shallow 的东西应用 deletion test:删除它会让复杂度集中,还是只把复杂度移动到别处?“yes, concentrates” 才是需要的 signal。

二、用 HTML 报告呈现候选项

把 self-contained HTML file 写到 OS temp directory,避免任何内容落进 repo。Temp dir 从 $TMPDIR 解析,fallback 到 /tmp(Windows 用 %TEMP%),写到 <tmpdir>/architecture-review-<timestamp>.html,让每次运行都有新文件。为用户打开它:Linux 用 xdg-open <path>,macOS 用 open <path>,Windows 用 start <path>,并告诉用户 absolute path。

Report 使用 Tailwind via CDN 做 layout/styling,用 Mermaid via CDN 做能可靠传达结构的 diagrams。Mermaid 和手写 CSS/SVG visuals 可以混用:关系是 graph-shaped(call graphs、dependencies、sequences)时用 Mermaid;需要 editorial 表达(mass diagrams、cross-sections、collapse animations)时用手写 divs/SVG。每个 candidate 都要有 before/after visualisation。

每个 candidate 渲染一张 card,包含:Files(涉及哪些 files/modules)、Problem(当前 architecture 为什么造成 friction)、Solution(会改变什么,用平实的语言描述)、Benefits(用 locality 与 leverage 解释收益,以及 tests 如何改善)、Before / After diagram(side-by-side,自绘,说明 shallowness 与 deepening)、Recommendation strength(Strong、Worth exploring、Speculative 之一,渲染为 badge)。Report 末尾包含首选推荐区:你会先处理哪个 candidate,以及为什么。

用 GLOSSARY.md vocabulary 表达 domain,用 /codebase-design vocabulary 表达 architecture。如果 GLOSSARY.md 定义了 “Order”,就说 “Order intake module”,不要说 “FooBarHandler”,也不要说 “Order service”。

关于 ADR conflicts:如果 candidate 与现有 ADR 冲突,只有在 friction 真实到值得重新打开 ADR 时才提出。Card 中明确标记(例如 warning callout:“contradicts ADR-0007 - but worth reopening because...”)。不要列出 ADR 理论上禁止的每个 refactor。

完整 HTML scaffold、diagram patterns 和 styling guidance 见 HTML-REPORT.md。此时不要提出 interfaces。写完文件后问用户:“Which of these would you like to explore?”

三、Grilling 循环

用户选中 candidate 后,调用 Skill 工具并指定 grilling,与用户走完 decision tree:constraints、dependencies、deepened module 的形状、seam 后面放什么、哪些 tests 能保留。

Side effects 随 decisions 成形而内联发生;调用 Skill 工具并指定 domain-modeling,让 domain model 保持最新:要用 GLOSSARY.md 中不存在的概念命名 deepened module 时,把 term 加入 GLOSSARY.md,若文件不存在则按需创建;对话中打磨了 fuzzy term 时,立即更新 GLOSSARY.md;用户以 load-bearing reason 拒绝了 candidate 时,提议写 ADR,表述为:“Want me to record this as an ADR so future architecture reviews don't re-suggest it?”只有当未来 explorer 确实需要该 reason 以避免再次提出同样建议时才提议;跳过临时原因(“not worth it right now”)和显而易见原因;想探索 deepened module 的 alternative interfaces 时,调用 Skill 工具并指定 codebase-design,并使用其中的 design-it-twice parallel sub-agent pattern。

适用场景与限制

该技能适用于需要系统性发现架构改进点的代码库,尤其是近期仍在演进的区域。它依赖 GLOSSARY.md 与 docs/adr/ 等既有资料,若这些文件不存在,部分步骤会按需创建或受限。报告写入系统临时目录,不会落入 repo。关于具体支持的平台、版本或收费信息,资料中暂未提供。