refactor

重构工作流技能

概述

用于改进现有代码的双轨工作流。精修轨道适用于小型、范围明确的重构；全面改造轨道适用于架构变更和迁移。两条轨道都强调先探索再投入，并要求更新文档。

触发条件

在以下情况下激活此技能：

• 用户运行 {{COMMAND_PREFIX}}refactor 命令
• 用户想要改进现有代码结构
• 用户提到“重构”“重新组织”“清理”“迁移”
• 用户要求“移动”“提取”“重命名”或“重新组织”代码

**区分：**如果用户说“修复”或“清理”——代码能正常运行，但需要改进结构时，使用 {{COMMAND_PREFIX}}refactor。有问题（出错、崩溃、行为异常）时，使用 {{COMMAND_PREFIX}}debug。

工作流概览

                              {{COMMAND_PREFIX}}refactor
                                  |
                            +-----+-----+
                            |  Explore  |
                            +-----+-----+
                                  |
                   +--------------+--------------+
                   |                             |
              --polish                       (default)
                   |                             |
                   v                             v
          +--------------+              +--------------+
          |    Polish    |              |   Overhaul   |
          |    Track     |              |    Track     |
          +--------------+              +--------------+

命令接口

启动重构工作流

# Default: overhaul track
{{COMMAND_PREFIX}}refactor "Description of what needs refactoring"

# Fast path: polish track
{{COMMAND_PREFIX}}refactor --polish "Small contained refactor description"

# Explore first, then decide track
{{COMMAND_PREFIX}}refactor --explore "Unsure of scope, explore first"

工作流中途命令

# Switch from polish to overhaul (during explore/brief)
{{COMMAND_PREFIX}}refactor --switch-overhaul

# Resume after context compaction
{{COMMAND_PREFIX}}rehydrate

轨道对比

方面	精修	全面改造
范围	<=5 个文件，单一关注点	无限制
Worktree	否（直接操作）	是（隔离）
委派	否	是（完整工作流）
文档	必须包含更新阶段	必须包含更新阶段
人工检查点	0	1（合并）

何时使用 refactor 而不是 debug

信号	使用 {{COMMAND_PREFIX}}refactor	使用 {{COMMAND_PREFIX}}debug
代码能正常运行，但杂乱/复杂	是	否
有问题或行为异常	否	是
“应该重新组织一下”	是	否
用户报告了 bug 或回归问题	否	是
性能下降	如果是结构性问题，切换到 {{COMMAND_PREFIX}}refactor	从 {{COMMAND_PREFIX}}debug 开始（调查）
可正常运行的代码违反 SOLID 原则	是	否
生产日志中出现错误	否	是

**经验法则：**如果对能正常运行的代码感到_不满意_（难以阅读、违反 SOLID 原则、逻辑重复），使用 {{COMMAND_PREFIX}}refactor。如果出现了_症状_（本应正常工作的内容却无法正常工作），使用 {{COMMAND_PREFIX}}debug。

特征测试（两条轨道均适用）

修改任何现有代码的行为之前，先通过特征测试记录当前行为。这是两条轨道都必须执行的前置步骤：

1. 更改前：编写测试，记录代码当前的行为（而不是它应该有的行为）。通过最合适的可观察接口（API、CLI、集成边界或函数）使用有代表性的输入来执行代码，并断言实际输出/效果。
2. **更改过程中：**任何特征测试失败都意味着行为发生了变化。评估这种变化是有意还是意外。
3. **更改后：**记录哪些特征测试失败是预期的。其余特征测试将成为回归测试。

这与 Michael Feathers 在 Working Effectively with Legacy Code 中提出的方法一致——先了解行为，再进行更改。

测试基准完整性检查（两条轨道均适用）

特征测试是你的判断基准——用于判断行为是否发生变化的安全网。只有在重构过程中不修改这个基准，安全网才能发挥作用。完成重构之前，检查测试差异：

git diff -- tests/

重构过程中可以增加测试基准（新增特征测试、新增用例），但绝不能悄悄修改现有的特征断言。悄悄修改测试基准会破坏安全网：测试现在会针对已更改的行为通过，从而掩盖特征测试本应捕获的回归问题。如果确实必须更改特征断言，这就属于行为变更——要明确指出并说明理由，不要不加说明地将其混入重构差异中。

设计阶段约束（两条路径均适用）

在 brief 阶段，确定方案之前，根据与重构相关的架构不变量，列出 Constraints 部分。这是重构设计阶段对应于 /ideate Phase 0 的环节，并使用同一个共享事实来源来确定选择规则：参见 @skills/ideate/references/constraint-anchoring.md。加载 .exarchos/invariants.md（cost-of-load: always-load 条目）并输出 Constraints 部分。**仅在注册了目录时启用：**如果 .exarchos.yml: invariants.catalogs 下未注册目录，则不输出 Constraints 部分，直接继续。brief 阶段中该部分的位置请参见 @skills/refactor/references/brief-template.md。

Polish 路径

适用于小型、范围明确的快速重构（<=5 个文件，单一关注点）。编排器可以直接编写代码（这是对编排器约束的例外）。不使用 worktree，不委派任务。

