Claude Code批量迁移五大战役全流程

graph TD
    A[迁移需求分析] --> B{迁移类型判断}
    B --> C1[战役一: 语言迁移<br/>JS → TypeScript]
    B --> C2[战役二: 框架升级<br/>Vue2 → Vue3]
    B --> C3[战役三: 组件迁移<br/>Class → Hooks]
    B --> C4[战役四: API迁移<br/>REST → GraphQL]
    B --> C5[战役五: 样式迁移<br/>CSS → Tailwind]

    C1 & C2 & C3 & C4 & C5 --> D[CLAUDE.md迁移配置]
    D --> E{规模评估}
    E -->|<50文件| F[单Agent直接迁移]
    E -->|50-200文件| G[/batch并行分解]
    E -->|>200文件| H[分阶段+worktree隔离]

    F & G & H --> I[自动化测试验证]
    I --> J[人工Review + 合并]

# CLAUDE.md — 迁移专用配置

## 项目概况
- 项目名称: my-enterprise-app
- 技术栈: Vue 2.6 + Vuex + JavaScript + SCSS
- 文件总数: 约850个源文件
- 测试覆盖率: 42%

## 当前迁移阶段
- [x] Phase 1: JavaScript → TypeScript（已完成60%）
- [ ] Phase 2: Vue 2 → Vue 3 Composition API
- [ ] Phase 3: SCSS → Tailwind CSS
- [ ] Phase 4: Vuex → Pinia

## 迁移规则
1. 每次迁移只处理一个模块，不要跨模块修改
2. 迁移后必须保持现有测试通过
3. 优先迁移工具函数和类型定义，最后迁移UI组件
4. 不允许在迁移过程中引入新功能
5. 每个文件迁移后必须能独立编译

## 禁止操作
- 不要删除任何现有测试
- 不要修改构建配置（webpack/vite）除非迁移要求
- 不要在迁移PR中混合非迁移改动

## 文件路径约定
- 类型定义: src/types/
- 工具函数: src/utils/
- 组件: src/components/
- 页面: src/views/
- 状态管理: src/store/

# 第一步：让Claude Code分析项目并生成类型蓝图
claude -p "分析整个src/目录下的JavaScript文件，列出：
1. 所有导出的函数签名及其参数/返回类型
2. 所有接口和类型别名（从JSDoc中提取）
3. 第三方依赖中缺少@types/声明的包
4. 建议的迁移优先级排序

输出为markdown表格格式。" --output-format text > migration-type-audit.md

# 基于审计报告，批量安装缺失的类型声明
claude -p "读取 migration-type-audit.md，生成npm命令来安装所有缺失的@types/包。
只输出可以直接执行的命令，不要任何解释。" --allowedTools "Bash(read_only)"

# 对单个模块进行类型迁移
claude "将 src/utils/ 目录下所有 .js 文件迁移为 .ts：
1. 添加完整的类型注解，不使用any
2. 将JSDoc @param/@returns 转为TypeScript类型语法
3. 确保tsconfig strict模式编译通过
4. 保留所有现有导出签名不变
5. 运行 tsc --noEmit 验证"

# 在Claude Code交互会话中执行
/batch 将 src/components/ 下所有 .js 文件迁移为 .tsx，遵循以下规则：
- 添加Props接口类型定义
- 将所有React.PropTypes转换为TypeScript类型
- 确保每个组件文件独立可编译
- 不修改组件逻辑或UI表现

sequenceDiagram
    participant U as 开发者
    participant C as Claude Code
    participant P as 规划Agent
    participant W1 as Worktree Agent 1
    participant W2 as Worktree Agent 2
    participant W3 as Worktree Agent 3

    U->>C: /batch JS→TS迁移 src/components/
    C->>P: 分析并分解迁移单元
    P->>C: 返回15个独立迁移单元
    C->>W1: Agent 1: Button, Modal, Tooltip
    C->>W2: Agent 2: Table, Form, Input
    C->>W3: Agent 3: Card, Tab, Dropdown
    Note over W1,W3: 并行在独立worktree中执行
    W1-->>C: 迁移完成 + diff
    W2-->>C: 迁移完成 + diff
    W3-->>C: 迁移完成 + diff
    C->>U: 汇总15个文件迁移结果

