migration-guide

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Migration Guide

迁移指南

Transform tool/framework switches from risky leaps into controlled, reversible transitions.

将工具/框架切换从高风险的一跃而起转变为可控、可回滚的过渡过程。

Purpose

用途

Migrations fail when users try to switch everything at once. This skill creates phased migration plans that maintain productivity while transitioning, with rollback options at each phase.

当用户尝试一次性切换所有内容时，迁移往往会失败。本技能会生成多阶段的迁移计划，在过渡期间保持生产效率，且每个阶段都提供回滚选项。

Migration Categories

迁移分类

1. Tool Migration:
   - IDE: Cursor → Claude Code
   - AI: Copilot → Claude
   - Bundler: Webpack → Vite

2. Framework Migration:
   - React → Next.js
   - Express → Fastify
   - REST → GraphQL

3. Workflow Migration:
   - Manual → Automated
   - Monolith → Microservices
   - Local → Cloud

4. Version Migration:
   - Major upgrades (v1 → v2)
   - Breaking changes
   - Deprecation handling

1. Tool Migration:
   - IDE: Cursor → Claude Code
   - AI: Copilot → Claude
   - Bundler: Webpack → Vite

2. Framework Migration:
   - React → Next.js
   - Express → Fastify
   - REST → GraphQL

3. Workflow Migration:
   - Manual → Automated
   - Monolith → Microservices
   - Local → Cloud

4. Version Migration:
   - Major upgrades (v1 → v2)
   - Breaking changes
   - Deprecation handling

Process

流程

Phase 1: Migration Assessment

阶段1：迁移评估

Entry Check

准入检查

IF user provided: current state + target state + reason
    → Proceed to Phase 2
ELSE
    → Assess migration scope first

IF user provided: current state + target state + reason
    → Proceed to Phase 2
ELSE
    → Assess migration scope first

Assessment Questions

评估问题

Question	Purpose
"What are you migrating from?"	Identify source
"What are you migrating to?"	Identify target
"Why are you migrating?"	Validate motivation
"What's your timeline?"	Scope the phases
"Can you run both simultaneously?"	Determine strategy

问题	目的
"你要从什么系统/工具迁移？"	确定迁移源
"你要迁移到什么系统/工具？"	确定迁移目标
"你迁移的原因是什么？"	验证迁移动机
"你的时间规划是怎样的？"	划定阶段范围
"你可以同时运行新旧两个系统/工具吗？"	确定迁移策略

Migration Type Detection

迁移类型检测

IF source and target can coexist:
    → Recommend: Parallel Migration (lowest risk)
    → Run both, gradually shift traffic/usage

IF must be atomic swap:
    → Recommend: Big Bang Migration (higher risk)
    → Requires thorough testing, clear rollback

IF partial migration possible:
    → Recommend: Strangler Fig Pattern
    → New features in new system, old stays

IF source and target can coexist:
    → Recommend: Parallel Migration (lowest risk)
    → Run both, gradually shift traffic/usage

IF must be atomic swap:
    → Recommend: Big Bang Migration (higher risk)
    → Requires thorough testing, clear rollback

IF partial migration possible:
    → Recommend: Strangler Fig Pattern
    → New features in new system, old stays

Phase 2: Compatibility Mapping

阶段2：兼容性映射

Entry Check

准入检查

IF migration assessed:
    → Map compatibility
ELSE
    → Return to Phase 1

IF migration assessed:
    → Map compatibility
ELSE
    → Return to Phase 1

Feature Mapping Table

功能映射表

markdown

undefined

markdown

undefined

Feature Compatibility

Feature	[Source]	[Target]	Migration Effort
[feature 1]	✓ How it works	✓ Equivalent	Low/Med/High
[feature 2]	✓ How it works	⚠ Different approach	Med
[feature 3]	✓ How it works	✗ Not available	High (workaround needed)
[feature 4]	✗ N/A	✓ New capability	Gain

undefined

Feature	[Source]	[Target]	Migration Effort
[feature 1]	✓ How it works	✓ Equivalent	Low/Med/High
[feature 2]	✓ How it works	⚠ Different approach	Med
[feature 3]	✓ How it works	✗ Not available	High (workaround needed)
[feature 4]	✗ N/A	✓ New capability	Gain

undefined

Breaking Changes Identification

破坏性变更识别

FOR each feature in source:
    Compare with target:

    IF identical API/behavior:
        → Mark: Direct migration

    IF different API, same result:
        → Mark: Adaptation needed
        → Document: transformation required

    IF no equivalent:
        → Mark: Blocker or accept loss
        → Document: workaround or alternative

FOR each feature in source:
    Compare with target:

    IF identical API/behavior:
        → Mark: Direct migration

    IF different API, same result:
        → Mark: Adaptation needed
        → Document: transformation required

    IF no equivalent:
        → Mark: Blocker or accept loss
        → Document: workaround or alternative

