workflow-checkpoint-refactor

/workflow:checkpoint-refactor

多阶段重构，状态可持久保存，即使超出上下文限制或跨越会话边界也能保留。

何时使用此技能

在以下情况使用此技能……	在以下情况直接重构……
重构涉及 10 个以上文件	修改 1-5 个文件
工作将超出上下文限制	小范围、专注的修改
需要跨会话恢复工作	单会话任务
存在多个相互依赖的阶段	修改的文件彼此独立
团队协作进行大型重构	独自快速修复

上下文

• 仓库根目录：!git rev-parse --show-toplevel
• 计划文件是否存在：!find . -maxdepth 1 -name REFACTOR_PLAN.md
• Git 状态：!git status --porcelain
• 最近的提交：!git log --oneline --max-count=5

参数

• --init：交互式创建新的重构计划
• --continue：从最后一个已完成的阶段继续
• --status：显示当前计划进度
• --phase=N：执行指定阶段

计划文件格式

计划文件（REFACTOR_PLAN.md）用于保存持久状态。它是循环的 紧凑状态包（.claude/rules/loop-integrity.md）：新会话，或不记得先前阶段的子 Agent， 都必须仅凭此文件即可恢复工作。因此，每个阶段不仅要记录要做什么，还要记录已验证什么以及发生了哪些变化—— 如果缺少这些信息，跨越上下文限制恢复工作时，就会在不知不觉中重复或撤销已完成的工作。

# Refactor Plan: {description}

Created: {date}
Last updated: {date}
Base commit: {hash}
Exit condition: {the literal criterion that ends the whole refactor — e.g. "all phases done, full suite + tsc green on base"}

## Overview
{What is being refactored and why}

## Phase 1: {phase name}
- **Status**: done | in-progress | pending | needs-review
- **Files**: file1.ts, file2.ts, file3.ts
- **Description**: {what this phase does}
- **Acceptance criteria**: {how to verify success — the phase's exit condition}
- **Verifier result**: {what the independent check returned — PASS/FAIL + the criterion it judged; filled in at the phase boundary}
- **Changed since last run**: {what this phase actually touched, so a successor doesn't redo or undo it}
- **Result**: {summary of changes made, filled in after completion}

## Phase 2: {phase name}
- **Status**: pending
- **Files**: file4.ts, file5.ts
- **Description**: {what this phase does}
- **Acceptance criteria**: {how to verify success}
- **Verifier result**: {empty until verified}
- **Changed since last run**: {empty until completed}
- **Result**: {empty until completed}

...

执行

执行此多阶段重构工作流：

步骤 1：初始化重构计划（--init 模式）

如果提供了 --init 标志：

1. 分析范围：阅读待重构文件，了解其依赖关系
2. 定义阶段，每个阶段都应：
   • 涉及 3-7 个文件（限定范围）
   • 有明确的验收标准（测试、类型检查）
   • 可独立提交
   • 基于前一阶段推进
3. 编写计划文件：在仓库根目录创建 REFACTOR_PLAN.md
4. 记录基准提交：git log --format='%H' -1

阶段排序：先处理共享工具和类型，最后处理叶级组件；测试应与实现同步进行。

步骤 2：恢复现有重构（--continue 模式）

如果提供了 --continue 标志：

1. 读取 REFACTOR_PLAN.md
2. 查找下一个待处理阶段（状态为 pending 或 needs-review）
3. 验证所有先前阶段的状态均为 done
4. 执行该阶段（转到步骤 4）

步骤 3：检查进度（--status 模式）

如果提供了 --status 标志：

1. 读取 REFACTOR_PLAN.md
2. 解析计划并显示阶段、描述、状态和文件数量的状态表
3. 退出

第 4 步：执行目标阶段（--phase=N 或在第 2 步中选择）

对于每个阶段：

1. 从计划文件中读取上下文（当前阶段的详细信息）
2. 只读取此阶段列出的文件
3. 根据阶段说明实施更改
4. 使用适当的工具验证（tsc、ty check、cargo check 或 npm/pytest test）
5. 如果验证失败：
   • 如果错误容易解决，就修复错误
   • 如果问题复杂，就将阶段标记为 needs-review，并注明错误详情
   • 使用 WIP: 前缀提交部分工作
6. 如果验证通过，若验收标准需要判断（例如“该类现在只负责单一职责”），而不是纯机械检查（测试套件通过或 tsc 无错误本身已是独立验证——测试失败并不在意你付出了多少努力），则必须先经过独立验证者核验，才能将阶段标记为 done：
   • 调度一个全新的 Task 子 Agent，让它只读取此阶段的验收标准和最终差异，不读取工作者的推理过程，并判断标准是否达成。工作者有偏向于宣布完成的倾向；循环的停止条件必须来自循环之外（.claude/rules/loop-integrity.md，支柱 1）。如果验收标准涉及行为（“端点返回 X”“该 bug 不再复现”），则委派给 agent-patterns-plugin:execution-grounded-review，由它先运行测试套件，再根据执行证据逐条核验标准，而非仅凭表面判断。
   • 在阶段的 Verifier result 字段中记录核验结果（PASS/FAIL + 已核验的标准）。
   • 如果核验者返回 FAIL，则将状态保留为 in-progress/needs-review，并在标记为 done 之前解决问题。
7. 核验通过后，更新计划文件：将状态设为 done，填写 Verifier result、Changed since last run 和 Result，然后提交： git add -u && git commit -m "refactor phase N: {description}"
8. 如果还有后续阶段，则继续下一阶段或建议使用 --continue

第 5 步：委派子 Agent（适用于大型阶段）

对于涉及 7 个或更多文件的阶段，将任务委派给 Task 子 Agent，并提供：

• 要修改的文件列表
• 阶段说明和验收标准
• 指示：运行验证、更新计划文件、暂存并提交更改
• 如果验证失败：将阶段标记为 needs-review，并注明错误详情

恢复模式

情况	操作
在阶段中途达到上下文限制	启动新会话，运行 --continue
阶段标记为 needs-review	阅读计划以了解详情，修复问题，运行 --phase=N
阶段完成后测试损坏	撤销阶段提交，调查问题，然后重新执行
计划需要调整	直接编辑 REFACTOR_PLAN.md，更新各阶段
基础分支已更新	变基到新的基础分支，并重新验证已完成的阶段

Agentic 优化

上下文	命令
检查计划是否存在	test -f REFACTOR_PLAN.md && echo "exists"
快速类型检查	npx tsc --noEmit --pretty 2>&1 | head -20
快速测试	npm test -- --bail=1 2>&1 | tail -20
阶段提交	git commit -m "refactor phase N: description"
验证工作状态	npx tsc --noEmit && npm test -- --bail=1
显示计划阶段	grep "^## Phase" REFACTOR_PLAN.md
显示阶段状态	grep -A1 "^## Phase" REFACTOR_PLAN.md | grep Status

快速参考

操作	命令
初始化新的重构	/workflow:checkpoint-refactor --init
检查进度	/workflow:checkpoint-refactor --status
恢复工作	/workflow:checkpoint-refactor --continue
运行指定阶段	/workflow:checkpoint-refactor --phase=3
手动编辑计划	直接编辑 REFACTOR_PLAN.md

相关技能

• code-review-checklist - 审查重构后的代码
• refactoring-patterns - 重构技巧
• adversarial-review - 基于判断的阶段门委派的独立验证者
• execution-grounded-review - 用于行为型阶段验收标准的执行验证者
• .claude/rules/loop-integrity.md - 说明计划文件为何是状态数据包，以及为何要独立判断 done