07
Migrate · workflow

framework-migration

07-framework-migration.md
🚚
P1 source: claude-sessions created: 2026-06-13
◉

WHAT IS THIS

定位

框架、API、语言迁移 workflow。适合 Bun、React Router、TanStack、Cloudflare Workers、SDK 版本、语言 runtime 迁移。

⚡

TRIGGERS

触发场景
▸需要把一个包从旧 API 切到新 API。
▸框架升级后旧生命周期、路由、server function、build 输出变化。
▸多个文件需要机械迁移，但不能破坏语义。
▸迁移后要保证行为等价。
↹

INPUT & OUTPUT

输入 / 产出
↘ INPUT
  • 迁移目标和版本。
  • 官方 migration guide。
  • 受影响文件列表。
  • 当前测试命令。
  • 兼容策略和截止日期。
↗ OUTPUT
  • 迁移计划。
  • 分批 patch。
  • 兼容层删除或保留说明。
  • 等价性验证报告。
🪜

STEPS

编排步骤
  1. 1
    建影响面
    用 rg 找旧 API、旧 import、旧 config、旧 runtime 行为。
  2. 2
    读官方 guide
    只引用和当前版本相关的变更，不凭记忆迁移。
  3. 3
    设计迁移批次
    按 module 或 file fan-out，避免一个 patch 同时改业务逻辑和框架语义。
  4. 4
    先补行为测试
    对核心路径补 regression 或 snapshot，保证迁移前后可比。
  5. 5
    分批迁移
    每批只改一类模式。文件级 agent 可以并行，但写入范围要互斥。
  6. 6
    反向检查
    找旧 API 残留，找兼容层是否真的被用到，找类型 any 和静默 catch。
  7. 7
    全量验证
    跑 lint、typecheck、unit、integration、build、runtime smoke。
⚙

AGENT ROLES

Agent 分工
⚙
Guide Reader
读官方迁移文档。
⚙
Impact Mapper
列受影响文件。
⚙
Batch Workers
按目录或模式迁移。
⚙
Equivalence Reviewer
检查行为等价。
⚙
Test Runner
跑全量验证。
✓

ACCEPTANCE GATE

验收 gate
⊘

FAILURE HANDLING

失败处理
⊘
如果官方 guide 和实际包版本不一致，停止并锁版本。
⊘
如果迁移引发业务行为变化，拆成单独 PR 或 ADR。
⊘
如果测试覆盖不足，先补测试，不直接批量替换。
⌘

TEMPLATE

迁移批次模板
TEMPLATE
| Batch | Pattern | Files | Risk | Tests | Status |
| --- | --- | --- | --- | --- | --- |