Back to Details

full-codebase-migrator

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Full Codebase Migrator

全代码库迁移工具

A production-grade migration planning system that leverages the full 1M token context window to ingest an entire codebase, understand its architecture end-to-end, and produce a comprehensive, file-by-file migration plan. This is not a partial analysis -- it reads every file, traces every dependency, and outputs an actionable plan that a team can execute sequentially without conflicts.
这是一套生产级别的迁移规划系统，利用完整的1M Token上下文窗口读取整个代码库，全面理解其架构，并生成详尽的逐文件迁移计划。这并非局部分析——它会读取每一个文件，追踪每一处依赖，输出可执行的计划，团队可按顺序执行且不会产生冲突。

Supported Migration Types

支持的迁移类型

MigrationFromTo
LanguageJavaScript (.js/.jsx)TypeScript (.ts/.tsx)
Component ModelReact Class ComponentsReact Functional + Hooks
FrameworkCreate React AppNext.js / Vite
FrameworkExpress.jsFastify / Hono / Elysia
FrameworkVue 2 (Options API)Vue 3 (Composition API)
FrameworkAngular.jsAngular (modern)
StylingCSS / SCSS / CSS ModulesTailwind CSS
StylingStyled ComponentsCSS Modules / Tailwind
StateRedux (classic)Redux Toolkit / Zustand / Jotai
TestingJest + EnzymeVitest + Testing Library
BuildWebpackVite / Turbopack / esbuild
MonorepoSingle repoTurborepo / Nx workspace
ORMSequelize / TypeORMPrisma / Drizzle
RuntimeNode.js (CommonJS)Node.js (ESM) / Bun / Deno
Package Managernpmpnpm / yarn (berry)
CustomAnyAny (user-defined rules)
迁移类型源技术目标技术
语言迁移JavaScript (.js/.jsx)TypeScript (.ts/.tsx)
组件模型迁移React Class ComponentsReact Functional + Hooks
框架迁移Create React AppNext.js / Vite
框架迁移Express.jsFastify / Hono / Elysia
框架迁移Vue 2 (Options API)Vue 3 (Composition API)
框架迁移Angular.jsAngular (modern)
样式方案迁移CSS / SCSS / CSS ModulesTailwind CSS
样式方案迁移Styled ComponentsCSS Modules / Tailwind
状态管理迁移Redux (classic)Redux Toolkit / Zustand / Jotai
测试方案迁移Jest + EnzymeVitest + Testing Library
构建工具迁移WebpackVite / Turbopack / esbuild
仓库架构迁移单仓库Turborepo / Nx workspace
ORM迁移Sequelize / TypeORMPrisma / Drizzle
运行时迁移Node.js (CommonJS)Node.js (ESM) / Bun / Deno
包管理器迁移npmpnpm / yarn (berry)
自定义迁移任意技术任意技术（用户自定义规则）

When to Use

适用场景

  • You are planning a major technology migration and need a complete inventory before starting
  • You want to understand the full blast radius of a framework or language change
  • You need to estimate effort and risk before committing to a migration
  • You want a deterministic execution order that respects the dependency graph
  • You need to hand off a migration plan to a team with clear, file-level instructions
  • 你正在规划重大技术迁移，需要在启动前完成完整的代码库盘点
  • 你想了解框架或语言变更的全面影响范围
  • 你需要在投入迁移前估算工作量和风险
  • 你需要遵循依赖图谱的确定性执行顺序
  • 你需要向团队移交包含清晰文件级说明的迁移计划

When NOT to Use

不适用场景

  • Single-file conversions (just do them directly)
  • Codebases with fewer than 5 files (overkill)
  • When you want to execute the migration immediately (this skill plans; use agent-army to execute)
  • 单文件转换（直接手动处理即可）
  • 文件数量少于5个的代码库（杀鸡焉用牛刀）
  • 你希望立即执行迁移（本工具仅负责规划；如需执行请使用agent-army）

Architecture

架构

You (Commander)
 |
 |-- Phase 1: Full Ingestion (sequential, read everything)
 |    |-- Glob: discover all source files
 |    |-- Read: ingest every file into context
 |    |-- Bash: collect metadata (line counts, git history, package.json)
 |
 |-- Phase 2: Analysis (in-context reasoning)
 |    |-- Dependency graph construction
 |    |-- Complexity scoring per file
 |    |-- Risk classification
 |    |-- Migration pattern matching
 |
 |-- Phase 3: Plan Generation (Write output)
 |    |-- migration-plan.md (the deliverable)
 |    |-- Optional: migration-plan.json (machine-readable)
你（指挥官）
 |
 |-- 阶段1：全量读取（顺序执行，读取所有内容）
 |    |-- Glob：发现所有源文件
 |    |-- Read：将所有文件读取到上下文
 |    |-- Bash：收集元数据（行数、Git历史、package.json）
 |
 |-- 阶段2：分析（上下文内推理）
 |    |-- 依赖图谱构建
 |    |-- 按文件复杂度评分
 |    |-- 风险分类
 |    |-- 迁移模式匹配
 |
 |-- 阶段3：计划生成（写入输出）
 |    |-- migration-plan.md（交付产物）
 |    |-- 可选：migration-plan.json（机器可读格式）

