Back to Details

refactor

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Refactor Workflow Skill

Refactor 工作流技能

Overview

概述

Two-track workflow for improving existing code. Polish track for small, contained refactors; overhaul track for architectural changes and migrations. Both tracks emphasize exploration before commitment and mandatory documentation updates.
用于改进已有代码的双路径工作流。优化路径适用于小型、独立的重构；全面整改路径适用于架构变更和迁移。两条路径都强调在投入工作前先进行探索，且必须更新文档。

Triggers

触发条件

Activate this skill when:
  • User runs 
    /refactor
    command
  • User wants to improve existing code structure
  • User mentions "refactor", "restructure", "clean up", "migrate"
  • User asks to "move", "extract", "rename", or "reorganize" code
Disambiguation: If the user says "fix" or "clean up" — use 
/refactor
when the code works but needs structural improvement. Use 
/debug
when something is broken (error, crash, wrong behavior).
在以下场景激活此技能：
  • 用户运行/refactor命令
  • 用户希望改进现有代码结构
  • 用户提及"refactor"、"restructure"、"clean up"、"migrate"
  • 用户要求"move"、"extract"、"rename"或"reorganize"代码
歧义区分：如果用户提到"fix"或"clean up"——当代码能正常运行但需要结构优化时，使用/refactor；当代码出现故障（错误、崩溃、行为异常）时，使用/debug。

Workflow Overview

工作流概览

                              /refactor
                                  |
                            +-----+-----+
                            |  Explore  |
                            +-----+-----+
                                  |
                   +--------------+--------------+
                   |                             |
              --polish                       (default)
                   |                             |
                   v                             v
          +--------------+              +--------------+
          |    Polish    |              |   Overhaul   |
          |    Track     |              |    Track     |
          +--------------+              +--------------+
                              /refactor
                                  |
                            +-----+-----+
                            |  Explore  |
                            +-----+-----+
                                  |
                   +--------------+--------------+
                   |                             |
              --polish                       (default)
                   |                             |
                   v                             v
          +--------------+              +--------------+
          |    Polish    |              |   Overhaul   |
          |    Track     |              |    Track     |
          +--------------+              +--------------+

Command Interface

命令接口

Start Refactor Workflow

启动重构工作流

bash
undefined
bash
undefined

Default: overhaul track

默认：全面整改路径

/refactor "Description of what needs refactoring"
/refactor "需要重构的内容描述"

Fast path: polish track

快速路径：优化路径

/refactor --polish "Small contained refactor description"
/refactor --polish "小型独立重构描述"

Explore first, then decide track

先探索，再决定路径

/refactor --explore "Unsure of scope, explore first"
undefined
/refactor --explore "不确定范围，先探索"
undefined

Mid-Workflow Commands

工作流中途命令

bash
undefined
bash
undefined

Switch from polish to overhaul (during explore/brief)

在探索/概述阶段从优化路径切换到全面整改路径

/refactor --switch-overhaul
/refactor --switch-overhaul

Resume after context compaction

上下文压缩后恢复工作

/rehydrate
undefined
/rehydrate
undefined

Track Comparison

路径对比

AspectPolishOverhaul
Scope<=5 files, single concernNo limit
WorktreeNo (direct)Yes (isolated)
DelegationNoYes (full workflow)
DocumentationMandatory update phaseMandatory update phase
Human Checkpoints01 (merge)
维度优化路径全面整改路径
范围≤5个文件，单一关注点无限制
工作树不需要（直接修改）需要（隔离环境）
任务委派不支持支持（完整工作流）
文档更新强制阶段强制阶段
人工检查点0个1个（合并阶段）

Characterization Testing (Both Tracks)

特性测试（两条路径通用）

