改进代码库架构

功能概述¶

improve-codebase-architecture 会扫描代码库，寻找加深机会（deepening opportunities）。这些是指浅层模块（接口几乎和它所隐藏的东西一样复杂）可以变成深层模块的地方。它会将这些机会整理成一份自包含的 HTML 报告，然后针对你选中的那个拷问你。

它永远不会改动代码。整个运行过程只会产生一段对话和一个位于你操作系统临时目录中的 HTML 文件。你稍后在单独的会话中，通过常规构建流程进行重构。这使得它成为一种勘察工具，而不是重构工具，因此你可以在一个你还没准备好改动的代码库上运行它。

两个过滤器防止报告沦为泛泛的清理建议。首先，每个候选都必须通过删除测试（deletion test）：如果你移除了这个模块，它的复杂度是会转移到更小的接口后面，还是会扩散到调用方？只有第一种情况才能获得卡片。其次，除非你指定某个具体区域，否则它会先读取最近的提交历史，并将扫描重点放在经常变更的路径上。对无人改动的代码进行加深，是一场永远得不到回报的重构。

何时使用¶

你通过输入 /improve-codebase-architecture 来调用它；代理不会自行使用它。

它不是主构建流程中的一步。你会定期运行它，以便积累更多改进代码库的工作。人们在四种情况下使用它：

它容易与同类技能混淆，具体区别如下：

• 要设计一个你已选定的模块，请使用 codebase-design。本技能负责找出要处理的模块，而 codebase-design 才是进行设计的地方。
• 对于大到无法在一次会话中容纳的整体工作，请使用 wayfinder。
• 对于“这个具体的东西坏了”的情况，请使用 diagnosing-bugs。当真正的发现是没有好的接缝来锁定 bug 时，它会把你送回这里。

前提条件¶

运行它无需任何前提。如果存在 GLOSSARY.md 或 docs/adr/ 中的 ADR，它会读取这些内容，并使用你所在领域自己的术语。这样，候选就会呈现为“加深订单接收模块（Order intake module）”，而不是“重构 FooBarHandler”。

它会在两个位置写入内容。报告会输出到仓库之外的 <tmpdir>/architecture-review-<timestamp>.html。在拷问循环中，它会向 GLOSSARY.md 添加或精炼术语，并在该文件不存在时创建它。它还会提议将被否决的候选记录为 ADR，这样未来的运行就不会再次建议它。

深度，以及探寻深度的报告¶

该技能建立在一个核心理念上：深度（depth）。深层模块将大量行为置于一个小而稳定的接口之后。浅层模块则通过一个几乎与其底层代码一样宽的接口暴露其实现。报告会寻找三种形式的浅层问题：

• 仅为了可测试性而提取的纯函数，而真正的 bug 在于调用方如何使用它们（没有局部性（locality））。
• 跨越自身接缝（seams）泄漏的模块。
• 一个不打开五个文件就无法理解的概念。

针对每一个，它都会提出能够修复该问题的加深方案。

每个候选都是一张卡片，包含所涉及的文件、摩擦点、通俗易懂的解决方案、在局部性和杠杆作用（leverage）方面的收益、一张前后对比图，以及一个强度徽章。

报告以首要建议（Top recommendation）结尾，即它会优先处理的候选。然后技能会停下来，询问你想探索哪个候选。到这一步，你什么都没决定，代码也没有任何改动。

选定一个之后会发生什么¶

当你选定一个候选后，针对它的拷问会话就会开始。它会涵盖约束条件、接缝后面放什么、哪些测试仍然有效，以及加深后的接口应该是什么样。该会话的输出是一个决策，而不是一个 diff。接下来遵循常规流程：将决策带入 to-spec，然后进入 to-tickets，最后进入 implement。

常见问题¶

它围绕一个想法拷问了我一个小时，而不是给我展示选项。我能关掉这个功能吗？

可以。在调用时说明即可（“不要拷问我，只给我看报告”）。这是关于该技能最常见的抱怨。一位用户曾称赞它是“获取改进方案深入分析的便捷方式”，但在加入拷问循环后，觉得它“几乎无法使用”。在他们的会话中，它先提出一个单一方案，然后问了“几十个或数百个问题”。设计意图是先给出报告，并且只在你选定的候选上开始拷问。但较弱的模型会直接跳到针对它们第一个想法的访谈。在该线程中，结果因模型而异。这是一个未解决的问题，该技能目前还没有文档化的无拷问模式。

报告打开时是未应用样式的原始 HTML，也没有图表。发生了什么？

