refactorkit

refactorkit

对现有代码库进行的架构调查。refactorkit 会读取仓库，分析其变更频率、模块形态和测试，找出哪些地方的结构正在增加成本；然后用两道门槛对候选项排序，最多选出一个，并将其写成一份可供他人讨论的提案。

这是一个单一流程，可以选择限定在某个子树中（/refactorkit src/payments）。它没有任何模式：每次运行时，所有操作都以相同方式进行。

它只提出建议，绝不修改代码

refactorkit 只会写入一个 Markdown 文件，不会触碰任何源代码。 不移动、不重命名、不提取，也不会“顺手做点小整理”。名字里有重构，但这项技能只会说明在哪里以及为什么；具体执行由接手提案的人负责。这个边界正是报告值得信任的全部原因，因为一边调查一边修改，就意味着已经替你做了决定，而你读到的只是事后合理化，不是建议。

这项技能的工具中刻意不包含 Edit。它创建的文件是新文件，因此 Write 就足够了。

何时触发

“我应该在哪里重构”“这个代码库的结构有什么问题”“找出重构机会”“这段代码很难修改”“改进我们的架构”“审查模块边界”“这里的接缝一团糟”“/refactorkit”。

四条边界，每条一句：

• 不是代码审查。 代码审查会检查差异，寻找刚刚完成的工作中的缺陷。refactorkit 会检查代码树，寻找早于差异就已存在的结构问题。“审查我的改动”不属于这项技能的职责。
• 不是文档编写。 描述现有架构是另一项工作；refactorkit 只会描述尚不存在的架构。
• 不是视觉设计。 这里讨论的内容与 UI、样式或设计系统无关，尽管“设计”和“重构”放在一起可能会让人这么以为。
• 不是决策记录。 refactorkit 产出的是提案，不是已批准的决定。如果提案取代了现有的架构决策，它会明确说明，并指向仓库中负责记录决策的机制。

术语

请准确使用这些术语；它们能避免调查结果沦为泛泛的异味清单。

• 模块。 任何有内部和外部之分的东西：文件、类、包、服务。它不是一种语言结构，而是一个边界。
• 接口。 调用方必须了解的、正确使用模块所需的一切。不只是签名：还包括顺序约束、必需配置、副作用、错误约定，以及无人记录的不变量。接口几乎总是比看起来更庞大。
• 深度。 模块隐藏的行为量，相对于它要求调用方了解的接口内容。深模块用小接口隐藏大量工作。浅模块无论哪种方式，成本都差不多。
• 接缝。 系统可以在不撕裂的情况下拆分之处：一侧可以被替换、伪造或单独测试，而不影响另一侧。
• 适配器。 唯一职责是在另外两个模块之间调整数据形式的模块。适配器本身没有问题；但一组适配器可能表明两侧对数据形态的理解并不一致。
• 局部性。 一项概念性改动有多少内容落在同一个地方。局部性好，意味着功能改动只涉及少数文件；局部性差，则意味着改动会扩散到更多地方。
• 杠杆效应。 一项修复能让多少未来改动变得更省力。若多个候选项同样可靠，它就是决定取舍的因素。

全程使用项目自己的领域术语。 如果代码库使用 ledger、tenant、shipment 这些词，提案里也要使用这些词。退回到泛泛的“组件”“服务”“API”或“层”，是发现仅靠模式匹配而非实际阅读得出的最明显信号；这也会让架构建议听起来似乎合理，却空洞无物。

四种摩擦模式

一个封闭集合。refactorkit 只查找这四种模式，不查找其他任何内容。封闭性至关重要：无休止地搜寻“问题”，在每个代码库中都会生成同一份泛泛的清单，而这正是此技能旨在取代的输出。这四种模式都归结为深度，因为它们各自体现了一种情况：接口的成本高于其背后的行为。

模式	含义	要查找的形态	由谁发现
浅层接口	学习接口所花的成本，与阅读实现所花的成本相差无几	一个单元，其成员各自只转发到另一个单元的一个成员	子 Agent
适配器泛滥	仅用于在另外两个单元之间转换数据的模块；要指出的问题是两端的数据形态不一致，而绝不是“删除适配器”	一组只负责转换的单元聚集在同一个边界上，向两个方向进行转换	子 Agent
未测试的耦合	只有搭建协作者才能测试的行为	测试中构造的协作者多于作出断言的对象；或一个未测试单元的所有邻近单元都已测试	子 Agent
局部性差	一项概念上的更改会扩散到许多文件	不同目录中的文件反复在同一批提交中一同更改	主会话

信号是形态。 无论代码如何命名，都要匹配表中的结构，因为不同语言社区的命名惯例各异，而形态不会变。先推导出代码库自身的惯例（下文读取的护栏通常会告诉你这些），再按上述结构查找，不必拘泥于此代码库恰好采用的名称。

两道关卡

每个候选项在列出之前都必须通过这两道关卡。未通过任意一道的候选项都会被静默丢弃：既不会作为较弱的发现出现，也不会附带保留说明出现。

