Guided migration and upgrade — dependency major version bumps, API breaking change adaptation, language edition upgrades, and build system migrations. Preserves compatibility through incremental steps with rollback points. Auto-saves migration report to .artifacts/ TRIGGER when: user asks to upgrade a dependency, bump a major version, migrate an API, switch build systems, or adapt to breaking changes from a library/framework update. DO NOT TRIGGER when: user is adding a new dependency (use /design), or making internal design changes unrelated to external API/version changes (use /refactor or /refactor breaking for destructive internal redesign).
当前时间:!date '+%Y-%m-%d %H:%M:%S'
当前目录:!pwd
当前分支:!git branch --show-current 2>&1
构建配置:!find . -maxdepth 2 -name "xmake.lua" -o -name "Cargo.toml" -o -name "pyproject.toml" -o -name "package.json" -o -name "go.mod" -o -name "CMakeLists.txt" 2>/dev/null | head -10
项目文件概览:!find . -type f \( -name "*.rs" -o -name "*.cpp" -o -name "*.hpp" -o -name "*.h" -o -name "*.py" -o -name "*.ts" -o -name "*.go" \) ! -path "*/target/*" ! -path "*/.git/*" ! -path "*/node_modules/*" | head -60
构建命令策略:!cat ~/.claude/skills/shared/build-detect.md
产物存储约定:!cat ~/.claude/skills/shared/artifacts.md
Bench 感知:!cat ~/.claude/skills/shared/bench-aware.md
目标:$ARGUMENTS
迁移的关键不是"改完",而是每一步都可回滚、可验证。
大爆炸式迁移(改完所有再测)是灾难之源。每一步改动后构建通过、测试通过,才推进到下一步。
upgrade tokio to 2.0、bump spdlogrust edition 2024、C++23 to C++26cmake to xmake、pip to uvactix-web to axum、unittest to pytestmigrate from deprecated API X to Y[strategy]:
incremental(默认):逐模块迁移,每步提交,新旧可共存big-bang:一次性全量替换(仅适用于无法增量迁移的场景)[dry-run]:仅输出迁移计划和影响分析,不执行[auto]:无人值守模式——跳过迁移计划确认,直接执行;迁移中遇到三次修复仍失败时自动终止并回滚(而非暂停等待)记录迁移前的完整状态:
mkdir -p .artifacts
# 依赖版本锁定
cat Cargo.lock 2>/dev/null | head -100 # Rust
cat uv.lock 2>/dev/null | head -100 # Python
cat package-lock.json 2>/dev/null | head -100 # Node
# 当前构建和测试基线
git rev-parse HEAD 2>&1
运行完整构建和测试,建立基线。按 Bench 感知约定执行基线检查。
❌ 迁移前基线未通过。请先修复现有问题再开始迁移。根据迁移类型,收集必要信息:
依赖升级:
# 当前版本
grep "<dep_name>" Cargo.toml xmake.lua pyproject.toml package.json 2>/dev/null
# 查找项目中所有使用该依赖的位置
grep -rn "<dep_name>" --include="*.rs" --include="*.cpp" --include="*.py" --include="*.ts" --include="*.go" . | grep -v "target/" | grep -v "node_modules/" | grep -v ".git/"
阅读目标版本的:
语言版本升级:
构建系统迁移:
## 迁移影响评估
### 迁移类型
<依赖升级 / 语言版本 / 构建系统 / 框架 / API>
### Breaking Changes 清单
| 序号 | 变更 | 影响范围 | 代码位置 | 适配方式 |
|------|------|----------|----------|----------|
| 1 | `foo()` 签名变更 | 12 处调用 | `src/*.rs` | 更新参数 |
| 2 | `Bar` 类型移至新模块 | 8 处 import | `src/*.rs` | 更新路径 |
| ... | ... | ... | ... | ... |
### 废弃 API 使用情况
| 废弃 API | 使用次数 | 替代方案 |
|----------|----------|----------|
| `old_fn()` | 5 | `new_fn()` |
| ... | ... | ... |
### 风险评估
- 总影响文件数:N
- Breaking change 数量:N
- 预估工作量:<小 / 中 / 大>
- 策略建议:<incremental / big-bang,附理由>
将迁移拆分为可独立验证的原子步骤:
## 迁移计划
### 步骤概览
1. [准备] <创建迁移分支,添加兼容层 / feature flag>
2. [适配] <逐模块适配 breaking change #1>
3. [适配] <逐模块适配 breaking change #2>
4. [切换] <更新依赖版本 / 构建配置>
5. [清理] <移除兼容层、废弃代码、旧配置>
6. [验证] <全量测试 + benchmark>
### 每步详细计划
#### Step 1: <标题>
- 改动:<具体操作>
- 验证:<该步骤后的验证命令>
- 回滚:<若失败如何回滚>
- 提交信息:<预设的 commit message>
**增量策略(默认)**的关键技巧:
// 兼容层:旧签名委托到新实现
#[deprecated(note = "Use new_fn() instead")]
pub fn old_fn(x: i32) -> i32 {
new_fn(x as i64) as i32
}
[features]
new-parser = [] # 启用新解析器
大爆炸策略(仅当无法增量时):
┌─────────────────────────────────────────────┐
│ ✋ 迁移计划已就绪 │
├─────────────────────────────────────────────┤
│ │
│ 迁移类型 : <依赖升级 / 语言版本 / …> │
│ 策略 : <incremental / big-bang> │
│ 步骤数 : N 步 │
│ Breaking 变更 : M 项 │
│ 影响文件 : K 个 │
│ │
│ 回复「继续」开始执行 │
│ 回复「dry-run」仅查看计划 │
│ 或修改具体步骤 │
└─────────────────────────────────────────────┘
在此处暂停,等待用户确认。
auto 模式:不暂停,直接按计划执行。若迁移失败则自动回滚到迁移前状态并终止。
若指定 dry-run,输出完整计划后终止。
git checkout -b migrate/<简短描述> 2>&1
for each step in 迁移计划:
1. 执行改动
2. 构建验证:根据项目构建系统执行编译/导入验证(若用户提供了命令则优先使用)
3. 若构建失败 → 分析错误,修复,重试
4. 运行测试:根据项目配置执行测试(若用户提供了命令则优先使用)
5. 测试结果:
✅ 通过 → 提交该步骤,继续下一步
❌ 失败 → 区分原因:
- 迁移适配遗漏 → 修复,重试
- 新版本行为变化(预期中的) → 更新测试,记录
- 新版本 bug → 记录,评估是否继续
- 三次修复仍失败 → 暂停,告知用户(`auto` 模式:自动回滚到上一个成功的 commit 并终止)
6. 提交:
git add <本次改动的具体文件> && git commit -m "<预设的 commit message>"
每步提交,确保每个 commit 都是可构建、可测试的状态。这样出问题时可以精确 git bisect。
Rust 依赖升级:
cargo update -p <crate> 更新单个依赖cargo clippy 是否有新的 lint 警告(新版 clippy 可能更严格)cargo fix --edition 自动迁移,再手动检查结果C++ 构建系统迁移:
#include 搜索路径和链接库路径正确Python 依赖升级:
uv lock --upgrade-package <pkg> 精确升级所有步骤执行完毕后,运行完整验证:
若用户提供了构建/测试/lint 命令则优先使用;否则根据项目构建系统和配置,自行确定并执行构建、测试与静态检查命令;若项目无测试或 linter 则跳过对应步骤。
按 Bench 感知约定执行回归对比。
若项目有可运行的 demo / example:
# 运行示例,确认功能正常
cargo run --example <name> 2>&1
python examples/<name>.py 2>&1
#[allow(deprecated)] / #pragma warning(disable: ...) 等临时抑制清理后再跑一轮完整构建 + 测试,确认清理未引入问题。
禁止使用 git add -A 或 git add .——必须逐文件 add,避免暴露 .env、credentials 等敏感文件或意外的大文件。
git add <本次改动的具体文件> && git commit -m "chore: remove migration scaffolding"
按产物存储约定输出以下报告:
# Migration Report
## 概况
- 时间:<开始时间>
- 耗时:<X 分 Y 秒>
- 迁移类型:<依赖升级 / 语言版本 / 构建系统 / 框架 / API>
- 迁移目标:<描述>
- 策略:incremental / big-bang
- 迁移分支:<branch name>
## 迁移前后对比
| 维度 | 迁移前 | 迁移后 |
|------|--------|--------|
| <依赖/语言/构建系统> 版本 | <旧> | <新> |
| 构建状态 | ✅ | ✅ |
| 测试(通过/总数) | N/N | N/N |
| Benchmark | <基线> | <结果> |
## Breaking Changes 适配记录
| 变更 | 影响文件数 | 适配方式 | 备注 |
|------|------------|----------|------|
| <描述> | N | <如何改的> | <注意事项> |
## 执行步骤记录
| 步骤 | 描述 | Commit | 状态 |
|------|------|--------|------|
| 1 | <描述> | <hash> | ✅ |
| 2 | <描述> | <hash> | ✅ |
## 遇到的问题
### 问题 1:<标题>
- 现象:<描述>
- 原因:<分析>
- 解决:<如何处理>
## 后续建议
- <是否有废弃 API 警告需要后续处理>
- <是否需要更新文档(/doc)>
- <是否建议用 /improve 对迁移后的代码做深度打磨>
- <是否有其他依赖也需要升级>
/debug:迁移过程中构建或测试失败时调用 /debug 定位根因,再回到 /migrate 修复/improve:迁移完成后对代码做深度打磨(上面的"后续建议"已提示)/doc:API 有变化时用 /doc api 和 /doc changelog 同步文档/bench:性能敏感依赖升级后必须跑 benchmark 对比基线/refactor breaking:迁移揭示出的结构性问题应分离到 refactor 单独处理,/migrate 专注外部 API 适配输出语言跟随用户输入语言。