Execution Protocol

执行流程

Follow these steps precisely when this skill is invoked.
调用本工具时请严格遵循以下步骤。

Step 0: Identify Migration Type

步骤0：确定迁移类型

Before doing anything, clarify the migration scope with the user:
  1. Determine migration type -- Ask the user (or infer from context) what the migration is. Examples: "JS to TS", "CRA to Next.js", "Redux to Zustand".
  2. Determine migration scope -- Full repo or a specific directory? Default to full repo.
  3. Determine output location -- Where to write migration-plan.md. Default to the repo root.
  4. Determine constraints -- Are there files or directories to exclude? Are there deadlines or team size considerations?
If the user has already specified these in their prompt, skip the questions and proceed.
在执行任何操作前，与用户明确迁移范围：
  1. 确定迁移类型 —— 询问用户（或从上下文推断）迁移场景，例如："JS转TS"、"CRA转Next.js"、"Redux转Zustand"。
  2. 确定迁移范围 —— 全仓库还是特定目录？默认全仓库。
  3. 确定输出位置 —— migration-plan.md的写入路径。默认仓库根目录。
  4. 确定约束条件 —— 是否有需要排除的文件或目录？是否有截止日期或团队规模限制？
如果用户已在提示中明确这些信息，可跳过提问直接执行。

Step 1: Full Codebase Ingestion

步骤1：全量代码库读取

This is the critical step that leverages the 1M context window. Read everything.
这是利用1M上下文窗口的关键步骤，读取所有内容。

1a. Discover All Source Files

1a. 发现所有源文件

Use Glob to find all relevant source files. Typical patterns by migration type:

JS to TS:        **/*.{js,jsx,mjs,cjs}
React migration:  **/*.{js,jsx,ts,tsx}
Vue migration:    **/*.{vue,js,ts}
Angular:          **/*.{ts,html,scss,css}
General:          **/*.{js,jsx,ts,tsx,vue,svelte,css,scss,json,yaml,yml,md}

Always exclude:
- node_modules/**
- dist/**
- build/**
- .next/**
- coverage/**
- *.min.js
- *.bundle.js
- package-lock.json
- yarn.lock
- pnpm-lock.yaml
使用Glob查找所有相关源文件。不同迁移类型的典型匹配模式：

JS转TS:        **/*.{js,jsx,mjs,cjs}
React迁移:      **/*.{js,jsx,ts,tsx}
Vue迁移:        **/*.{vue,js,ts}
Angular迁移:    **/*.{ts,html,scss,css}
通用模式:        **/*.{js,jsx,ts,tsx,vue,svelte,css,scss,json,yaml,yml,md}