删除测试。 如果删除此模块，并让调用方吸收它的功能，复杂度会在应有的位置集中，还是只会转移？集中才是收益。转移只是披着重构外衣的折腾；将其打印出来只会让报告变长，最终无人阅读。用一句证据说明结论：哪些调用方会吸收哪些功能，以及为什么这样做会或不会是更合适的归属位置。

将接口作为测试面。 更改后，能否仅通过新接口测试该行为，而不触及其内部？如果不能，说明切入点放错了：该候选项是未完成的，尚未准备就绪。这道关卡能阻止仅仅移动边界的提案冒充改进提案。

每个列出的候选项都必须在终端输出和文件中注明两道关卡的结论。未注明关卡结论的候选项不是较弱的候选项，而是缺乏证据的候选项。

强度等级

应根据此表为每个通过筛选的候选项评级，而不是凭感觉判断；未定义的徽标只是披着标签外衣的主观印象，而强度是读者最信任、无需核实的一列。

强度	所需条件	排名方式
strong	通过两道关卡，文件位于变更频率最高的一小部分中，并且以实际文件名指出了影响范围	可列为优先项
moderate	通过两道关卡，但代码很少变动或影响范围很广	仅当没有 strong 项时才可列为优先项
weak	通过关卡，但收益仅体现在风格上，不会改变调用方必须了解的内容	可以列出，绝不列为优先项

流程

1. 先阅读护栏

在查看任何代码之前，先了解仓库已经做出的决定：

• 仓库根目录中的上下文或术语表文件（通常是 CONTEXT.md），了解通用语言；项目自己的领域术语源自此处，命名惯例通常也会在此体现；
• docs/adr/（或此仓库存放架构决策记录的目录），了解已经做出的决定。

如果提案要推翻已接受的决策记录，必须注明其编号，并引导至一份取代该记录的新记录，而不是悄悄重新建议已被否决的设计。推翻决策是合理的；没意识到自己在推翻决策则不合理。

这两个文件都不存在很常见。静默降级，不要发出警告或添加说明。

2. 先按变更频率排序，再分组

git log --format= --name-only --since=<a year or so> 一次就能提供 refactorkit 所需的两类信号，而且除了 git 之外不需要其他工具：每个文件的变更频率（变更频率排名），以及哪些文件总是一起变更（这些共同变更对会成为局部性差的发现依据）。

先按变更次数排列文件，再将高频变更文件按目录、功能或仓库实际存在的边界，划分为 3–5 个连贯的区域。如果用户给出了范围参数，就遵守该范围：范围会缩小扫描的目录树，但不会改变方法。

没有 git 历史，即浅克隆或根本不是 git 仓库时，就无法进行排名。改为按结构扫描，并明确说明已跳过优先级排序，避免有人将覆盖范围说明误解为其他含义。

3. 分头执行，每个区域分配一个 Agent

每个区域派遣一个子 Agent。每个子 Agent 都要在自己的范围内应用 四种摩擦模式中的三种代码阅读模式，独立运行两道门槛，并返回候选记录列表，或明确说明结果为空；空结果完全可以接受。

给所有 Agent 相同的固定返回格式，因为主会话必须对自己未收集的发现进行排序。自由形式的说明无法直接排序，若不重新阅读 Agent 阅读过的所有内容，就无法完成排序；这会让分头执行失去意义：

字段	内容
pattern	三种代码阅读模式之一
files	涉及的路径
shape	拟议的结构，一行说明
deletion_test	结论加一句证据
test_surface	结论加一句证据
blast_radius	触及的文件、变更的调用方
strength	参照强度等级

**局部性差的发现应留在主会话中。**它源自手头已有的共同变更对，不需要读取任何文件；而且，单个区域的 Agent 从结构上就无法看到分属不同区域、却会一起变更的文件。把这项任务交给区域 Agent，就注定会漏掉这些发现。

没有可用的子 Agent 工具 → 在当前会话中扫描变更频率最高的文件范围，应用相同的模式和门槛，并说明本次运行采用了哪种方式。对于公开技能来说，这种回退方式占运行的大多数，而非少数边缘情况，因此它是一种真正的工作模式，应该有真实的覆盖范围说明，而不是以道歉的口吻说它有所降级。

4. 综合、把关、排序、选定

• 剔除任何缺少把关结论的记录。剔除，而不是修补，因为缺乏证据的把关正是删除测试要捕捉的情况；在主会话中修补它，就意味着要对你没读过的代码断言结论。
• 去重各个领域的记录；同一个接缝往往会从两侧浮现。
• 排序时先看强度，再看杠杆作用，最后看影响范围是否最小。
• **只要有任何非 weak 候选保留下来，就恰好选定一个。**无论列表中还有什么，都绝不选定 weak 候选。其余候选按顺序列为备选。
• **如果所有保留项都是 weak，则一个也不选定。**这意味着“没有值得做的候选”，并遵循没有候选通过把关时的处理方式，在终端表格中列出弱候选。