HSM 阶段：explore → brief → polish-implement → polish-validate → polish-update-docs → completed

有关详细的阶段说明、状态管理和自动链式执行行为，请参见 @skills/refactor/references/polish-track.md。

Overhaul 路径

适用于架构变更、迁移和多文件重组的严谨路径。使用完整的委派模型，并通过 worktree 隔离。

HSM 阶段：explore → brief → overhaul-plan → overhaul-plan-review → overhaul-delegate → overhaul-review → overhaul-update-docs → synthesize → completed

有关详细的阶段说明、技能调用和自动链式执行行为，请参见 @skills/refactor/references/overhaul-track.md。

状态管理

初始化重构工作流：

action: "init", featureId: "refactor-<slug>", workflowType: "refactor"

使用 describe 在运行时发现完整的状态架构：exarchos_workflow({ action: "describe", actions: ["init"] })。

阶段转换与守卫条件

必须按顺序遍历。 每个阶段都必须按顺序遍历 — 不能跳过阶段，即使你已准备好后续阶段所需的全部数据。例如，explore 必须先转换到 brief，再进入 overhaul-plan；直接尝试从 explore 转到 overhaul-plan 会被 HSM 拒绝。从 brief 必须进入 polish-implement 或 overhaul-plan，不能直接进入 completed。每次转换都必须通过一次 set 调用，在 phase 参数旁发送 updates，以满足相应的守卫条件。有关每一步的确切工具调用，请参见 @skills/refactor/references/polish-track.md 或 @skills/refactor/references/overhaul-track.md。

每次阶段转换都有必须满足的守卫条件。转换前，请查阅 @skills/checkpoint/references/phase-transitions.md，了解各守卫条件对应的准确前置要求。

每次转换都遵循以下模式：在一次 set 调用中，通过 updates 发送守卫条件的前置要求，并通过 phase 指定目标阶段。

架构发现

使用 exarchos_workflow({ action: "describe", actions: ["update", "init"] }) 获取参数架构，并使用 exarchos_workflow({ action: "describe", playbook: "refactor" }) 获取阶段转换、守卫条件和操作手册指南。

决策手册

在 explore 阶段查询决策手册，以获取路径选择标准： exarchos_orchestrate({ action: "runbook", id: "scope-decision" })

此手册根据文件数量、结构影响和 PR 范围，提供用于选择 polish 或 overhaul 路径的结构化标准。

路径切换

如果在 explore 或 brief 阶段发现范围超出 polish 路径的限制，请使用 {{MCP_PREFIX}}exarchos_workflow，并设置 action: "update"，将 track 设为 "overhaul"，同时更新 explore.scopeAssessment.recommendedTrack。

**范围阈值：**如果受影响的文件数 >5，或变更跨越模块边界 -> 建议采用 overhaul 路径。

切换指标：

• 受影响的文件超过 5 个
• 发现多个关注点
• 需要跨模块变更
• 测试覆盖缺口需要新增测试

输出：“范围已超出 polish 路径的限制。正在切换到 overhaul 路径。”

集成点

重要： 所有技能调用都必须使用显式的 Skill() 工具调用：

技能	调用方式	用法
{{COMMAND_PREFIX}}plan	{{CHAIN next="plan" args="--refactor <state-file>"}}	从简报中提取任务
{{COMMAND_PREFIX}}delegate	{{CHAIN next="delegate" args="<state-file>"}}	为 TDD 分派子 Agent
{{COMMAND_PREFIX}}review	{{CHAIN next="review" args="<state-file>"}}	质量审查
{{COMMAND_PREFIX}}synthesize	{{CHAIN next="synthesize" args="<feature>"}}	创建 PR

反模式

不要	应该
跳过探索	始终先评估范围（参见 references/explore-checklist.md）
对大规模变更使用 polish	范围扩大时切换到 overhaul
跳过文档更新	文档更新是强制要求（参见 references/doc-update-checklist.md）
重构时添加功能	避免范围蔓延——遵循简报目标
因为“只是移动代码”而跳过测试	重构需要测试验证
为 polish 创建设计文档	改用状态文件中的简报
在 main 中进行 overhaul	使用 worktree 隔离

Exarchos 集成

当 Exarchos MCP 工具可用时，在整个重构工作流中发出事件：

1. 工作流开始时（explore）： 使用 action: "append" 调用 {{MCP_PREFIX}}exarchos_event → 发出 workflow.started 事件，workflowType 为 "refactor"
2. 选择轨道时： 提供 phase 时，exarchos_workflow 的 set 会自动发出事件——发出 workflow.transition 事件，包含所选轨道（polish/overhaul）
3. 每次阶段转换时： 提供 phase 时，exarchos_workflow 的 set 会自动发出事件——发出包含 from/to/trigger/featureId 的 workflow.transition 事件
4. overhaul 轨道的堆叠： 由 {{COMMAND_PREFIX}}delegate 处理（子 Agent 按照实现者提示使用 git commit + git push）
5. polish 轨道的提交： 单次执行 git commit -m "refactor: <description>" + git push——无需多分支堆叠
6. 完成时： 转换到终止状态时，exarchos_workflow 的 set 会自动发出事件——发出指向 "completed" 的 workflow.transition 事件