Dependency Analysis

依赖分析

LIST all dependencies:
    - Which work with both?
    - Which need replacement?
    - Which are source-specific?
    - Which are target-specific?

OUTPUT:
| Dependency | Source | Target | Action |
|------------|--------|--------|--------|
| [dep] | v1.x | v2.x | Upgrade |
| [dep] | ✓ | ✗ | Replace with [alt] |

LIST all dependencies:
    - Which work with both?
    - Which need replacement?
    - Which are source-specific?
    - Which are target-specific?

OUTPUT:
| Dependency | Source | Target | Action |
|------------|--------|--------|--------|
| [dep] | v1.x | v2.x | Upgrade |
| [dep] | ✓ | ✗ | Replace with [alt] |

Phase 3: Migration Plan Generation

阶段3：迁移计划生成

Entry Check

准入检查

IF compatibility mapped:
    → Generate phased plan
ELSE
    → Return to Phase 2

IF compatibility mapped:
    → Generate phased plan
ELSE
    → Return to Phase 2

Phase Structure

阶段结构

markdown

undefined

markdown

undefined

Migration Plan: [Source] → [Target]

Phase 0: Preparation (Before Starting)

Duration: [estimate] Risk: Low

Actions:

Document current configuration
Create backup/snapshot
Set up target environment
Verify team readiness

Rollback: N/A (nothing changed yet)

Duration: [estimate] Risk: Low

Actions:

Document current configuration
Create backup/snapshot
Set up target environment
Verify team readiness

Rollback: N/A (nothing changed yet)

Phase 1: Parallel Setup

Duration: [estimate] Risk: Low

Actions:

Install [target] alongside [source]
Configure [target] with basic settings
Verify [target] works independently
Keep using [source] for production work

Rollback: Remove [target], continue with [source]

Success Criteria:

[Target] runs without errors
No impact on [source] workflow

Duration: [estimate] Risk: Low

Actions:

Install [target] alongside [source]
Configure [target] with basic settings
Verify [target] works independently
Keep using [source] for production work

Rollback: Remove [target], continue with [source]

Success Criteria:

[Target] runs without errors
No impact on [source] workflow

Phase 2: Feature Migration

Phase 3: Workflow Transition

Duration: [estimate] Risk: Medium

Actions:

Switch primary workflow to [target]
Use [source] only for unsupported features
Document any gaps or issues
Adjust team processes

Rollback: Return to [source] as primary

Success Criteria:

80%+ of work done in [target]
Team comfortable with new workflow

Duration: [estimate] Risk: Medium

Actions:

Switch primary workflow to [target]
Use [source] only for unsupported features
Document any gaps or issues
Adjust team processes

Rollback: Return to [source] as primary

Success Criteria:

80%+ of work done in [target]
Team comfortable with new workflow

Phase 4: Full Cutover

Duration: [estimate] Risk: Low (if previous phases succeeded)

Actions:

Disable/uninstall [source]
Remove [source] configurations
Update documentation
Archive [source] backups

Rollback: Reinstall [source] from backup

Success Criteria:

[Source] fully removed
No references to [source] in workflow

---

Duration: [estimate] Risk: Low (if previous phases succeeded)

Actions:

Disable/uninstall [source]
Remove [source] configurations
Update documentation
Archive [source] backups

Rollback: Reinstall [source] from backup

Success Criteria:

[Source] fully removed
No references to [source] in workflow

---

Phase 4: Specific Migration Guides

阶段4：特定场景迁移指南

Tool-Specific Templates

工具专属迁移模板

Cursor → Claude Code Migration

Cursor 迁移到 Claude Code

markdown

undefined

markdown

undefined

Cursor → Claude Code

What Changes

Cursor	Claude Code
GUI-based	Terminal-based
.cursorrules	CLAUDE.md
Cmd+K	Direct prompt
Tab completion	Different paradigm

Cursor	Claude Code
GUI-based	Terminal-based
.cursorrules	CLAUDE.md
Cmd+K	Direct prompt
Tab completion	Different paradigm

Phase 1: Parallel (Keep Both)

Install Claude Code:

npm install -g @anthropic-ai/claude-code

Run from project:
```
claude
```
Use for multi-file tasks only

Install Claude Code:

npm install -g @anthropic-ai/claude-code

Run from project:
```
claude
```
Use for multi-file tasks only

Phase 2: Translate Configuration

Convert .cursorrules to CLAUDE.md:

markdown

undefined

Convert .cursorrules to CLAUDE.md:

markdown

undefined

From .cursorrules

[content]

To CLAUDE.md

[translated content]

undefined

[translated content]

undefined