**完成条件：**每条记录都已剔除、去重或排序，结果是一个已选定的候选，或明确说明“没有值得做的候选”。

选定一个候选才是工作本身。五个看起来不相上下的选项，只是回到了运行本流程前的状态。

5. 报告，然后写入文件

先打印一张简洁的表格（候选、模式、强度、影响范围），再说明已选定的方案及其理由，最后列出备选。

每份报告都要包含覆盖范围说明，并同时出现在终端和文件中：*“按变更量为 1,240 个文件排序，跨 4 个领域阅读了排名最高的 40 个文件。”*看不见的数量上限会让完整性声明失实，也会混淆“这里没有结构性问题”和“我只看了 3% 的内容”。

文件应保存到 docs/refactor/NNNN-refactor-<slug>-YYYY-MM-DD.md，文件名由四位数字序号、小写类型前缀、简短的小写 kebab-case 主题 slug 和末尾的 ISO 创建日期组成。要确定序号 NNNN，请检查 docs/refactor/ 中当前工作树、git worktree list 列出的所有其他工作树以及 origin/HEAD（运行 git fetch origin 后执行 git ls-tree --name-only origin/HEAD docs/refactor/），取最高的四位前导序号并加一；如果没有，则从 0001 开始。扫描这三个来源，因为并行工作树否则会取到相同序号。跳过失败的来源，例如没有远程仓库；如果没有 git，则只列出目录。序号按目录分别编号，永不复用。编辑文件时保持完整文件名不变；对同一主题重新运行时，更新同一个文件，不要另建副本。如果仓库已有约定俗成的提案文档存放位置或命名方式，则优先遵循该约定。

文件应包含覆盖范围说明、排序表格，然后为每个候选各设一节，涵盖问题、拟议结构、更深层的原因、两个把关结论以及影响范围；至少要为已选定的候选提供一张 Mermaid 前后对比图。GitHub 和大多数编辑器都能原生渲染 Mermaid，因此无需生成 HTML 报告。

此文件是持久且可提交的，因为它是待在 PR 中审阅的提案，而不是临时文件。refactorkit 仍绝不提交它。

无法写入文件系统（基于浏览器的 Agent）→ 在其规范路径下以代码块形式打印文件内容，并跳过写入操作。

6. 交接

本节采用流程说明的语体撰写：每句只写一条指令，使用主动语态和现在时，不用比喻。

**变更内容。**报告写入的文件，并明确说明未触碰任何源文件。**存放位置。**给出路径。**下一步。**将已选定的候选转成分阶段计划。安装了 plankit 时，点名使用它，并将提案文件作为输入；否则自行编写计划，每个阶段对应一个安全的中间状态，并附上能验证该状态的检查。然后按此顺序将计划交给 grillkit 进行质询，再交给 implementkit 实施。

备选：如果提案取代了现有记录，则转交给决策记录技能（安装了 domainkit 时使用它）。

**如果结果为空或全部为弱候选，则说明没有下一步。**见下文。

当没有任何内容通过门槛时

结果为空也是一种真实结果，refactorkit 会如实报告：说明覆盖范围，指出没有任何内容通过门槛，并且不写入任何文件。结果全部为 weak 也是同样的情况：在终端表格中列出较弱的候选项，说明没有值得执行的候选项，并且不写入任何文件。

这比看起来更重要。必须产出发现结果的调查会凭空捏造结论，而捏造的架构建议读起来和真正的建议毫无二致：用词相同、语气同样笃定、形式也相同。只有当「这里什么都没有」是一个允许的答案时，删除测试才是真正的门槛。

终端行必须包含覆盖范围，例如 “扫描了 src/ 中的 38 个文件；没有任何内容通过删除测试”，否则空结果就无法与根本没有运行扫描区分开来。

说明

• 始终不修改源文件。 整个写入范围仅限一个新建的 Markdown 文件。任何其他操作，无论是重命名、提取，还是「快速修复」，都不在允许范围内，即使显然正确也不行。
• 仅使用只读 shell。 git 历史、文件读取、grep。绝不安装或运行分析工具来生成证据：探查是否存在此类工具并解析其输出，会让这项技能依赖于一种可能在小版本发布中发生变化的格式。如果仓库中已有此类磁盘文件，例如依赖关系图或覆盖率报告，可以读取，但绝不生成。
• 告知后续步骤，不要启动。 指明下一个 kit 及其单行调用方式；不要调用它。是否执行提案由读者决定，而调查若自行衔接构建流程，就剥夺了读者做出决定的权利。
• 告知后续步骤，不要设为前置条件。 如果未安装所述 kit，每条建议都应能退化为普通操作。即使是只有 git 而别无其他内容的空仓库，refactorkit 也能派上用场。
• 优先遵循仓库规范，而非这些默认规则。 仓库中已有的产物位置、文档约定或 Agent 指南文件（CLAUDE.md 或等效文件）中的明确政策优先；请说明你遵循了这些规范。