# 使用-p模式生成迁移审计报告
claude -p "扫描整个项目，生成Vue 2到Vue 3迁移审计报告：
1. 使用了哪些Vue 2专有API（$set, $delete, $on, $off, filters等）
2. 依赖的Vue 2专有库（vue-router v3, vuex v3等）
3. 使用了v-model的组件（Vue 3语法变更）
4. 使用了$children的组件（已移除）
5. 使用了$listeners的组件（已合并到$attrs）
6. 每个组件的迁移复杂度评估（简单/中等/复杂）

输出JSON格式。" --output-format json > vue-migration-audit.json

claude "升级构建配置以支持Vue 3：
1. webpack.config.js中替换vue-loader配置
2. 更新alias: 'vue$' → 'vue/dist/vue.esm-bundler.js'
3. 安装 @vue/compiler-sfc 替代 vue-template-compiler
4. 配置兼容模式 @vue/compat（渐进迁移策略）
5. 运行 webpack --mode development 验证构建通过"

claude "配置Vue兼容模式：
1. 安装 @vue/compat
2. 修改 main.js 入口使用兼容构建
3. 配置全局兼容配置，对已迁移组件禁用兼容警告
4. 创建迁移进度追踪文件，记录哪些组件已完成迁移
5. 启动dev server验证应用正常运行"

# 对简单组件批量迁移
/batch 将 src/components/common/ 目录下的Vue 2组件迁移为Vue 3 Composition API：
- Options API → <script setup> + Composition API
- data() → ref/reactive
- computed → computed()
- methods → 普通函数
- mounted/created → onMounted/onCreated
- props定义 → defineProps<T>()
- emit → defineEmits<T>()
- filters → computed或全局方法
- 移除this.$set和this.$delete调用
每个组件必须在浏览器中无控制台警告运行

claude "迁移 src/views/Dashboard.vue 这个复杂组件：
1. 先读取并分析组件的所有依赖关系
2. 识别使用的所有mixins和它们的实际功能
3. 将mixins转为composables
4. 处理this.$refs在Composition API中的用法
5. 处理this.$router和this.$route的替换
6. 确保所有watch保持原有行为（immediate, deep选项）
7. 运行该组件相关的所有测试"

claude -p "分析src/store/目录下的Vuex store结构，输出：
1. 所有state字段及其类型
2. 所有getters及其依赖的state
3. 所有mutations和对应逻辑
4. 所有actions及其异步操作
5. 模块间的依赖关系图

格式：每个store模块一个section。" > store-analysis.md

# 基于分析结果，批量生成Pinia store
/batch 将 src/store/ 下每个Vuex模块迁移为Pinia store：
- state → reactive state定义
- mutations → 直接state修改或actions
- getters → computed getters
- actions → Pinia actions（保持异步逻辑）
- 模块注册 → defineStore独立定义
- 保持所有导出接口不变，组件端零修改

# 安装React现代化Skill
claude skill add https://github.com/cloudorcl-lab/agents-claude/tree/main/plugins/framework-migration/skills/react-modernization

# 第一步：分类组件
claude -p "扫描 src/ 目录下所有React Class组件，按迁移复杂度分类：
- 简单：只有render和基本state，无生命周期方法
- 中等：使用componentDidMount/componentDidUpdate
- 复杂：使用shouldComponentUpdate、getSnapshotBeforeUpdate、Error Boundary
- 特殊：使用HOC包装或context直接访问

输出：{category: {files: [...], count: N}}" --output-format json > react-class-audit.json

/batch 将以下简单React Class组件迁移为函数组件+Hooks：
[从审计结果中导入简单组件列表]

规则：
- class Component extends React.Component → function Component
- constructor + this.state → const [x, setX] = useState()
- this.setState → setter函数直接调用
- this.props → props参数解构
- this.handleChange → const handleChange = useCallback(...)
- 保持所有PropTypes定义不变