始终排除以下内容：
- node_modules/**
- dist/**
- build/**
- .next/**
- coverage/**
- *.min.js
- *.bundle.js
- package-lock.json
- yarn.lock
- pnpm-lock.yaml

1b. Collect Metadata

1b. 收集元数据

Run these Bash commands to gather structural information:
  1. Line counts -- 
    wc -l
    on every discovered file. This drives effort estimation.
  2. Package manifest -- Read package.json (or equivalent) for dependencies, scripts, and config.
  3. Config files -- Read tsconfig.json, .babelrc, webpack.config.js, vite.config.ts, .eslintrc, .prettierrc, and any other config files.
  4. Git history -- 
    git log --oneline -20
    for recent context. 
    git log --all --pretty=format:"%h %s" --diff-filter=M -- "*.js"
    (adjusted per migration type) to see which files change most frequently.
  5. Directory structure -- 
    find . -type d -not -path '*/node_modules/*' -not -path '*/.git/*'
    to map the project layout.
运行以下Bash命令收集结构信息：
  1. 行数统计 —— 对所有发现的文件执行
    wc -l
    ，用于工作量估算。
  2. 包清单 —— 读取package.json（或等效文件）获取依赖、脚本和配置。
  3. 配置文件 —— 读取tsconfig.json、.babelrc、webpack.config.js、vite.config.ts、.eslintrc、.prettierrc及其他配置文件。
  4. Git历史 —— 执行
    git log --oneline -20
    获取近期上下文。执行
    git log --all --pretty=format:"%h %s" --diff-filter=M -- "*.js"
    （根据迁移类型调整）查看变更最频繁的文件。
  5. 目录结构 —— 执行
    find . -type d -not -path '*/node_modules/*' -not -path '*/.git/*'
    映射项目布局。

1c. Read Every Source File

1c. 读取所有源文件

This is the key differentiator. Read EVERY source file discovered in 1a. Use the Read tool systematically:
  1. Start with entry points: 
    index.js
    , 
    App.js
    , 
    main.js
    , 
    server.js
    , or equivalents.
  2. Read config files next: tsconfig, webpack, vite, eslint, babel configs.
  3. Read shared utilities, types, and constants.
  4. Read feature files grouped by directory.
  5. Read test files last.
For large codebases (500+ files), use Agent sub-agents to read files in parallel batches. Each agent reads a directory subtree and returns file contents plus a brief summary.
Context budget management:
  • Files under 100 lines: read in full
  • Files 100-500 lines: read in full
  • Files 500-1000 lines: read in full (prioritize these -- they are the riskiest to migrate)
  • Files 1000+ lines: read first 500 lines + last 100 lines + any class/function declarations. Flag for manual review.
  • If the total codebase exceeds ~800K tokens of source, prioritize: entry points > shared code > feature code > tests > styles. Note which files were partially read or skipped.
这是本工具的核心差异化特性，读取1a中发现的每一个源文件。系统地使用Read工具：
  1. 从入口文件开始：
    index.js
    、
    App.js
    、
    main.js
    、
    server.js
    或等效文件。
  2. 接下来读取配置文件：tsconfig、webpack、vite、eslint、babel配置。
  3. 读取共享工具、类型定义和常量文件。
  4. 按目录分组读取功能文件。
  5. 最后读取测试文件。
对于大型代码库（500+文件），使用Agent子代理并行批量读取文件。每个代理读取一个目录子树，并返回文件内容及简要摘要。
上下文预算管理：
  • 少于100行的文件：完整读取
  • 100-500行的文件：完整读取
  • 500-1000行的文件：完整读取（优先处理——这些文件迁移风险最高）
  • 1000+行的文件：读取前500行 + 最后100行 + 所有类/函数声明，标记为需人工审核
  • 如果代码库总内容超过约800K Token，按优先级读取：入口文件 > 共享代码 > 功能代码 > 测试文件 > 样式文件。记录哪些文件被部分读取或跳过。

Step 2: Dependency Graph Construction

步骤2：依赖图谱构建

With the full codebase in context, build the dependency graph:
在上下文加载完整代码库后，构建依赖图谱：

2a. Import Analysis

2a. 导入分析

For every file, extract:
  • Static imports: 
    import X from './path'
    , 
    const X = require('./path')
  • Dynamic imports: 
    import('./path')
    , 
    require.resolve('./path')
  • Re-exports: 
    export { X } from './path'
  • Side-effect imports: 
    import './styles.css'
  • Type-only imports (TS): 
    import type { X } from './path'
Build an adjacency list:
{
  "src/App.tsx": {
    "imports": ["src/components/Header.tsx", "src/hooks/useAuth.ts", "src/utils/api.ts"],
    "importedBy": ["src/index.tsx"],
    "externalDeps": ["react", "react-router-dom"]
  }
}
对每个文件提取：
  • 静态导入：
    import X from './path'
    、
    const X = require('./path')
  • 动态导入：
    import('./path')
    、
    require.resolve('./path')
  • 重导出：
    export { X } from './path'
  • 副作用导入：
    import './styles.css'
  • 仅类型导入（TS）：
    import type { X } from './path'
构建邻接表：
{
  "src/App.tsx": {
    "imports": ["src/components/Header.tsx", "src/hooks/useAuth.ts", "src/utils/api.ts"],
    "importedBy": ["src/index.tsx"],
    "externalDeps": ["react", "react-router-dom"]
  }
}

2b. Identify Layers

2b. 分层分类

Classify every file into one of these layers (top = most depended upon):
  1. Foundation -- Types, interfaces, constants, enums, config. Imported by many, imports few.
  2. Utilities -- Helper functions, formatters, validators. Imported by features, imports foundation.
  3. Services -- API clients, data access, state management. Imports utilities and foundation.
  4. Components/Features -- UI components, route handlers, feature modules. Imports services, utilities, foundation.
  5. Pages/Routes -- Top-level page compositions. Imports components.
  6. Entry Points -- index.js, App.js, server.js. Imports pages.
  7. Tests -- Test files. Import everything, imported by nothing.
  8. Config -- Build configs, linter configs. Usually standalone.
将每个文件归类到以下层级（顶层为被依赖最多的文件）：
  1. 基础层 —— 类型、接口、常量、枚举、配置。被大量文件导入，自身导入极少。
  2. 工具层 —— 辅助函数、格式化工具、验证器。被功能文件导入，依赖基础层。
  3. 服务层 —— API客户端、数据访问、状态管理。依赖工具层和基础层。
  4. 组件/功能层 —— UI组件、路由处理器、功能模块。依赖服务层、工具层、基础层。
  5. 页面/路由层 —— 顶级页面组合。依赖组件层。
  6. 入口层 —— index.js、App.js、server.js。依赖页面层。
  7. 测试层 —— 测试文件。依赖所有层级，不被任何文件导入。
  8. 配置层 —— 构建配置、校验器配置。通常独立存在。

2c. Identify Cycles

2c. 循环依赖检测

Detect circular dependencies. These are migration hazards -- a cycle means you cannot migrate files independently. Flag all cycles and recommend resolution strategies.
检测循环依赖，这是迁移隐患——循环意味着无法独立迁移文件。标记所有循环并推荐解决策略。

2d. Identify External Dependencies

2d. 外部依赖识别

List all third-party packages and classify them:
  • Compatible: Works with both source and target (no changes needed)
  • Needs Update: Has a version compatible with the target (update version)
  • Needs Replacement: Incompatible with target (find alternative)
  • Needs Wrapper: Can work with an adapter/wrapper pattern
  • Must Remove: No path forward (rewrite functionality)
列出所有第三方包并分类：
  • 兼容：同时适用于源技术和目标技术（无需更改）
  • 需更新：存在兼容目标技术的版本（更新版本）
  • 需替换：与目标技术不兼容（寻找替代方案）
  • 需适配：可通过适配器/包装器模式兼容
  • 必须移除：无可行迁移路径（重写功能）

Step 3: File-by-File Analysis

步骤3：逐文件分析

For every source file, produce a migration assessment:
undefined
对每个源文件生成迁移评估：
undefined

[relative/path/to/file.js]

[relative/path/to/file.js]

  • Lines: 245
  • Layer: Component
  • Complexity: Medium
  • Imports: 8 internal, 3 external
  • Imported by: 4 files
  • Migration difficulty: 3/5
  • Estimated effort: 30 minutes
  • Risk level: Medium
Current patterns found:
  • Class component with 3 lifecycle methods (componentDidMount, componentDidUpdate, componentWillUnmount)
  • Local state with this.setState (5 occurrences)
  • Refs via createRef (2 occurrences)
  • HOC wrapper (withRouter)
Required changes:
  1. Convert class to function component
  2. Replace lifecycle methods with useEffect hooks
  3. Replace this.state/this.setState with useState hooks
  4. Replace createRef with useRef hooks
  5. Replace withRouter HOC with useRouter/useNavigate hooks
  6. Add TypeScript types for props (currently PropTypes)
  7. Add TypeScript types for state shape
  8. Update imports from '.js' to '.ts' extensions (if applicable)
Dependencies that must migrate first:
  • src/types/user.ts (needs TypeScript types defined)
  • src/hooks/useAuth.ts (referenced hook must exist)
Risk factors:
  • Complex componentDidUpdate with multiple conditions -- requires careful useEffect dependency array
  • Ref forwarding pattern may need forwardRef wrapper
Testing impact:
  • src/tests/UserProfile.test.js must be updated (enzyme shallow render -> testing library render)
undefined
  • 行数：245
  • 层级：组件层
  • 复杂度：中等
  • 导入：8个内部依赖，3个外部依赖
  • 被导入：4个文件
  • 迁移难度：3/5
  • 估算工作量：30分钟
  • 风险等级：中等
发现的当前模式：
  • 包含3个生命周期方法的类组件（componentDidMount、componentDidUpdate、componentWillUnmount）
  • 使用this.setState的本地状态（5处）
  • 使用createRef的引用（2处）
  • HOC包装器（withRouter）
所需变更：
  1. 将类组件转换为函数组件
  2. 用useEffect钩子替换生命周期方法
  3. 用useState钩子替换this.state/this.setState
  4. 用useRef钩子替换createRef
  5. 用useRouter/useNavigate钩子替换withRouter HOC
  6. 为props添加TypeScript类型（当前使用PropTypes）
  7. 为状态结构添加TypeScript类型
  8. 将导入扩展名从'.js'更新为'.ts'（如适用）
需优先迁移的依赖：
  • src/types/user.ts（需定义TypeScript类型）
  • src/hooks/useAuth.ts（引用的钩子必须已存在）
风险因素：
  • 包含多条件的复杂componentDidUpdate——需谨慎处理useEffect依赖数组
  • Ref转发模式可能需要forwardRef包装器
测试影响：
  • src/tests/UserProfile.test.js必须更新（enzyme浅渲染 -> testing library渲染）
undefined

Step 4: Migration Order Calculation

步骤4：迁移顺序计算

Using the dependency graph, calculate the optimal migration order. This is a topological sort with practical adjustments:
利用依赖图谱计算最优迁移顺序，这是结合实际调整的拓扑排序：

4a. Base Order (Topological Sort)

4a. 基础顺序（拓扑排序）

  1. Foundation layer first (types, constants, config)
  2. Utilities second
  3. Services third
  4. Components fourth (leaf components before composite components)
  5. Pages fifth
  6. Entry points sixth
  7. Tests last
  1. 首先迁移基础层（类型、常量、配置）
  2. 其次迁移工具层
  3. 然后迁移服务层
  4. 接着迁移组件层（叶子组件优先于复合组件）
  5. 之后迁移页面层
  6. 再迁移入口层
  7. 最后迁移测试层

4b. Practical Adjustments

4b. 实际调整

Adjust the base order for real-world concerns:
  • Quick wins first: Within each layer, prioritize small/simple files. Early success builds momentum.
  • High-risk files early: Migrate complex files while the team is fresh, not at the end when fatigue sets in.
  • Batch by feature: When possible, group files by feature so a single PR migrates a complete feature.
  • Shared code before consumers: Any file imported by 5+ other files should migrate before its consumers.
  • Break cycles first: If circular dependencies exist, resolve them before migrating either file in the cycle.
针对实际场景调整基础顺序：
  • 优先快速完成：在每个层级内，优先处理小而简单的文件。早期成功可建立团队动力。
  • 高风险文件提前：在团队精力充沛时迁移复杂文件，而非在后期疲劳阶段。
  • 按功能批量迁移：尽可能按功能分组文件，使单个PR完成一个完整功能的迁移。
  • 共享代码先于消费者：被5个以上文件导入的文件应优先于其依赖者迁移。
  • 先解决循环依赖：如果存在循环依赖，先解决再迁移循环中的任何文件。

4c. Phase Grouping

4c. 阶段分组

Organize files into migration phases. Each phase should:
  • Be completable in 1-3 days by one developer
  • Contain files that can all be migrated without touching files in later phases
  • Result in a buildable, testable codebase when complete
  • Map to a single PR or small set of PRs
undefined
将文件组织为迁移阶段。每个阶段应：
  • 单个开发者可在1-3天内完成
  • 包含的文件可独立迁移，无需触及后续阶段的文件
  • 完成后代码库可构建、可测试
  • 对应单个PR或少量PR
undefined

Phase 1: Foundation (Day 1)

阶段1：基础层（第1天）

  • Estimated effort: 4 hours
  • Files: 12
  • Risk: Low | # | File | Lines | Effort | Notes | |---|------|-------|--------|-------| | 1 | src/types/index.ts | 45 | 15m | Already TS, just verify | | 2 | src/constants/config.ts | 30 | 10m | Rename .js to .ts, add types | | ... | ... | ... | ... | ... |
  • 估算工作量：4小时
  • 文件数量：12
  • 风险：低 | 序号 | 文件 | 行数 | 工作量 | 备注 | |---|------|-------|--------|-------| | 1 | src/types/index.ts | 45 | 15分钟 | 已为TS，仅需验证 | | 2 | src/constants/config.ts | 30 | 10分钟 | 重命名.js为.ts，添加类型 | | ... | ... | ... | ... | ... |

Phase 2: Utilities (Day 1-2)

阶段2：工具层（第1-2天）

...
...

Phase 3: Services (Day 2-3)

阶段3：服务层（第2-3天）

...
undefined
...
undefined

Step 5: Risk Assessment

步骤5：风险评估

Produce a risk matrix for the overall migration:
生成整体迁移的风险矩阵：

5a. File Risk Scores

5a. 文件风险评分

Score each file 1-5 on these dimensions:
  • Complexity: Lines of code, cyclomatic complexity, number of patterns to change
  • Centrality: Number of files that depend on it (high centrality = high blast radius)
  • Volatility: How often the file changes in git history (high volatility = merge conflict risk)
  • Test Coverage: Does this file have tests? (no tests = higher risk)
  • External Coupling: Does it tightly integrate with third-party libraries that need replacement?
Overall risk = weighted average: Complexity(0.25) + Centrality(0.30) + Volatility(0.15) + TestCoverage(0.15) + ExternalCoupling(0.15)
从以下维度为每个文件评分（1-5分）：
  • 复杂度：代码行数、圈复杂度、需变更的模式数量
  • 核心度：依赖该文件的数量（核心度越高，影响范围越大）
  • 变动频率：Git历史中文件的变更频率（变动越频繁，合并冲突风险越高）
  • 测试覆盖率：文件是否有测试（无测试=更高风险）
  • 外部耦合度：是否与需替换的第三方库紧密集成
整体风险=加权平均值：复杂度(0.25) + 核心度(0.30) + 变动频率(0.15) + 测试覆盖率(0.15) + 外部耦合度(0.15)

5b. Migration-Level Risks

5b. 迁移级风险

Assess these macro risks:
RiskLikelihoodImpactMitigation
Build breaks during migrationMediumHighPhase-by-phase migration with CI checks after each phase
Type errors cascadeHighMediumStart with 
any
types, tighten incrementally
Third-party lib incompatibilityLowHighAudit all deps before starting (Step 2d)
Team unfamiliarity with targetMediumMediumPair programming on first 2 phases
Merge conflicts with active developmentHighMediumFeature freeze during foundation phase, or parallel branch
Test failures after migrationMediumMediumRun tests after each phase, fix immediately
Performance regressionLowHighBenchmark before and after each phase
评估以下宏观风险：
风险发生概率影响程度缓解措施
迁移期间构建失败中等高分阶段迁移，每个阶段后执行CI检查
类型错误扩散高中等从
any
类型开始，逐步收紧
第三方库不兼容低高迁移前审核所有依赖（步骤2d）
团队不熟悉目标技术中等中等前2个阶段采用结对编程
与活跃开发产生合并冲突高中等基础层阶段冻结功能，或使用并行分支
迁移后测试失败中等中等每个阶段后运行测试，立即修复问题
性能退化低高每个阶段前后进行基准测试

5c. Rollback Strategy

5c. 回滚策略

Define the rollback plan:
  • Each phase maps to a PR. Revert the PR to roll back.
  • Maintain a migration branch. If the migration stalls, the main branch is untouched.
  • Document the point of no return (usually after Phase 1 merges to main).
定义回滚计划：
  • 每个阶段对应一个PR，回滚PR即可撤销该阶段的变更。
  • 维护迁移分支。如果迁移停滞，主分支不受影响。
  • 记录不可回滚点（通常是阶段1合并到主分支后）。

Step 6: Effort Estimation

步骤6：工作量估算

Produce effort estimates at multiple granularities:
生成多粒度的工作量估算：

6a. Per-File Estimates

6a. 逐文件估算

Based on file size and migration patterns:
File SizeSimple PatternsComplex PatternsEstimated Time
< 50 linesRename + add typesN/A5-10 minutes
50-150 linesAdd types, update importsLifecycle conversion, state refactor15-30 minutes
150-300 linesAdd types, update importsMultiple pattern changes30-60 minutes
300-500 linesMultiple files worth of workHeavy refactoring1-2 hours
500+ linesConsider splitting firstMajor risk, needs review2-4 hours
基于文件大小和迁移模式：
文件大小简单模式复杂模式估算时间
< 50行重命名+添加类型无5-10分钟
50-150行添加类型、更新导入生命周期转换、状态重构15-30分钟
150-300行添加类型、更新导入多模式变更30-60分钟
300-500行相当于多个文件的工作量重度重构1-2小时
500+行建议先拆分高风险，需审核2-4小时

6b. Per-Phase Estimates

6b. 逐阶段估算

Sum file estimates plus overhead:
  • Overhead per phase: 30 minutes for PR creation, review, CI, merge
  • Integration testing: 15 minutes per phase to verify nothing broke
  • Buffer: Add 20% buffer for unexpected issues
汇总文件估算值并添加额外开销：
  • 每阶段开销：30分钟用于PR创建、审核、CI、合并
  • 集成测试：每阶段15分钟验证功能未损坏
  • 缓冲时间：添加20%缓冲应对意外问题

6c. Total Estimate

6c. 总估算

undefined
undefined

Effort Summary

工作量汇总

PhaseFilesRaw EffortBuffer (20%)Total
1. Foundation123h0.6h3.6h
2. Utilities186h1.2h7.2h
3. Services84h0.8h4.8h
4. Components3516h3.2h19.2h
5. Pages105h1h6h
6. Entry Points31h0.2h1.2h
7. Tests258h1.6h9.6h
Total11143h8.6h51.6h
  • Calendar time (1 dev): ~7 working days
  • Calendar time (2 devs): ~4 working days
  • Calendar time (3 devs, parallelized): ~3 working days
Note: Phases 1-3 are sequential. Phases 4-7 can partially parallelize across developers.
undefined
阶段文件数量原始工作量缓冲时间(20%)总工作量
1. 基础层123小时0.6小时3.6小时
2. 工具层186小时1.2小时7.2小时
3. 服务层84小时0.8小时4.8小时
4. 组件层3516小时3.2小时19.2小时
5. 页面层105小时1小时6小时
6. 入口层31小时0.2小时1.2小时
7. 测试层258小时1.6小时9.6小时
总计11143小时8.6小时51.6小时
  • 日历时间（1名开发者）：约7个工作日
  • 日历时间（2名开发者）：约4个工作日
  • 日历时间（3名开发者，并行执行）：约3个工作日
注：阶段1-3需顺序执行。阶段4-7可部分并行执行。
undefined

Step 7: Generate migration-plan.md

步骤7：生成migration-plan.md

Write the final deliverable to the specified output location. The document structure:
markdown
undefined
将最终交付产物写入指定输出位置。文档结构：
markdown
undefined

Migration Plan: [Source] to [Target]

迁移计划：[源技术] 到 [目标技术]

Generated: [timestamp] Codebase: [repo name / path] Total files: [N] Estimated effort: [Xh] Estimated calendar time: [X days] ([N developers])
生成时间：[时间戳] 代码库：[仓库名称/路径] 总文件数：[N] 估算工作量：[X小时] 估算日历时间：[X天]（[N名开发者]）

Table of Contents

目录

  1. Executive Summary
  2. Migration Type
  3. Codebase Inventory
  4. Dependency Graph
  5. External Dependencies
  6. Migration Phases
  7. File-by-File Changes
  8. Risk Assessment
  9. Effort Estimation
  10. Rollback Strategy
  11. Pre-Migration Checklist
  12. Post-Migration Verification
  1. 执行摘要
  2. 迁移类型
  3. 代码库盘点
  4. 依赖图谱
  5. 外部依赖
  6. 迁移阶段
  7. 逐文件变更
  8. 风险评估
  9. 工作量估算
  10. 回滚策略
  11. 迁移前检查清单
  12. 迁移后验证

Executive Summary

执行摘要

[2-3 paragraph overview: what is being migrated, why, key risks, estimated effort, recommended approach (big bang vs incremental), and team recommendations]
[2-3段概述：迁移内容、原因、关键风险、估算工作量、推荐方案（大爆炸式 vs 增量式）、团队建议]

Migration Type

迁移类型

  • From: [source technology/framework/pattern]
  • To: [target technology/framework/pattern]
  • Scope: [full repo / specific directories]
  • Strategy: [incremental (recommended for 50+ files) / big bang (viable for <50 files)]
  • 源技术：[源技术/框架/模式]
  • 目标技术：[目标技术/框架/模式]
  • 范围：[全仓库 / 特定目录]
  • 策略：[增量式（50+文件推荐） / 大爆炸式（<50文件适用）]

Codebase Inventory

代码库盘点

File Distribution by Type

文件类型分布

File TypeCountTotal Lines% of Codebase
.jsNNN%
.jsxNNN%
............
文件类型数量总行数代码库占比
.jsNNN%
.jsxNNN%
............

Directory Structure

目录结构

[tree output, annotated with migration notes]
[tree命令输出，附带迁移说明]

File Size Distribution

文件大小分布

RangeCountNotes
< 50 linesNQuick migrations
50-150 linesNStandard effort
150-300 linesNModerate effort
300-500 linesNSignificant effort
500+ linesNConsider splitting before migrating
范围数量备注
< 50行N快速迁移
50-150行N标准工作量
150-300行N中等工作量
300-500行N大量工作量
500+行N迁移前建议拆分

Dependency Graph

依赖图谱

Layer Classification

层级分类

[Table of all files classified into Foundation / Utilities / Services / Components / Pages / Entry Points / Tests / Config]
[所有文件的层级分类表格：基础层 / 工具层 / 服务层 / 组件层 / 页面层 / 入口层 / 测试层 / 配置层]

Critical Path

关键路径

[Files with highest centrality -- these are the backbone of the codebase and must migrate cleanly]
[核心度最高的文件——这些是代码库的支柱，必须确保迁移顺利]

Circular Dependencies

循环依赖

[List of cycles with recommended resolution]
[循环依赖列表及推荐解决策略]

External Dependencies

外部依赖

PackageCurrentStatusActionReplacement
react18.2.0CompatibleNone--
lodash4.17.21CompatibleNone--
moment2.29.4Needs ReplacementReplacedayjs or date-fns
...............
包名当前版本状态操作替代方案
react18.2.0兼容无--
lodash4.17.21兼容无--
moment2.29.4需替换替换dayjs或date-fns
...............

Migration Phases

迁移阶段

[Phase-by-phase breakdown as defined in Step 4]
[步骤4中定义的分阶段详细说明]

File-by-File Changes

逐文件变更

[Every file's migration assessment as defined in Step 3, organized by phase]
[步骤3中定义的每个文件的迁移评估，按阶段组织]

Risk Assessment

风险评估

[Risk matrix and macro risks as defined in Step 5]
[步骤5中定义的风险矩阵和宏观风险]

Effort Estimation

工作量估算

[Effort tables as defined in Step 6]
[步骤6中定义的工作量表格]

Rollback Strategy

回滚策略

[Rollback plan as defined in Step 5c]
[步骤5c中定义的回滚计划]

Pre-Migration Checklist

迁移前检查清单

  • All team members have read this plan
  • Target framework/library versions agreed upon
  • CI pipeline updated to support target (e.g., TypeScript compiler added)
  • Branch strategy agreed (migration branch vs feature flags)
  • Code freeze scheduled for foundation phase (if applicable)
  • Rollback procedure tested
  • Performance benchmarks captured (before state)
  • Test suite passing at 100% before migration starts
  • 所有团队成员已阅读本计划
  • 目标框架/库版本已达成共识
  • CI流水线已更新以支持目标技术（如添加TypeScript编译器）
  • 分支策略已确定（迁移分支 vs 功能开关）
  • 基础层阶段已安排代码冻结（如适用）
  • 回滚流程已测试
  • 已采集性能基准（迁移前状态）
  • 测试套件在迁移前100%通过

Post-Migration Verification

迁移后验证

  • All files migrated per plan
  • Zero source-pattern files remaining (e.g., no .js files if migrating to TS)
  • Build passes with zero errors
  • Test suite passes at 100%
  • No 
    any
    types remaining (or documented exceptions)
  • Performance benchmarks comparable to pre-migration
  • Documentation updated
  • Team trained on new patterns
undefined
  • 所有文件已按计划迁移
  • 无遗留源模式文件（如迁移到TS后无.js文件）
  • 构建通过且无错误
  • 测试套件100%通过
  • 无遗留
    any
    类型（或已记录例外情况）
  • 性能基准与迁移前相当
  • 文档已更新
  • 团队已接受新模式培训
undefined

Step 8: Optional JSON Output

步骤8：可选JSON输出

If the user requests it (or for large migrations where machine-readability helps), also generate 
migration-plan.json
:
json
{
  "metadata": {
    "generated": "ISO timestamp",
    "migrationFrom": "JavaScript",
    "migrationTo": "TypeScript",
    "totalFiles": 111,
    "estimatedHours": 51.6
  },
  "files": [
    {
      "path": "src/utils/helpers.js",
      "targetPath": "src/utils/helpers.ts",
      "lines": 145,
      "layer": "utility",
      "phase": 2,
      "phaseOrder": 3,
      "difficulty": 2,
      "estimatedMinutes": 20,
      "riskScore": 1.8,
      "dependencies": ["src/types/index.ts"],
      "dependedOnBy": ["src/services/api.ts", "src/components/Form.tsx"],
      "patterns": ["add-types", "update-imports"],
      "notes": "Pure functions, straightforward typing"
    }
  ],
  "phases": [...],
  "dependencies": {...},
  "risks": [...],
  "externalDeps": [...]
}
如果用户要求（或大型迁移需要机器可读性），同时生成
migration-plan.json
：
json
{
  "metadata": {
    "generated": "ISO时间戳",
    "migrationFrom": "JavaScript",
    "migrationTo": "TypeScript",
    "totalFiles": 111,
    "estimatedHours": 51.6
  },
  "files": [
    {
      "path": "src/utils/helpers.js",
      "targetPath": "src/utils/helpers.ts",
      "lines": 145,
      "layer": "utility",
      "phase": 2,
      "phaseOrder": 3,
      "difficulty": 2,
      "estimatedMinutes": 20,
      "riskScore": 1.8,
      "dependencies": ["src/types/index.ts"],
      "dependedOnBy": ["src/services/api.ts", "src/components/Form.tsx"],
      "patterns": ["add-types", "update-imports"],
      "notes": "纯函数，类型定义简单"
    }
  ],
  "phases": [...],
  "dependencies": {...},
  "risks": [...],
  "externalDeps": [...]
}

Handling Edge Cases

边缘情况处理

Codebase Too Large for Context

代码库超出上下文容量

If the codebase exceeds the context window capacity:
  1. Prioritize by layer -- Read foundation and utility layers in full, sample feature layers.
  2. Use Agent sub-agents -- Deploy agents to read and summarize subsections of the codebase. Each agent reads one directory subtree and returns a structured summary (file list, import graph, patterns found).
  3. Aggregate summaries -- The commander combines all sub-agent summaries into the full picture.
  4. Flag gaps -- Clearly note in the migration plan which files were summarized vs fully analyzed.
如果代码库超出上下文窗口容量：
  1. 按层级优先读取 —— 完整读取基础层和工具层，抽样读取功能层。
  2. 使用Agent子代理 —— 部署代理读取并汇总代码库的子部分。每个代理读取一个目录子树，并返回结构化摘要（文件列表、导入图谱、发现的模式）。
  3. 汇总摘要 —— 指挥官将所有子代理的摘要整合为完整视图。
  4. 标记缺口 —— 在迁移计划中明确标注哪些文件是摘要分析 vs 完整分析。

Monorepo with Multiple Packages

包含多包的Monorepo

  1. Treat each package as a semi-independent migration.
  2. Identify cross-package dependencies.
  3. Generate a per-package migration plan plus a top-level orchestration plan.
  4. Recommend migration order across packages (shared libs first, apps last).
  1. 将每个包视为半独立的迁移单元。
  2. 识别跨包依赖。
  3. 生成每个包的迁移计划及顶层编排计划。
  4. 推荐跨包迁移顺序（共享库优先，应用最后）。

Mixed Codebase (Already Partially Migrated)

混合代码库（已部分迁移）

  1. Identify which files are already in the target state.
  2. Classify files as: migrated, partially migrated, not migrated.
  3. Focus the plan on unmigrated files.
  4. Note any partially migrated files that need completion.
  1. 识别已处于目标状态的文件。
  2. 将文件分类为：已迁移、部分迁移、未迁移。
  3. 计划重点放在未迁移文件上。
  4. 记录需完成迁移的部分迁移文件。

No Tests Exist

无测试用例

  1. Flag this as a HIGH risk factor.
  2. Recommend adding integration tests for critical paths BEFORE migrating.
  3. Include a "pre-migration test authoring" phase in the plan.
  1. 将此标记为高风险因素。
  2. 建议在迁移前为关键路径添加集成测试。
  3. 在计划中添加“迁移前测试编写”阶段。

Effort Calibration by Migration Type

按迁移类型校准工作量

Different migration types have different per-file effort multipliers:
Migration TypeSimple FileMedium FileComplex File
JS to TS (strict)10 min30 min2h
JS to TS (loose/any)5 min15 min45 min
Class to Hooks15 min45 min2.5h
CRA to Next.js10 min30 min1.5h
Redux to Zustand20 min1h3h
Vue 2 to Vue 315 min45 min2h
CSS to Tailwind10 min30 min1.5h
Jest to Vitest5 min15 min45 min
CommonJS to ESM5 min10 min30 min
These are starting estimates. Adjust based on the specific codebase after ingestion.
不同迁移类型的逐文件工作量乘数不同：
迁移类型简单文件中等文件复杂文件
JS转TS（严格模式）10分钟30分钟2小时
JS转TS（宽松/any模式）5分钟15分钟45分钟
类组件转Hooks15分钟45分钟2.5小时
CRA转Next.js10分钟30分钟1.5小时
Redux转Zustand20分钟1小时3小时
Vue 2转Vue 315分钟45分钟2小时
CSS转Tailwind10分钟30分钟1.5小时
Jest转Vitest5分钟15分钟45分钟
CommonJS转ESM5分钟10分钟30分钟
以上为初始估算值，读取代码库后根据具体情况调整。

Quality Checklist for the Migration Plan

迁移计划质量检查清单

Before delivering the plan, verify:
  • Every source file is accounted for (inventory matches glob results)
  • Every file has a phase assignment
  • No file depends on an unmigrated file in a later phase (topological order holds)
  • All external dependencies are classified
  • Effort estimates sum correctly
  • Risk scores are calculated and documented
  • Circular dependencies are identified and have resolution strategies
  • The plan is actionable -- a developer can pick up Phase 1 and start immediately
  • Rollback strategy is defined
  • Pre-migration and post-migration checklists are included
交付计划前，请验证：
  • 所有源文件已纳入盘点（清单与Glob结果匹配）
  • 每个文件已分配阶段
  • 无文件依赖后续阶段的未迁移文件（拓扑顺序有效）
  • 所有外部依赖已分类
  • 工作量估算汇总正确
  • 风险评分已计算并记录
  • 循环依赖已识别并提供解决策略
  • 计划可执行——开发者可直接开始阶段1的工作
  • 回滚策略已定义
  • 包含迁移前和迁移后检查清单