报告从 CDN 加载 Tailwind 和 Mermaid，因此打开时需要网络访问。如果某些东西阻止了这些脚本，页面会直接损坏，且没有错误提示。在报告的案例中，一个安全钩子要求 SRI 哈希。代理添加了它们，但 CDN 向浏览器提供的字节与计算哈希的 curl 不同，因此浏览器阻止了脚本。离线和受限制的环境也有同样的问题。代理看不到这一点，因为它从不渲染页面。作为变通方法，要求使用内联 CSS 和手工构建的 SVG 图表，而不是 CDN 配置。这是一个未解决的问题。

它给了我十二个候选项。我是在同一个会话中逐一处理，还是开始一个新会话？

每个会话只处理一个候选项。如果你在同一个对话中处理多个，上下文窗口 会同时被报告、质询、领域模型编辑和代码变更填满。报告只是一个临时文件，因此要继续传递候选项，而不是文件。选一个，质询它，并把决策带入 /to-spec。把其余的变成 工单，以便之后单独处理。将选定的改进放入规范中，而不是直接进入实现。人们经常问这个问题，而该技能本身没有记录相关的工作流。

我该如何提示它？

用你接下来要构建的东西来提示它。如果即将进行大型构建，让它指向规范并询问“我们怎样才能让这次变更更容易？”没有提示的运行会自行寻找热点。这对于常规维护没问题，但一个方向能让报告可操作。

它适用于大型遗留代码库吗？

部分适用。它在缺乏一致结构的大型现有代码库上表现良好，并且是任何一次性结构设置之后推荐的维护工具。但拥有失控项目的用户报告说它“有点帮助，但似乎还是不够用”。一位拥有八年历史遗留代码库的开发者报告说模型绕圈子，尽管同一技能在整洁的仓库上能生成清晰的图。目前还没有专门用于这种情况的 /refactor 技能。如果代码库没有共享词汇表，先运行 grill-with-docs 来创建一个。这通常会让该技能的输出好得多。

它与 /codebase-design 有什么不同？

/codebase-design 是一个参考，而不是会话驱动器。它提供词汇表（模块、接口、深度、接缝、适配器、杠杆、局部性），而这个技能会使用它。如果你给一个新代理 /codebase-design 作为任务，它会以已知的方式失败。它没有自己的流程可供遵循，因此代理会发明一个流程，再次探索代码，并在问你任何问题之前运行很长时间。运行这个技能，并让它使用那个技能。

它会不会告诉我代码库没问题？

很少，所以开始前要知道这一点。该技能的存在是为了输出发现，因此它倾向于生成候选项，而不是得出没有问题的结论。使用强度徽章来纠正这一点。如果报告中的每个候选项都是 Speculative，说明该技能没有发现任何问题。

它在 Codex 或其他执行框架中有效吗？

部分有效。探索步骤直接指定了 Claude Code 的 Agent 工具，并带有 subagent_type=Explore。没有该工具的 执行框架 可能会跳过并行探索，而不是使用其自身的等价物。该技能仍然会运行，但扫描不够彻底。有人提出了一个不依赖执行框架的重写，但尚未合并。

我实际上如何在 TypeScript 中实现深度模块？

该技能没有附带一个好的答案。人们经常要求有一个 TYPESCRIPT.md，其中包含这些原则的具体文件和模块布局，但它并不存在。该技能会告诉你深化应该放在哪里，以及接缝后面应该放什么。你必须自己将其转化为包或目录结构。

它正在工作的标志¶

• 候选项使用你领域中的概念命名，而不是发明的类名：“订单接收模块”，而不是“FooBarHandler”。
• 候选项位于你最近编辑过的文件中，而不是仓库中没人碰的部分。
• 运行期间没有代码变更。唯一的新文件是临时目录中的 HTML 报告。
• 它在报告后停止，并询问你想要哪个候选项。它不会自行继续。
• 每张卡片都会将收益解释为局部性或杠杆，并说明哪些测试会变得更简单，而不仅仅是“这样更干净”。
• 当你因持久原因拒绝某个候选项时，它会提议记录一个 ADR，以便下次运行时不再建议它。

它的定位¶

improve-codebase-architecture 是周期性维护。你每隔几天运行一次，在任何链条之外，用于排队工作，而不是执行工作。它的邻居：

• codebase-design 拥有每个候选项都使用的深度与接缝词汇表。
• grilling 在你选择候选项后遍历决策树。
• domain-modeling 在你做出决策时保持 GLOSSARY.md 和 ADR 为最新。

它的输出是一个想法，该想法会在 grill-with-docs 或 to-spec 处回到主构建流程中。它在主流程末尾的对应物是 retro。这个技能改进代理所工作的代码，而 retro 在构建之后改进其周围的环境（检查、标准、引导文件）。对于哪种技能适合某种情况，ask-matt 是整个集合的路由器。