improve-codebase-architecture — 代码库架构深化审查技能

技能概述

improve-codebase-architecture 扫描你的代码库，找出值得深化的架构改造机会，输出一份带前后对比图的 HTML 评审报告，然后陪你逐条推演你选中的那一个——整个过程不改动任何一行代码。

适用场景

1. 日常结构维护：每隔几天或趁有空时跑一次，在两次功能开发之间阻止代码结构悄悄腐化。它默认会先看近期提交记录，把注意力放在正在频繁变动的路径上，而不是没人碰的角落。
2. 大功能开发之前：把即将要做的 spec 指给它，问一句"怎么让这次改动变简单"。这是这个技能最有效的用法——先腾出结构空间，再开始写功能。
3. 遗留项目摸底与补接缝：面对一个庞大、结构混乱或"氛围编程"堆出来的仓库，用它摸清代码实际长什么样；也可以先用它找出缺失的接缝，再动手给不可测的老代码写测试。

补充一句边界：它一次只处理一个候选。报告里可能有十几个候选，选一个进入推演，剩下的转成独立工单另开会话处理。

核心功能

1. 深化机会扫描：围绕"深度"这一个判断标准去找问题——深模块把大量行为藏在又小又稳的接口后面，浅模块的接口几乎和底下的实现一样宽，等于没藏。报告专门追三种浅：只为可测性抽出来的纯函数（真正的 bug 藏在调用方式里，没有局部性）、模块从接缝处泄漏、以及不打开五个文件就读不懂的概念。
2. 候选卡片式 HTML 报告：每个候选渲染成一张卡片，包含涉及的文件、摩擦点、大白话描述的解法、用局部性和杠杆效应表述的收益、一张手绘的前后对比图，以及一个强度徽章——Strong（删除测试明确通过，值得认真对待）、Worth exploring（方向合理，但收益取决于代码接下来往哪走）、Speculative（为了完整性列出来，多半可以忽略）。报告以一段"首要推荐"收尾。报告写到系统临时目录，不会污染仓库。
3. 删除测试与候选筛选：每个候选都必须过删除测试——删掉这个模块，是把复杂度收拢到一个更小的接口后面，还是只是把它摊到各个调用方身上？只有"收拢"的那种才有资格进报告。这道过滤器是它不沦为泛泛清理建议的原因。
4. 选中后的推演环节：你挑定一个候选后，它会围绕约束、接缝背后放什么、哪些测试能活下来、深化后的接口该长什么样，跟你走一遍决策树。产物是一个决策，不是一份 diff。它还会顺手把新出现的领域术语补进 CONTEXT.md（文件不存在就创建），并主动提出把被否决的候选记成 ADR，免得下次运行又提一遍同样的建议。

它读取 CONTEXT.md 和 docs/adr/ 里的架构决策，用你项目自己的名词说话——候选会写成"深化订单接入模块"，而不是"重构 FooBarHandler"。

常见问题

它会直接改我的代码吗？

不会。整个过程只产出一个临时目录里的 HTML 文件，加上一段对话。重构本身要等之后另开会话，走正常的开发流程（决策 → to-spec → to-tickets → 实现）。这正是它算"勘察"而不是"重构工具"的原因，也是它值得在一个你还没准备好动手的代码库上先跑一遍的理由。

报告打开是一堆没样式的原始 HTML，图表也不见了？

报告从 CDN 加载 Tailwind 和 Mermaid，所以打开时需要联网，被拦截时会静默失败。已归档的一个案例是安全钩子要求 SRI 哈希：agent 加上了哈希，但 CDN 发给浏览器的字节和用来算哈希的 curl 拿到的字节不一致，浏览器就拦掉了脚本。离线和受限环境会撞上同一堵墙。而且 agent 看不见这个现象——它从不渲染页面。绕开办法是让它别用 CDN 脚手架，改成内联 CSS 加手搓 SVG 图表。

它一口气给了十二个候选，我要在同一个会话里全部处理吗？

一个会话只处理一个候选。在一个对话里连做几个，会把报告、推演、领域模型改动和代码改动一起灌进上下文窗口。报告只活在临时文件里，所以要带走的是候选本身而不是那个文件：挑一个、推演它、把决策送进 /to-spec，其余转成可以日后独立拾起的工单。想要的是改进方案时，进 spec 比直接进实现更稳妥。

怎么让它别一直追问，只出报告就行？

在调用时直接说明就行，比如"别追问我，只给我报告"。这是这个技能被抱怨最多的地方——有用户本来欣赏它"能方便地拿到一份透彻的改进分析"，加了推演环节之后觉得"几乎没法用"，并提到有些会话里它只提出一个方案却问了"几十上百个问题"。设计意图是先出报告、只在你选中的候选上才开始推演，但较弱的模型会跳过报告、直接拿它想到的第一个点子来审问你。这个问题尚未关闭：技能目前还没有一个成文的免推演模式。

它和 /codebase-design 有什么区别？

/codebase-design 是一份参考，不是会话驱动者。它提供词汇表（模块、接口、深度、接缝、适配器、杠杆、局部性），这个技能借用它。把一个新 agent 指向 /codebase-design 让它"去执行"，是已知的失败模式：那个技能没有自己的流程可循，agent 会自己发明一套，重新翻一遍代码，跑很久才来问你第一句话。用它来驱动，把 codebase-design 当字典查。

在大型遗留代码库上效果怎么样？

部分有效。它在缺乏统一结构的大型存量代码库上表现不错，也是任何一次性结构治理之后推荐的日常维护手段。但要如实说明另一面：有用户反馈在真正失控的项目上它"帮了一点，但还是不够看"，也有维护了八年遗留系统的开发者反馈，同一个技能在整洁仓库上能画出干净的图，在他那儿却一直绕圈。目前还没有专门的 /refactor 技能覆盖这种场景。如果代码库连一套共享词汇都没有，先用 grill-with-docs 建立词汇，再跑这个技能，输出会好很多。

怎么提示它效果最好？

带着"接下来要建什么"去提示。有大功能要上时，把 spec 指给它，问"怎么让这次改动变简单"。不带方向的运行会自己去扫热点，日常维护够用，但只有点明方向，报告才会变得可落地。

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

很少，而且你最好提前知道这一点。这个技能的构造目的就是产出发现，框架本身会推着它给出候选，而不是得出"没毛病"的结论。强度徽章就是防线：一份全是 Speculative 的报告，就是它在用它唯一会的方式告诉你它没找到什么。