Before modifying any existing code behavior, capture current behavior as characterization tests. This is a mandatory pre-step for both tracks:
  1. Before changes: Write tests that document what the code currently does (not what it should do). Exercise the code through the most appropriate observable seam (API, CLI, integration boundary, or function) with representative inputs and assert on actual outputs/effects.
  2. During changes: Any characterization test failure means behavior changed. Evaluate: intentional or accidental?
  3. After changes: Document which characterization test failures were expected. Remaining characterization tests become regression tests.
This aligns with Michael Feathers' approach in Working Effectively with Legacy Code — understand behavior before changing it.
在修改任何现有代码行为之前，需捕获当前行为作为特性测试。这是两条路径都必须执行的前置步骤：
  1. 修改前：编写测试记录代码当前的实际行为（而非预期行为）。通过最合适的可观测接口（API、CLI、集成边界或函数），使用代表性输入执行代码，并断言实际输出/效果。
  2. 修改中：任何特性测试失败都意味着行为发生了变化。评估：是有意修改还是意外变更？
  3. 修改后：记录哪些特性测试失败是预期的。剩余的特性测试将成为回归测试。
这与Michael Feathers在《修改既有代码的有效方法》（Working Effectively with Legacy Code）中的方法一致——在修改前先理解行为。

Polish Track

优化路径

Fast path for small, contained refactors (<=5 files, single concern). Orchestrator may write code directly (exception to orchestrator constraints). No worktree, no delegation.
HSM phases: 
explore
→ 
brief
→ 
polish-implement
→ 
polish-validate
→ 
polish-update-docs
→ 
completed
For detailed phase instructions, state management, and auto-chain behavior, see 
@skills/refactor/references/polish-track.md
.
适用于小型、独立重构（≤5个文件，单一关注点）的快速路径。编排器可直接编写代码（突破编排器约束的例外情况）。无需工作树，不支持任务委派。
HSM阶段：
explore
→ 
brief
→ 
polish-implement
→ 
polish-validate
→ 
polish-update-docs
→ 
completed
关于详细的阶段说明、状态管理和自动链式行为，请查看
@skills/refactor/references/polish-track.md
。

Overhaul Track

全面整改路径

Rigorous path for architectural changes, migrations, and multi-file restructuring. Uses full delegation model with worktree isolation.
HSM phases: 
explore
→ 
brief
→ 
overhaul-plan
→ 
overhaul-plan-review
→ 
overhaul-delegate
→ 
overhaul-review
→ 
overhaul-update-docs
→ 
synthesize
→ 
completed
For detailed phase instructions, skill invocations, and auto-chain behavior, see 
@skills/refactor/references/overhaul-track.md
.
适用于架构变更、迁移和多文件重构的严谨路径。采用带工作树隔离的完整委派模型。
HSM阶段：
explore
→ 
brief
→ 
overhaul-plan
→ 
overhaul-plan-review
→ 
overhaul-delegate
→ 
overhaul-review
→ 
overhaul-update-docs
→ 
synthesize
→ 
completed
关于详细的阶段说明、技能调用和自动链式行为，请查看
@skills/refactor/references/overhaul-track.md
。

State Management

状态管理

Initialize refactor workflow:
action: "init", featureId: "refactor-<slug>", workflowType: "refactor"
Use 
describe
to discover the full state schema at runtime: 
exarchos_workflow({ action: "describe", actions: ["init"] })
.
初始化重构工作流：
action: "init", featureId: "refactor-<slug>", workflowType: "refactor"
使用
describe
在运行时发现完整状态 schema：
exarchos_workflow({ action: "describe", actions: ["init"] })
。

Phase Transitions and Guards

阶段转换与守卫条件