claude "迁移 src/components/DataGrid.jsx：
这是一个使用多个生命周期的中等复杂组件。

转换规则：
1. componentDidMount → useEffect(() => { ... }, [])
2. componentDidUpdate(prevProps) → useEffect(() => { ... }, [dep1, dep2])
3. componentWillUnmount → useEffect return cleanup
4. this.state = {a, b, c} → const [a, setA] = useState() + const [b, setB] = useState()
5. this.setState({a: 1, b: 2}) → 批量调用setA(1); setB(2)
6. 使用React.memo替代PureComponent/shouldComponentUpdate

关键：仔细分析componentDidUpdate中哪些props变化时触发逻辑，
生成精确的useEffect依赖数组。"

// Claude Code应该知道Error Boundary必须保留为Class组件
// 在CLAUDE.md中明确指示：
// "Error Boundary组件保留为Class组件，不做迁移"

// 但可以将内部逻辑抽取为自定义Hook
function useErrorHandler() {
  const [error, setError] = useState<Error | null>(null);
  const resetError = useCallback(() => setError(null), []);
  return { error, setError, resetError };
}

# 从REST API调用代码逆向推断数据模型
claude -p "扫描src/目录下所有API调用代码（fetch/axios调用），分析并输出：
1. 所有API端点URL及其HTTP方法
2. 每个端点的请求参数结构
3. 每个端点的响应数据结构
4. 数据实体之间的关系（从嵌套响应推断）
5. 推断出的GraphQL Schema定义（type Query, type Mutation, type实体）

输出GraphQL Schema SDL格式。" > inferred-schema.graphql

claude "基于 inferred-schema.graphql 和后端API文档（如果有），完成以下工作：
1. 验证推断的Schema是否覆盖所有现有REST端点
2. 添加缺失的输入类型（Input types）
3. 为每个Query/Mutation添加描述注释
4. 设计分页策略（Cursor-based或Offset-based）
5. 生成schema.graphql最终版本"

claude "配置Apollo Client：
1. 安装 @apollo/client 和 graphql 依赖
2. 创建Apollo Client实例，配置缓存策略
3. 设置认证链接（从现有axios拦截器迁移）
4. 配置错误处理策略
5. 创建自定义Hook替代现有API调用函数

参考现有 src/services/api.js 中的认证和错误处理逻辑。"

# 逐页面替换REST调用为GraphQL
claude "迁移 src/pages/UserManagement/ 页面的数据获取：
1. 将 getUserList() REST调用替换为 useQuery(GET_USERS)
2. 将 createUser() REST调用替换为 useMutation(CREATE_USER)
3. 将 updateUser() REST调用替换为 useMutation(UPDATE_USER) + cache.updateQuery
4. 将 deleteUser() REST调用替换为 useMutation(DELETE_USER) + cache.evict
5. 处理加载状态和错误状态（对应现有loading/error state）
6. 确保分页行为与原REST分页一致"

/batch 将 src/pages/ 下所有页面的REST API调用迁移为GraphQL：
- 每个页面独立迁移
- 先生成该页面的GraphQL query/mutation定义
- 替换数据获取逻辑为Apollo Hook
- 保持UI渲染逻辑不变
- 保持错误处理和加载状态行为一致

claude "设计GraphQL缓存策略，替代现有的React Query缓存配置：
1. 读取现有React Query的queryKey和staleTime配置
2. 为Apollo Cache设计对应的typePolicy
3. 配置keyFields（决定缓存ID生成规则）
4. 配置merge函数处理分页数据合并
5. 配置read函数处理缓存数据读取
6. 生成完整的cache配置文件"

claude -p "扫描 src/ 目录下所有样式文件，分析：
1. 使用了哪些CSS特性（flexbox、grid、animation、media query等）
2. 使用的CSS预处理器特性（变量、mixin、嵌套、@extend等）
3. 自定义设计系统的值（颜色、字号、间距、阴影等）
4. 全局样式 vs 组件样式的比例
5. 哪些样式可以被Tailwind内置utility覆盖
6. 哪些样式需要自定义Tailwind配置