Phase 3: Workflow Integration

阶段3：工作流集成

Keep Cursor for: Quick edits, tab completion
Use Claude Code for: Complex tasks, multi-file, planning

以下场景保留使用Cursor：快速编辑、补全提示
以下场景使用Claude Code：复杂任务、多文件操作、规划

Phase 4: Optional Full Switch

阶段4：可选的完全切换

Only if comfortable. Hybrid is valid long-term.

undefined

仅当你使用顺畅时再执行。长期混用也是合理的方案。

undefined

Copilot → Claude Migration

Copilot 迁移到 Claude

markdown

undefined

markdown

undefined

GitHub Copilot → Claude Code

Paradigm Shift

Copilot: Reactive (suggests next line)
Claude: Agentic (executes full tasks)

Copilot: Reactive (suggests next line)
Claude: Agentic (executes full tasks)

Phase 1: Keep Both

Keep Copilot active in IDE
Add Claude Code for tasks
Use Copilot for: Writing new code
Use Claude for: "Do X for me"

Keep Copilot active in IDE
Add Claude Code for tasks
Use Copilot for: Writing new code
Use Claude for: "Do X for me"

Phase 2: Task Differentiation


Small (single line) → Copilot
Medium (function) → Either
Large (multi-file) → Claude Code
Planning → Claude Code (Plan Mode)

```


Small (single line) → Copilot
Medium (function) → Either
Large (multi-file) → Claude Code
Planning → Claude Code (Plan Mode)

```

Phase 3: Evaluate Value

阶段3：价值评估

After 2 weeks:

Which saves more time?
Which produces better code?
TCO comparison

使用2周后评估：

哪个工具更节省时间？
哪个生成的代码质量更高？
总体拥有成本对比

Phase 4: Decide

阶段4：决策

Keep both (common)
Drop Copilot (if Claude covers needs)
Drop Claude (if Copilot sufficient)

---

保留两者（常见方案）
弃用Copilot（如果Claude能覆盖所有需求）
弃用Claude（如果Copilot已经足够）

---

Phase 5: Rollback Strategy

阶段5：回滚策略

Entry Check

准入检查

IF migration plan generated:
    → Add rollback details
ELSE
    → Return to Phase 3

IF migration plan generated:
    → Add rollback details
ELSE
    → Return to Phase 3

Rollback Documentation

回滚文档

markdown

undefined

markdown

undefined

Rollback Strategy

Checkpoints

Phase	Checkpoint	Rollback Command
1	Before install	N/A
2	After config	Restore [source] config
3	After workflow	Switch back to [source]
4	After cutover	Reinstall [source]

Phase	Checkpoint	Rollback Command
1	Before install	N/A
2	After config	Restore [source] config
3	After workflow	Switch back to [source]
4	After cutover	Reinstall [source]

Data Preservation

Backup location: [path]
Backup command: [command]
Restore command: [command]

Backup location: [path]
Backup command: [command]
Restore command: [command]

Emergency Rollback

If critical failure during migration:

Stop current action
Run: [rollback command]
Verify: [verification steps]
Document: What failed and why

---

If critical failure during migration:

Stop current action
Run: [rollback command]
Verify: [verification steps]
Document: What failed and why

---

Self-Check (Read before every response)

自检（每次生成回复前阅读）

□ Did I identify the migration type? → Parallel vs Big Bang vs Strangler changes everything

□ Is every phase reversible? → No rollback = no safety net

□ Did I map feature compatibility? → Surprise gaps kill migrations

□ Are phases small enough? → Large phases = large risks

□ Did I include success criteria? → "Done" must be measurable

□ Is the timeline realistic? → Rushed migrations fail

□ Did I account for team learning curve? → New tool = temporary slowdown

□ 我是否识别了迁移类型？ → 并行迁移、一刀切迁移、绞杀者模式的选择会影响整个方案

□ 每个阶段是否都是可回滚的？ → 没有回滚方案=没有安全网

□ 我是否完成了功能兼容性映射？ → 意外的功能缺口会导致迁移失败

□ 阶段拆分是否足够细？ → 阶段越大=风险越高

□ 我是否包含了成功判定标准？ → "完成"必须是可衡量的

□ 时间规划是否现实？ → 仓促的迁移更容易失败

□ 我是否考虑了团队的学习曲线？ → 新工具会带来暂时的效率下降

Integration with Vibery

与Vibery的集成

AFTER migration planned:
    Suggest relevant components:
    - "project-blueprint for new project setup"
    - "workflow-composer to automate new workflows"
    - "[target]-pro agent for learning new tool"

AFTER migration planned:
    Suggest relevant components:
    - "project-blueprint for new project setup"
    - "workflow-composer to automate new workflows"
    - "[target]-pro agent for learning new tool"