/improve-codebase-architecture 技能

它做什么

improve-codebase-architecture 在代码库里搜寻深化机会（deepening opportunities）。这些地方是浅模块（shallow module）——一个接口几乎和它所隐藏的东西一样复杂——可以变成一个深度模块（deep module）。它把它们写成一份自包含的 HTML 报告，然后针对你挑中的那一个对你进行质询（grilling）。

它从不改动代码。整次运行产出一场对话，以及你的操作系统临时目录里的一个 HTML 文件。你稍后在一场单独的会话（session）里，通过正常的构建流程来做重构。这使它成为一次勘察，而不是重构工具，所以你可以拿它跑一个你还没准备好动手的代码库。

两个过滤器阻止这份报告变成泛泛的清理建议。第一，每个候选项（candidate）都必须通过删除测试（deletion test）：如果你移除这个模块，它的复杂度会移到一个更小的接口后面，还是会散布到各个调用方？只有前一种情况才会得到一张卡片。第二，除非你把它指向某个特定区域，否则它会先读最近的提交历史，把扫描集中在经常变化的路径上。没人动的代码里的深化，是一笔永远收不回成本的重构。

什么时候用它

你通过输入 /improve-codebase-architecture 来调用它；agent 不会主动去拿它。

它不是主构建循环里的一步。你定期运行它，以便排入更多改进代码库的工作。人们在四种情况下使用它：

情况	怎么用
日常维护	每隔几天跑一次，或者趁你有空的时候跑，这样结构不会在功能之间衰败。
一次大构建之前	把它指向规范文档（spec），问「我们怎么才能让这次改动变容易？」这是对它最有效的提示词。
棕地审计（brownfield audit）	拿它跑一个大型、无结构或者靠氛围编程（vibe coding）写出来的仓库，弄清它现在是什么形状。
遗留代码的测试工作	在对不可测的代码写测试之前，用它找出缺失的接缝（seams）。

它在哪些地方容易和兄弟技能混淆：

要设计一个你已经选好的模块，用 codebase-design。这个技能找出该做哪个模块，而 codebase-design 是你设计它的地方。
对于一场大到装不进单场会话的完整工作，用 wayfinder。
对于「这个具体的东西坏了」，用 diagnosing-bugs。当真正的发现是「没有一个好的接缝可以把 bug 锁住」时，它会把你送回这里。

前提条件

运行它不需要任何前提条件。如果 GLOSSARY.md 或 docs/adr/ 里的 ADR 存在，它会读取它们，并使用你领域自己的名词。于是一个候选项读起来是「深化 Order intake 模块」，而不是「重构 FooBarHandler」。

它往两个地方写东西。报告写到 <tmpdir>/architecture-review-<timestamp>.html，在仓库之外。在质询循环期间，它会在 GLOSSARY.md 里添加或锐化术语，并在该文件不存在时创建它。它还会主动提出把一个被拒绝的候选项记录成 ADR，这样未来的运行不会再建议它。

深度，以及寻找深度的报告

这个技能立足于一个观念：深度（depth）。一个深度模块把大量行为放在一个小而稳定的接口后面。一个浅模块通过一个几乎和底下代码一样宽的接口暴露它的实现。报告寻找三种形式的浅薄：

只为可测试性而抽出来的纯函数，而真正的 bug 出在调用方如何使用它们上（没有局部性（locality））。
跨过自己的接缝泄漏的模块。
不打开五个文件就无法理解的一个概念。

对每一种，它都提出能修复它的深化。

每个候选项是一张卡片，带有涉及的文件、摩擦、一个用大白话写的解决方案、以局部性和**杠杆（leverage）**衡量的收益、一张前后对比图，以及一枚强度徽章（strength badge）。

徽章	对你意味着什么
`Strong`	删除测试明确通过，而且摩擦是真实的。认真对待这些。
`Worth exploring`	看起来可行的深化，但回报取决于代码接下来往哪走。
`Speculative`	为了完整性而收录。这些你可以忽略大部分。

报告以一条首选建议收尾，也就是它最想先做的那一个候选项。然后技能停下，问你想探索哪一个。到那时你什么都还没决定，也没有任何代码发生改动。

选中一个候选项之后会发生什么

当你挑中一个候选项，一场质询会话就围绕它开始。它覆盖约束、接缝后面放什么、哪些测试能活下来，以及深化后的接口应该长什么样。那场会话的输出是一个决定，而不是一个 diff。从这里开始，正常流程适用：把这个决定带进 to-spec，然后是 to-tickets，然后是 implement。

常见问题

它围绕一个想法质询了我一个小时，却没给我看选项。我能关掉这个吗？

能。在调用它的时候说出来（「别质询我，只给我看报告」）。这是关于这个技能最常见的抱怨。有一位用户喜欢它，觉得它是「一种便捷地获得彻底改进分析的方式」，但在质询循环加入之后，觉得它「近乎不可用」。在他们的会话里，它提出单一方案，然后问了「10 个或 100 个问题」。设计意图是先出报告，只有在你选中的候选项上才开始质询。但较弱的模型（model）会直接跳到围绕它们想到的第一个点子做访谈。那个讨论串里的结果因模型而差异很大。这是一个未解决的 issue，而且这个技能还没有一个成文的免质询模式。