输出结构化报告。" --output-format text > style-audit.md

claude "基于 style-audit.md 分析结果，生成Tailwind配置：
1. 读取 src/styles/variables.scss 中的所有变量
2. 将SCSS变量映射为tailwind.config.js的theme扩展
3. 颜色变量 → theme.extend.colors
4. 字号变量 → theme.extend.fontSize
5. 间距变量 → theme.extend.spacing
6. 阴影变量 → theme.extend.boxShadow
7. 断点变量 → theme.screens
8. 生成完整的tailwind.config.js

确保配置覆盖项目中100%的自定义设计值。"

# 先迁移简单的utility类组件
/batch 将 src/components/ui/ 目录下的基础组件样式迁移为Tailwind：
- 读取每个组件的SCSS module文件
- 将每个CSS属性转换为对应的Tailwind类名
- 使用className替换className+style import
- 处理伪类（hover, focus, active）→ Tailwind修饰符
- 处理响应式 → Tailwind断点前缀（sm:, md:, lg:）
- 处理CSS变量引用 → Tailwind theme()函数
- 删除已迁移的SCSS文件
- 确保视觉表现完全一致（截图对比）

每个组件迁移后生成before/after截图路径

# 对于使用SCSS mixin、@extend等高级特性的样式
claude "迁移 src/components/ChartWidget.scss，这个文件使用了：
1. @include respond-to(breakpoint) mixin → Tailwind响应式前缀
2. @extend %card-base → Tailwind @apply或组合类名
3. CSS Grid复杂布局 → Tailwind grid utilities
4. CSS animation → Tailwind animation utilities + 自定义keyframes
5. SCSS嵌套选择器 → Tailwind group/group-hover 或变体

输出：ChartWidget组件使用Tailwind的完整代码"

# 迁移后自动运行视觉回归测试
claude "配置视觉回归测试流程：
1. 安装 playwright 和 pixelmatch
2. 编写脚本：迁移前对每个页面截图保存为baseline
3. 迁移后再次截图并对比
4. 设置允许的像素差异阈值为0.1%
5. 生成差异报告，标注差异位置
6. 如果差异超过阈值，自动标记需要人工review的文件"

graph LR
    A[战役一: JS→TS] --> B[战役二: Vue2→Vue3]
    B --> C[战役三: Class→Composition API]
    A --> D[战役四: REST→GraphQL]
    B --> E[战役五: SCSS→Tailwind]

    style A fill:#4CAF50,color:#fff
    style B fill:#2196F3,color:#fff
    style C fill:#FF9800,color:#fff
    style D fill:#9C27B0,color:#fff
    style E fill:#F44336,color:#fff

# CLAUDE.md — 联合迁移总控配置

## 全局迁移顺序（严格按序执行）
1. Phase 1: TypeScript基础建设（类型定义 + 工具函数）
2. Phase 2: Vue 3兼容模式启动
3. Phase 3: 基础组件Vue 3迁移（简单组件先行）
4. Phase 4: GraphQL层建设（Schema + Client配置）
5. Phase 5: 页面级API迁移
6. Phase 6: 样式迁移（从ui组件开始）
7. Phase 7: 复杂组件迁移 + 清理兼容模式

## 跨战役规则
- TypeScript迁移和Vue 3迁移不要同时修改同一文件
- 样式迁移不影响组件逻辑，可以与其他战役并行
- API迁移独立于框架迁移，通过Adapter层解耦
- 每个Phase完成后必须通过CI才能开始下一Phase

## 进度追踪
- 每个Phase完成后在migration-progress.md中标记
- 记录每个Phase的实际耗时vs预估耗时
- 记录遇到的阻塞点和解决方案

#!/bin/bash
# migrate.sh — Claude Code迁移编排脚本

set -e

PHASE=${1:-"all"}
PROJECT_DIR=$(pwd)

