/improve-codebase-architecture 技能

它的作用

improve-codebase-architecture 调查代码库寻找 深化机会 ——浅模块（接口几乎和它隐藏的东西一样复杂的）可能变成深模块的地方——把它们写成自包含的 HTML 报告，然后 grills 你穿过你选中的任何一个。

它从不改变代码。整个运行在系统临时目录产出一个 HTML 文件加上一段对话；重构本身稍后在单独的 会话，通过正常的构建流程。这正是它成为调查工具而非重构工具的原因，也是为什么在你还不打算改动的代码库上运行该技能依然值得。

两个过滤器让报告不至于变成泛泛的清理建议。每个候选都必须通过 删除测试 ——移除这个模块会把复杂性集中到更小的接口后面，还是只是把它摊到调用者身上？只有「集中」的情况才配得上卡片。而且除非你指向特定区域，否则它先读最近的提交历史，把扫描偏向正在活跃变化的路径，理由是：对无人触碰的代码做深化，是一次你永远不会兑现的重构。

何时使用

你通过输入 /improve-codebase-architecture ——这个 agent 不会自动调用它。

它坐在构建循环之外——它不是主循环上的一步，而是你定期运行以排队更多改进代码库工作的东西。它的四种使用情境：

它与同类容易混淆之处：

• 设计一个你已经选定的模块，用 codebase-design ——那个是工作台，这个是找到该放什么上去的调查。
• 对于大到一次会话装不下的整个任务，用 wayfinder.
• 「这个具体的东西坏了」，用 diagnosing-bugs。当真正的发现是没有好的接缝来锁定 bug 时，它会回到这里。

前置条件

运行它无需任何前置。它读取 CONTEXT.md 以及 docs/adr/ 如果存在就使用它们，并在存在时用你领域自己的名词说话——候选方案读起来是「深化订单接收模块」，而不是「重构 FooBarHandler」。

它写在两个地方。报告去往 <tmpdir>/architecture-review-<timestamp>.html，在仓库之外。在 追问审视 循环中它会添加或锐化 CONTEXT.md，若文件不存在则创建它，并主动提出把被否决的候选记录为 ADR，以免下次运行再次推荐它。

深度，以及追猎它的报告

技能围绕一个想法运转： depth。深模块把小而稳定的接口背后藏了大量行为。浅模块通过几乎与其下代码等宽的接口泄漏实现。报告是对浅度的猎杀——只为可测试性而抽取的纯函数，而真正的 bug 住在它们的调用方式里（没有 locality），模块跨越它们的 seams，一个不开五个文件就无法理解的概念——以及一个修复它的深化提案。

每个候选方案是一张卡片：涉及的文件、摩擦、通俗易懂的解决方案、以 locality and leverage，一张前后对比图，和一个强度徽章。

报告以 首选推荐 ——它会最先处理的那个——然后技能停下来问你想探索哪个候选。那一刻什么都没有决定，也没有任何代码被移动。

选定一个之后会发生什么

选定候选方案会启动 追问审视 会话讨论它：约束、接缝后面放什么、哪些测试存活、深化后的接口应该长什么样。那个会话的输出是一个决策，不是 diff。从那里起正常流程适用——把决策带进 to-spec，然后 to-tickets，然后 implement.

常见问题

它为了一个想法审问了我一小时，而不是给我看选项。能关掉吗？

可以——调用时说出来（「别审问我，只给我报告」）。这是该技能最响亮的抱怨。一位用户直言：他喜欢它作为「获得改进全面分析的便捷方式」，而在审问循环加入后觉得它「几乎不可用」，报告了它先提出单一方案、然后问「几十个或几百个问题」的会话。设计意图是报告先行，审问只在你选定的候选上开始，但较弱的 models 直接跳到就他们想到的第一个想法审问你。那条线索中的报告因模型差异巨大，而且是一个开放 issue——技能还没有文档化的免审问模式。

报告以无样式原始 HTML 打开，没有图表。发生了什么？

报告从 CDN 加载 Tailwind 和 Mermaid，所以打开时需要网络访问，当有东西拦截这些脚本时会静默失效。被上报的案例是安全 hook 要求 SRI 哈希：智能体添加了它们，CDN 提供给浏览器的字节与提供给 curl 用来计算哈希，而浏览器拦截了脚本。离线与锁定环境也会撞上同一堵墙。智能体看不到这一点，因为它从不渲染页面。变通方案是要求内联 CSS 和手绘 SVG 图表，而不是 CDN 脚手架。这是一个开放 issue，也是一个真实的粗糙之处。

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

一个会话一个候选。在一次对话中处理多个会填满 上下文窗口 连同报告、审问、领域模型修改和代码改动一次全来。报告只活在临时文件中，所以带着候选本身而不是文件：选一个，审问它，把决策带进 /to-spec，并把其余的变成 tickets 你可以稍后独立捡起。把选中的改进放进规格说明，而不是直接进入实现。这是一个反复出现的问题，技能本身没有文档化的工作流。

我该怎么向它提问？

心里想着你接下来要构建的东西。当大型构建即将到来时，把它指向规格说明并问「怎样才能让这个改动变得容易？」没有提示的运行会自行扫描热点，对日常维护没问题，但点名方向才让报告可执行。

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

部分。它擅长缺乏一致结构的大型现有代码库，是任何一次性结构配置之后推荐的维护机制。诚实的反面：真正失控项目的用户报告它「帮了一点忙但似乎还是不够」，一位有八年遗留代码库的开发者报告模型在原地打转，而同样的技能在整洁的仓库上能产出干净的关系图。没有专门的 /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 is 定期维护 ——每几天运行一次，脱离任何链，用来排队工作而不是做工作。它的邻居是 codebase-design，它拥有每个候选方案都要使用的深度与接缝词汇， 追问审视，一旦你选定候选方案，它就遍历决策树，而 domain-modeling，它保持 CONTEXT.md 并在决策尘埃落定时保持 ADR 为最新。它产出的是一份想法，它会在 grill-with-docs or to-spec。想知道哪个技能适合某个情境， ask-matt 是整套技能的路由器。