报告打开后是没样式的原始 HTML，也没有图。发生了什么？

报告从 CDN 加载 Tailwind 和 Mermaid，所以打开它时需要网络访问。如果有东西挡住了那些脚本，页面就会坏掉，而且没有任何报错。在报告的那个案例里，一个安全 hook 要求 SRI 哈希。agent 加上了它们，但 CDN 提供给浏览器的字节与提供给计算哈希的那次 curl 的字节不同，所以浏览器阻止了脚本。离线和受限的环境有同样的问题。agent 看不到这一点，因为它从不渲染页面。作为变通，要求用内联 CSS 和手工搭的 SVG 图，替代 CDN 那套设置。这是一个未解决的 issue。

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

每个候选项用一场会话。如果你在一场对话里处理好几个，上下文窗口（context window）会同时塞满报告、质询、领域模型的编辑和代码改动。报告只是一个临时文件，所以要把候选项带向前，而不是那个文件。挑一个，质询它，把决定带进 /to-spec。把其余的变成工单（tickets），让你之后可以单独拾起。把选中的改进写进一份规范文档，而不是直接去实现。人们经常问这个，而技能本身没有记录任何针对它的工作流。

我该怎么给它提示词？

用你接下来要构建的东西给它提示词。如果一场大构建即将到来，把它指向规范文档，问「我们怎么才能让这次改动变容易？」一次没有提示词的运行会自己找热点（hot spot）。这对日常维护没问题，但一个方向能让报告变得可行动。

它能在一个大型遗留代码库上工作吗？

部分能。它在缺乏一致结构的大型既有代码库上工作得很好，而且它是任何一次性结构性设置之后推荐的维护工具。但项目失控的用户报告说它「帮了一点忙，但似乎还是不够用」。一位拥有八年历史遗留代码库的开发者报告说模型在原地打转，尽管同一个技能在一个整洁的仓库上产出一张干净的图。针对那种情况，目前还没有专门的 /refactor 技能。如果代码库没有共享词汇，先跑 grill-with-docs 创建一套。这通常会让这个技能的输出好得多。

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

/codebase-design 是一份参考，不是会话驱动者。它提供词汇（module、interface、depth、seam、adapter、leverage、locality），而这个技能使用它。如果你把 /codebase-design 作为任务交给一个全新的 agent，它会以一种已知的方式失败。它没有自己的流程可走，所以 agent 会发明一套，重新探索代码，并且跑很长时间才开始问你任何东西。运行这个技能，让它去使用那一个。

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

很少，所以开始之前要知道这一点。这个技能存在的目的就是输出发现，所以它倾向于产出候选项，而不是得出「没有任何问题」的结论。用强度徽章来校正这一点。如果一份报告里的每个候选项都是 Speculative，那就是这个技能什么都没找到。

它在 Codex 或其他运行环境（harness）里能用吗？

部分能。探索那一步直接点名了 Claude Code 的 Agent 工具，并带上 subagent_type=Explore。没有那个工具的运行环境可能会跳过并行探索，而不是使用它自己的等价物。技能仍然能运行，但扫描没那么彻底。有人提议过一次运行环境中立的改写，但没有合并。

我到底该怎么在 TypeScript 里实现深度模块？

这个技能没有提供一个好答案。人们经常要一份 TYPESCRIPT.md，为这些原则给出具体的文件与模块布局，而它并不存在。技能告诉你一次深化该发生在哪里，以及接缝后面放什么。你必须自己把它变成包或目录结构。

它生效的标志

候选项点出你领域的概念，而不是编造的类名：「Order intake 模块」，而不是「FooBarHandler」。
候选项位于你最近编辑过的文件里，而不是仓库里没人动的部分。
运行期间没有代码发生改动。唯一的新文件是你临时目录里的那份 HTML 报告。
它在报告之后停下，问你想选哪个候选项。它不会自己继续。
每张卡片都把回报解释成局部性或杠杆，并说明哪些测试会变简单，而不只是「这样更干净」。
当你出于一个长久的原因拒绝某个候选项时，它主动提出记录一份 ADR，让下一次运行不再建议它。

它在体系中的位置

improve-codebase-architecture 是周期性维护。你每隔几天在任意链条之外运行它，目的是排队工作，而不是完成工作。它的邻居：

codebase-design 拥有每个候选项都会用到的那套深度与接缝词汇。
grilling 在你选定一个候选项之后走一遍决策树。
domain-modeling 在你做出决定的过程中让 GLOSSARY.md 和 ADR 保持最新。

它的输出是一个想法，这个想法从 grill-with-docs 或 to-spec 回到主构建流程。它在主流程末端的对应物是 retro。这个技能改进 agent 工作所在的代码，而 retro 在一次构建之后改进它周围的环境——检查、标准、引导文件（steering file）。至于哪个技能适合某种情况，ask-matt 是覆盖整套技能的路由器（router）。

原文：aihero.dev/skills-improve-codebase-architecture