# 阶段一：TypeScript基础建设
phase1_ts_foundation() {
    echo "=== Phase 1: TypeScript Foundation ==="

    # 生成类型审计报告
    claude -p "分析项目并生成TypeScript迁移审计报告" \
        --output-format json > reports/ts-audit.json

    # 安装类型依赖
    claude -p "根据reports/ts-audit.json生成npm install命令" \
        --allowedTools "Bash(read_only)" | bash

    # 迁移types和utils
    /batch 将src/types/和src/utils/下所有JS文件迁移为TS

    echo "Phase 1 complete."
}

# 阶段二：Vue 3兼容模式
phase2_vue3_compat() {
    echo "=== Phase 2: Vue 3 Compat Mode ==="

    claude "配置Vue 3兼容模式，确保应用正常启动"

    # 运行dev server验证
    npm run dev -- --port 3000 &
    DEV_PID=$!
    sleep 10

    # 检查是否有编译错误
    if curl -s http://localhost:3000 | grep -q "error"; then
        echo "Compat mode setup failed. Check logs."
        kill $DEV_PID
        exit 1
    fi
    kill $DEV_PID

    echo "Phase 2 complete."
}

# 阶段三：组件迁移
phase3_component_migration() {
    echo "=== Phase 3: Component Migration ==="

    # 简单组件批量迁移
    /batch 迁移src/components/common/下所有简单Vue组件为Composition API

    # 中等复杂度逐个迁移
    for component in $(cat reports/medium-complexity-components.txt); do
        claude "迁移 $component 为Vue 3 Composition API"

        # 每个组件迁移后验证
        if ! npm run test -- --grep "$component"; then
            echo "Test failed for $component, reverting..."
            git checkout -- "$component"
        fi
    done

    echo "Phase 3 complete."
}

# 执行指定阶段
case $PHASE in
    "1") phase1_ts_foundation ;;
    "2") phase2_vue3_compat ;;
    "3") phase3_component_migration ;;
    "all")
        phase1_ts_foundation
        phase2_vue3_compat
        phase3_component_migration
        ;;
    *)
        echo "Usage: ./migrate.sh [1|2|3|all]"
        exit 1
        ;;
esac

# .claude/hooks/migration-quality-gate.json
# 在每个迁移步骤后自动运行的质量检查

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "command": "bash -c 'npx tsc --noEmit 2>&1 | head -20'",
        "description": "TypeScript类型检查"
      },
      {
        "matcher": "Write|Edit",
        "command": "bash -c 'npm run lint 2>&1 | tail -5'",
        "description": "代码风格检查"
      },
      {
        "matcher": "Write|Edit",
        "command": "bash -c 'npm run test -- --passWithNoTests 2>&1 | tail -10'",
        "description": "单元测试执行"
      }
    ]
  }
}

# Step 1: 全局评估（用时约15分钟）
claude -p "全面分析这个电商平台项目的迁移需求：
1. JavaScript→TypeScript：估算文件数和复杂度
2. Vue 2→Vue 3：列出所有破坏性API使用
3. Vuex→Pinia：分析store模块依赖
4. REST→GraphQL：从API调用推断数据模型
5. SCSS→Tailwind：分析设计系统token

输出：总体迁移工时估算和风险点" --output-format text > full-migration-plan.md

# Step 2: 分阶段执行（利用-p模式串联）
# Phase 1: TypeScript（2天）
claude -p "执行Phase 1 TypeScript基础迁移..." --max-turns 50

# Phase 2: Vue 3 compat（1天）
claude -p "执行Phase 2 Vue 3兼容模式配置..." --max-turns 30

# Phase 3: 组件迁移（3天，/batch并行）
/batch Vue 3组件迁移，覆盖所有320个组件...

# Step 3: 验证（半天）
claude -p "运行完整测试套件和构建，验证迁移完整性"

## 迁移CLAUDE.md黄金规则

### 写什么
- 当前迁移阶段和已完成进度
- 严格的文件修改范围（精确到目录）
- 每类迁移的转换规则（给出具体代码示例）
- 禁止操作清单（比正面指令更重要）

### 不写什么
- 不要写模糊指令（如"尽量保持一致"）
- 不要写过长配置（超过200行会降低关注度）
- 不要写与迁移无关的项目信息