用途
migration-loop 用于把一组已知、可枚举的目标逐个迁移到全部完成。它是一次配置,基于 loop-controller:后者提供循环机制(原语选择、完整护栏栈、状态外置),本技能提供两样针对「把固定目标集迁移到完成」的东西——一份默认判定为未完成的(default-FAIL)目标清单,每次迭代只驱动一个条目;以及「旧模式已彻底消失」的证明(对旧模式做 grep 返回零),而不仅仅是「测试通过」。
它适用于一个有限、可枚举的目标集合需要同一种变换的场景,例如 codemod、Jest 转 Vitest、API 版本升级、框架或导入重命名,并且需要一种方式验证行为保持不变。
主要能力
- 每次迭代只处理一个目标:从清单中挑出下一个 migrated 为 false 的目标,只对该目标应用变换,运行测试套件确认行为一致,通过后提交一个以该目标命名的检查点提交,并把清单条目翻转为 true。
- 完成证明由三个证据组成,全部必需且默认判定为未完成:清单全部为 true、完整测试套件退出码为 0、对旧模式 grep 返回零。
- 记忆外置:migration-checklist.json(每个目标一条默认未完成条目 + 旧到新的映射)、PROGRESS.md(已迁移/下一步)、每个已迁移目标一个 git 检查点提交。
- 停止条件:三个证明证据全部成立,或达到迭代上限,或连续 3 轮无进展,或达到预算上限,或遇到不可逆目标的 HITL 检查点。
- 支持顺序执行与扇出两种模式:顺序模式每次一个目标;并行模式用于大规模、机械统一的目标集,通过 worktree 隔离的子代理扇出,每个迁移一个切片并在自己的 worktree 中提交。
- 支持 expand–contract 模式:当一次机械变更的爆炸半径同时破坏大量调用点时,按 expand → migrate → contract 三阶段排序。
使用方式
该循环会自行编辑并提交代码,因此禁用了模型自动调用(disable-model-invocation):需要手动输入 /migration-loop(或由编排器派发),而不是让 Claude 因为发现旧 API 就悄悄开始重写每个文件。
步骤:
- 枚举目标并构建默认未完成的清单。在循环前发现完整目标集,用 Grep/Glob 找到旧模式的每一处出现,去重成目标列表,每条写成 JSON 条目,包含 migrated: false、旧到新映射和精确的 grep 模式,存放在 profile 定义的路径(默认 migration-checklist.json)。清单就是循环的范围。
- 决定顺序还是扇出。顺序(/goal,默认)用于目标相互依赖、变换微妙或集合小到需要逐目标审查的情况;并行(/batch / 动态工作流)用于大规模、机械统一的目标集,通过 worktree 隔离的子代理扇出,每个 worktree 的构建/测试并行度上限为 1。
- 迁移一个目标,验证行为一致,提交检查点。对单个目标应用变换后运行完整套件;若套件变红,说明变换改变了行为,需先修复(或调用 fix-until-green)再继续,绝不在红色套件上推进清单。通过后提交以该目标命名的检查点提交,再翻转条目。
- 重新运行整个证明,重复。最后一个目标之后,同时运行三个证明证据;若清单全为 true 但 grep 非零,说明枚举时漏了目标,补上并继续循环。三者一次通过即完成,报告最终清单、套件退出码和 grep -c 输出(零)作为证据。
适用场景
- 有限、可枚举的目标集需要同一种变换,且能验证行为保持不变。
- 可逆的代码变换,在测试门禁和逐目标检查点提交之下,可无人值守运行。
- 大规模、机械统一的目标集(数百个相同的 codemod 位置)可用扇出模式。
- 一次机械变更同时破坏大量调用点时,可用 expand–contract 模式。
限制
- 不可逆资源的迁移属于 HITL 检查点:例如针对实时数据的真实数据库 schema 迁移、破坏性数据回填、外部系统。schema 迁移场景应交给 db-migration-agent,它负责 up/down 迁移、dry-run 和回滚。
- 禁止伪造完成:未变换就标记 migrated 为 true、收窄 grep 模式使其报告为零而用法仍存在、或删除/跳过测试以在行为变更下保持套件绿色,均属违规。
- 达到迭代上限是停止并上报,而不是放宽 grep 或未迁移就标记完成的许可。
- 同一目标连续 3 轮仍为 false(或旧模式 grep 计数不再下降)时停止并上报。
- 长迁移中,清单条目只有在观察到该目标的(套件退出码 0 + 检查点提交哈希)这一对证据时才翻转为 true;只有 PROGRESS.md 一行而无两者即为伪造。
- 每次迭代结束时必须是目标已迁移、已提交、已翻转,或处于声明的停止条件;不能以「下一步我将迁移 X」而无编辑结束。
- 预算上限从 .claude/profile.yaml 读取;不应向模型显示倒计时,也不应让长集合触发总结并退出。
与相邻技能的区别
- 与 fix-until-green 相比:后者驱动失败的套件变绿;本循环驱动固定目标集完全迁移。套件绿色在这里只是三个证明证据之一,承重的是旧模式 grep。当变换使门禁变红时,本循环会调用 fix-until-green。
- 与 db-migration-agent 相比:后者作为 HITL 操作负责单个不可逆 schema 迁移(up/down、dry-run、回滚);本循环驱动一组可逆代码变换到完成,并在 HITL 检查点把 schema 场景委托给它。
参考文件
references/migration-checklist.md:构建目标清单/映射(migration-checklist.json 默认未完成 schema 及示例)、顺序与 /batch 扇出的决策及 worktree 隔离形态,以及「旧模式已彻底消失」的验证(选择 grep 模式、限定范围、读取计数)。