SuperAPI AI 工具集

improve-codebase-architecture

编程与开发

查看项目

更新于 10-16 04:06

技能介绍

用途

该技能用于在代码库中发现“架构加深机会”(deepening opportunities),即把浅模块重构为深模块,最终目的是提升可测试性和 AI 可导航性。它由项目的领域模型提供信息:领域语言为好的接缝命名,ADR 记录该技能不应重新争辩的决策。

术语约定

技能要求在每条建议中严格使用下列术语,避免漂移到“component”“service”“API”或“boundary”。完整定义见 LANGUAGE.md。

  • Module — 任何具有接口和实现的东西(函数、类、包、切片)。
  • Interface — 调用方使用该模块必须知道的全部内容:类型、不变量、错误模式、顺序、配置。不仅是类型签名。
  • Implementation — 内部的代码。
  • Depth — 接口处的杠杆:小接口背后承载大量行为。深 = 高杠杆。浅 = 接口几乎和实现一样复杂。
  • Seam — 接口所在之处;一处无需就地编辑即可改变行为的位置(使用此词,而非“boundary”)。
  • Adapter — 在接缝处满足接口的具体事物。
  • Leverage — 调用方从深度中获得的收益。
  • Locality — 维护者从深度中获得的收益:变更、缺陷、知识集中在一处。

关键原则

  • 删除测试:设想删除该模块。如果复杂度消失,它只是直通模块;如果复杂度在 N 个调用方之间重新出现,则它确实有价值。
  • 接口即测试面。
  • 一个适配器 = 假设的接缝;两个适配器 = 真实的接缝。

使用方式(三步流程)

1. 探索

先阅读项目的领域词汇表以及你正在触及区域的任何 ADR。然后使用 Agent 工具(subagent_type=Explore)遍历代码库。不要遵循僵硬启发式,应有机地探索并记录你感受到摩擦的地方:

  • 理解一个概念需要在许多小模块之间来回跳转的地方?
  • 模块较浅、接口几乎和实现一样复杂的地方?
  • 仅为可测试性而抽取纯函数,但真正的缺陷隐藏在它们被调用的方式中(缺乏 locality)的地方?
  • 紧耦合模块跨越接缝泄漏的地方?
  • 代码库中未测试、或通过当前接口难以测试的部分?

对任何怀疑是浅模块的对象应用删除测试:删除它会更集中复杂度,还是只是转移复杂度?“是的,会集中”是你想要的信号。

2. 呈现候选

呈现一个编号列表的加深机会。对每个候选说明:

  • Files — 涉及哪些文件/模块
  • Problem — 当前架构为何造成摩擦
  • Solution — 将会发生什么变化的白话描述
  • Benefits — 以 locality 和 leverage 解释,并说明测试将如何改进

领域部分使用 CONTEXT.md 的词汇,架构部分使用 LANGUAGE.md 的词汇。如果 CONTEXT.md 定义了 “Order”,就谈“the Order intake module”,而不是“the FooBarHandler”,也不是“the Order service”。

ADR 冲突:如果某候选与现有 ADR 矛盾,仅当摩擦足够真实、值得重新审视该 ADR 时才呈现它,并清楚标记(例如“contradicts ADR-0007 — but worth reopening because…”)。不要列出 ADR 禁止的每一个理论性重构。

此时不要提出接口。询问用户:“Which of these would you like to explore?”

3. 深入讨论循环(grilling loop)

一旦用户选定一个候选,进入深入讨论。与用户一起遍历设计树——约束、依赖、加深后模块的形态、接缝背后是什么、哪些测试能保留。

副作用随决策确定就地发生:

  • 以 CONTEXT.md 中不存在的概念命名加深后的模块?将该术语添加到 CONTEXT.md——与 /grill-with-docs 相同的纪律(见 CONTEXT-FORMAT.md)。若文件不存在则惰性创建。
  • 对话中澄清了一个模糊术语?就在那里更新 CONTEXT.md。
  • 用户以承重理由拒绝该候选?提议一条 ADR,表述为:“Want me to record this as an ADR so future architecture reviews don't re-suggest it?” 仅当该理由确实是未来探索者避免重新提出同一建议所需要的,才提议;跳过瞬时的理由(“现在还不太值得”)和不言自明的理由。见 ADR-FORMAT.md。
  • 想为加深后的模块探索替代接口?见 INTERFACE-DESIGN.md。

适用场景

适用于用户希望改进代码库架构、发现可重构的浅模块、提升代码可测试性或 AI 可导航性的情况。也适用于伴随领域术语和 ADR 维护的架构梳理工作。

限制

  • 具体参数、配置项、安装方式等暂未提供。
  • 该技能依赖 CONTEXT.md、LANGUAGE.md、ADR-FORMAT.md、CONTEXT-FORMAT.md、INTERFACE-DESIGN.md 等项目内文件,缺失时相关行为按文档所述惰性创建或参考。
  • 收费方式、价格、平台支持情况暂未提供。