Sequential traversal required. Every phase MUST be traversed in order — you cannot skip phases, even if you have all the data for a later phase ready. For example, 
explore
must transition to 
brief
before 
overhaul-plan
— attempting 
explore
→ 
overhaul-plan
directly will be rejected by the HSM. From 
brief
you must go to 
polish-implement
or 
overhaul-plan
, not directly to 
completed
. Each transition requires its guard to be satisfied via 
updates
sent alongside the 
phase
parameter in a single 
set
call. See 
@skills/refactor/references/polish-track.md
or 
@skills/refactor/references/overhaul-track.md
for the exact tool call at each step.
Every phase transition has a guard that must be satisfied. Before transitioning, consult 
@skills/workflow-state/references/phase-transitions.md
for the exact prerequisite for each guard.
The pattern for every transition: send the guard prerequisite in 
updates
and the target in 
phase
in a single 
set
call.
必须按顺序遍历。所有阶段必须按顺序执行——即使已准备好后续阶段的所有数据，也不能跳过阶段。例如，
explore
必须先转换到
brief
，才能进入
overhaul-plan
——直接尝试
explore
→ 
overhaul-plan
会被HSM拒绝。从
brief
必须进入
polish-implement
或
overhaul-plan
，不能直接到
completed
。每次转换都需要通过在单个
set
调用中同时发送
updates
和
phase
参数来满足守卫条件。每个步骤的具体工具调用请查看
@skills/refactor/references/polish-track.md
或
@skills/refactor/references/overhaul-track.md
。
每个阶段转换都有必须满足的守卫条件。转换前，请查阅
@skills/workflow-state/references/phase-transitions.md
获取每个守卫条件的确切前提。
所有转换的模式：在单个
set
调用中，将守卫条件的前提放在
updates
中，目标阶段放在
phase
中。

Schema Discovery

Schema 发现

Use 
exarchos_workflow({ action: "describe", actions: ["set", "init"] })
for parameter schemas and 
exarchos_workflow({ action: "describe", playbook: "refactor" })
for phase transitions, guards, and playbook guidance.
使用
exarchos_workflow({ action: "describe", actions: ["set", "init"] })
获取参数 schema，使用
exarchos_workflow({ action: "describe", playbook: "refactor" })
获取阶段转换、守卫条件和工作流指南。

Decision Runbooks

决策手册

For track-selection criteria at the explore phase, query the decision runbook: 
exarchos_orchestrate({ action: "runbook", id: "scope-decision" })
This runbook provides structured criteria for choosing between polish and overhaul tracks based on file count, structural impact, and PR scope.
在探索阶段选择路径时，查询决策手册：
exarchos_orchestrate({ action: "runbook", id: "scope-decision" })
该手册提供了基于文件数量、结构影响和PR范围选择优化或全面整改路径的结构化标准。

Track Switching

路径切换

If scope expands beyond polish limits during explore or brief phase, use 
mcp__exarchos__exarchos_workflow
with 
action: "set"
to set 
track
to "overhaul" and update 
explore.scopeAssessment.recommendedTrack
.
Scope thresholds: If >5 files affected OR changes cross module boundaries -> recommend overhaul track.
Indicators to switch:
  • More than 5 files affected
  • Multiple concerns identified
  • Cross-module changes needed
  • Test coverage gaps require new tests
Output: "Scope expanded beyond polish limits. Switching to overhaul track."
如果在探索或概述阶段范围超出优化路径的限制，使用
mcp__exarchos__exarchos_workflow
并设置
action: "set"
，将
track
设为"overhaul"，并更新
explore.scopeAssessment.recommendedTrack
。
范围阈值：如果影响文件>5个，或变更跨模块边界→建议使用全面整改路径。
切换指标：
  • 影响文件超过5个
  • 识别出多个关注点
  • 需要跨模块变更
  • 测试覆盖率缺口需要新增测试
输出信息："范围超出优化路径限制，切换至全面整改路径。"

Integration Points

集成点

CRITICAL: All skill invocations MUST use explicit 
Skill()
tool calls:
SkillInvocationUsage
/plan
[Invoke the exarchos:plan skill with args: --refactor <state-file>]
Task extraction from brief
/delegate
[Invoke the exarchos:delegate skill with args: <state-file>]
Subagent dispatch for TDD
/review
[Invoke the exarchos:review skill with args: <state-file>]
Quality review
/synthesize
[Invoke the exarchos:synthesize skill with args: <feature>]
PR creation
重要提示：所有技能调用必须使用显式的
Skill()
工具调用：
技能调用方式用途
/plan
[Invoke the exarchos:plan skill with args: --refactor <state-file>]
从概述中提取任务
/delegate
[Invoke the exarchos:delegate skill with args: <state-file>]
为TDD分派子Agent
/review
[Invoke the exarchos:review skill with args: <state-file>]
质量评审
/synthesize
[Invoke the exarchos:synthesize skill with args: <feature>]
创建PR

Anti-Patterns

反模式

Don'tDo Instead
Skip explorationAlways assess scope first (see 
references/explore-checklist.md
)
Use polish for large changesSwitch to overhaul when scope expands
Skip doc updatesDocumentation is mandatory (see 
references/doc-update-checklist.md
)
Add features during refactorScope creep - stick to brief goals
Skip tests because "just moving code"Refactors need test verification
Create design document for polishUse brief in state file instead
Work in main for overhaulUse worktree isolation
禁止操作正确做法
跳过探索阶段始终先评估范围（查看
references/explore-checklist.md
）
用优化路径处理大型变更范围扩大时切换到全面整改路径
跳过文档更新文档更新是强制要求（查看
references/doc-update-checklist.md
）
重构期间添加新功能避免范围蔓延——坚守概述中的目标
因为"只是移动代码"而跳过测试重构需要测试验证
为优化路径创建设计文档改用状态文件中的概述
在主分支进行全面整改使用工作树隔离环境

Exarchos Integration

Exarchos 集成

When Exarchos MCP tools are available, emit events throughout the refactor workflow:
  1. At workflow start (explore): 
    mcp__exarchos__exarchos_event
    with 
    action: "append"
    → 
    workflow.started
    with workflowType "refactor"
  2. On track selection: Auto-emitted by 
    exarchos_workflow
    set
    when 
    phase
    is provided — emits 
    workflow.transition
    with selected track (polish/overhaul)
  3. On each phase transition: Auto-emitted by 
    exarchos_workflow
    set
    when 
    phase
    is provided — emits 
    workflow.transition
    with from/to/trigger/featureId
  4. Overhaul track stacking: Handled by 
    /delegate
    (subagents use 
    git commit
    + 
    git push
    per implementer prompt)
  5. Polish track commit: Single 
    git commit -m "refactor: <description>"
    + 
    git push
    — no multi-branch stacking needed
  6. On complete: Auto-emitted by 
    exarchos_workflow
    set
    when transitioning to terminal state — emits 
    workflow.transition
    to "completed"
当Exarchos MCP工具可用时，在重构工作流的各个环节发送事件：
  1. 工作流启动时（探索阶段）：
    mcp__exarchos__exarchos_event
    设置
    action: "append"
    → 发送
    workflow.started
    事件，workflowType为"refactor"
  2. 路径选择时：当
    exarchos_workflow
    的
    set
    调用提供
    phase
    时自动发送——发送
    workflow.transition
    事件，包含所选路径（polish/overhaul）
  3. 每次阶段转换时：当
    exarchos_workflow
    的
    set
    调用提供
    phase
    时自动发送——发送
    workflow.transition
    事件，包含来源/目标/触发条件/featureId
  4. 全面整改路径堆叠：由
    /delegate
    处理（子Agent根据实现者提示执行
    git commit
    + 
    git push
    ）
  5. 优化路径提交：单次
    git commit -m "refactor: <description>"
    + 
    git push
    ——无需多分支堆叠
  6. 工作流完成时：当转换到终端状态时，由
    exarchos_workflow
    的
    set
    调用自动发送——发送
    workflow.transition
    事件，目标状态为"completed"