实战案例：并行迁移 Vite → Next.js 16

这是一个实际案例，使用 Claude Code + Superpowers 完成。以下内容描述了从头脑风暴到完成的整个过程，包括迁移后的 UI 重新设计。

将一个 React 应用从 Vite 迁移到 Next.js 16 不是一个 agent 顺序完成的工作。Superpowers 允许你头脑风暴策略、编写详细计划，并分派多个 agent 并行执行——每个 agent 拥有独立的文件，互不冲突。

---

背景

项目是一个带登录功能的 Todo App，使用 React 19 + Vite 7 编写。当前技术栈：

方面	详情
框架	React 19 + Vite 7（SPA，无路由）
语言	TypeScript 5.9（strict mode）
UI	Tailwind CSS 4 + shadcn/ui
状态管理	Context API + useReducer
后端	无 — 100% localStorage
认证	客户端 SHA-256 hash，存储 localStorage
功能	Todo CRUD, Drag-drop, Filters, Dark mode, Auth
测试	Vitest + React Testing Library

目标： 将全部迁移到 Next.js 16 App Router，保留现有逻辑（localStorage、客户端 auth、UI 库）。团队有 3-4 个 agent 可以并行工作。

重要要求：

• 仅更换框架，不更改逻辑
• 迁移后所有现有测试仍必须通过
• 多个 agent 可以同时在不同文件上工作

---

你将学到什么

阅读完本案例后，你将知道如何在实际重构/迁移场景中应用 Superpowers 技术：

1. 头脑风暴 迁移策略 — 提出正确的问题，提出方案，选择最优方向
2. 编写计划 用于并行工作 — 按阶段划分任务并明确依赖关系
3. 并行 Subagents 同时执行 — 3 个 agent 同时在各自独立的文件上工作
4. 两阶段代码审查 确保质量 — 每个阶段后自动进行 spec 审查
5. 验证 确认结果 — build + 测试必须在继续之前通过

---

分步实践

步骤 0：头脑风暴迁移策略

在编写计划之前，你需要头脑风暴确定策略。你打开与 AI 的对话并说：

"我需要将整个项目重构为 NextJS 16，这是一个带账户登录的 web todo 项目。团队有 3-4 个 agent 可以并行工作。请先头脑风暴重构策略再开始。"

AI 进入头脑风暴模式（使用 superpowers:brainstorming skill），探索代码库，然后逐个提问：

AI： "重构的范围到哪里？"

• A) Full-stack — 添加真实数据库、API routes、服务端认证
• B) Hybrid — Server Components + App Router 用于渲染，但保留 localStorage
• C) 仅框架迁移 — 从 Vite 切换到 Next.js 16，保留现有逻辑

选择：C) 仅框架迁移 — 专注于项目结构和路由。

AI： "关于路由，URL 结构是什么样的？"

• A) 最小路由 — 只有 2 个路由：/（todo app）和 /login（认证页面）
• B) 结构化路由 — 多个路由：/login、/register、/todos、/todos/[id]

选择：A) 最小路由 — 简单，最接近当前状态。

AI： "现有的 UI 库保留还是更换？"

选择：全部保留 — shadcn/ui, @dnd-kit, sonner, date-fns, lucide-react。

AI： "测试用什么框架？"

• A) 保留 Vitest — Next.js 16 原生支持
• B) 切换到 Jest

选择：A) 保留 Vitest。

AI： "关于部署，有具体目标吗？"

• A) Vercel — 对 Next.js 最优化，零配置
• B) 自托管 / Docker
• C) 暂不关心 — 先专注迁移

选择：C) 暂不关心 — 先专注迁移。

收集完足够信息后，AI 展示 3 种方案：

## 方案 A：创建新项目 + 逐步迁移（推荐）
创建新的 Next.js 16 项目，逐步复制/适配各部分。
- 优点：结构干净，易于分配 agent 并行工作，项目从一开始就能运行
- 缺点：需要重新设置配置（shadcn, tailwind）

## 方案 B：就地迁移
直接在当前项目上转换——用 Next.js 替换 Vite。
- 优点：不丢失 git history
- 缺点：容易冲突，迁移过程中项目无法运行，难以分配并行任务

## 方案 C：Codemods + 自动化
使用 @next/codemod 和脚本自动转换。
- 优点：基本部分转换快
- 缺点：Codemods 不覆盖 Vite → Next.js，项目太小不值得

## 建议
方案 A。项目较小（约 15 个组件），创建新项目比就地迁移更快。
易于分配给 3-4 个 agent 并行工作。

选择 方案 A。AI 追问："你要我在浏览器上显示图表和 mockup 吗？" → 同意。AI 启动 visual companion（一个本地服务器）直接在浏览器上渲染架构图。

AI 继续通过 5 个部分展示详细设计（在浏览器上显示）：

1. Project Structure — 使用 App Router 的新目录结构（app/, components/, hooks/, lib/, types/, contexts/）
2. Component Mapping — Server vs Client Components 分类。模式：Thin Server Shell → Fat Client Tree
3. Routing & Auth Flow — / 包裹在 AuthGuard 中，/login 已登录时重定向，使用 next/navigation
4. Agent Parallelization — 3 个阶段：Foundation → Parallel Features → Integration
5. Migration Details — 添加/移除的包、配置变更、import 路径

AI 将设计规格保存到 docs/superpowers/specs/ 并自动分派 spec reviewer。Reviewer 发现 3 个问题（缺少 todo-app.tsx orchestrator、测试目录结构、Toaster 位置）→ AI 修复 → reviewer 第 2 次批准。

Superpowers 提示： 设计规格保存在 docs/superpowers/specs/ 中，在编写计划之前进行审查。详见 Brainstorming。

---

步骤 1：Superpowers 编写任务分配计划

在编写任何代码之前，AI 会创建一个详细的计划（使用 superpowers:writing-plans skill）。这是核心原则：没有计划就没有执行。

AI 读取所有源文件，然后创建包含 10 个任务、分为 3 个阶段的计划：

Phase 1: Foundation（1 个 agent，顺序执行 — 必须先完成）

1. Task 1: 使用 create-next-app 搭建新的 Next.js 16 项目
2. Task 2: 添加依赖和配置（Tailwind, shadcn, Vitest, tsconfig）
3. Task 3: 复制不变的文件（lib/, types/, hooks/, contexts/, components/ui/）
4. Task 4: 创建 app/layout.tsx — Root layout 包含 AuthProvider 和 Toaster
5. Task 5: 创建 app/globals.css — 从 src/index.css 迁移 CSS

Phase 2: Features（3 个 agent 并行）

6. Task 6 — Agent Auth: 创建认证页面（auth-guard.tsx, auth-page.tsx, login-form.tsx, register-form.tsx, app/login/page.tsx）
7. Task 7 — Agent Todo: 创建 todo 页面（todo-app.tsx, header.tsx, filter-bar.tsx, todo-list.tsx, todo-item.tsx, todo-input.tsx, edit-todo-dialog.tsx, app/page.tsx）
8. Task 8 — Agent Test: 迁移 8 个测试文件到 __tests__/，更新 relative imports → @/ alias

Phase 3: Integration（1 个 agent，顺序执行）

9. Task 9: 运行 npm run build + npx vitest run，修复所有问题
10. Task 10: 清理和最终提交

依赖关系图：

Phase 1 (Tasks 1-5) ─── sequential ───→ Phase 2 (Tasks 6-8) ─── parallel ───→ Phase 3 (Tasks 9-10)
                                          ├─ Agent Auth (Task 6)
                                          ├─ Agent Todo (Task 7)
                                          └─ Agent Test (Task 8)

并行执行的前提条件：每个 agent 拥有独立的文件，不重叠。Auth Agent 只修改 auth 相关文件，Todo Agent 只修改 todo 相关文件，Test Agent 只创建测试文件。

AI 自动分派 plan reviewer → reviewer 发现 1 个问题（测试文件使用 relative imports 移动后会失效）→ AI 通过 import mapping 表修复 → reviewer 批准。

AI 询问执行方式：

"两种执行方式：1) Subagent-Driven（推荐）— 分派 agent，任务间审查。2) Inline Execution — 在当前会话中直接执行。选择哪种？"

选择：1) Subagent-Driven — 适合 3-4 个 agent 并行工作的需求。

步骤 2：Phase 1 — Foundation

AI 将 5 个 foundation 任务合并为 1 个大 agent（因为它们是顺序依赖的）。Agent 执行：

1. Scaffold: npx create-next-app@latest，使用 TypeScript, Tailwind CSS, App Router
2. Config: 添加依赖（@dnd-kit/*, sonner, date-fns, shadcn 等），设置 vitest.config.ts, components.json
3. Copy files: lib/, types/, hooks/, contexts/, components/ui/ — 原样复制，只在文件开头添加 "use client"
4. Layout: 创建 app/layout.tsx，包含 metadata, fonts, <AuthProvider>, <Toaster />
5. CSS: 迁移 globals.css，使用 Tailwind 4 语法

Phase 1 完成后（7 个提交），AI 分派 后台运行的 spec reviewer 在准备 Phase 2 时检查合规性。

Phase 1: DONE — 7 commits, build 成功, 所有文件在正确位置

步骤 3：分派 3 个 Agent 并行执行（Phase 2）

Phase 1 完成后，controller 同时分派 3 个 agent：

Agent	任务	拥有的文件
Auth Agent	Auth 页面 + 路由保护	auth-guard, auth-page, login-form, register-form, app/login/page.tsx
Todo Agent	Todo 页面 + 所有组件	todo-app, header, filter-bar, todo-list, todo-item, todo-input, edit-todo-dialog, app/page.tsx
Test Agent	迁移 8 个测试文件	__tests__/components/, __tests__/contexts/, __tests__/hooks/, __tests__/lib/

每个 agent 收到：

• 明确的范围: 计划中的具体文件列表
• Spec 参考: 设计规格的链接，了解组件需要如何适配
• 约束: 不修改范围外的文件，每个交互组件开头添加 "use client"

实际进展：

• Auth Agent 最先完成 — 5 个文件，TypeScript 通过，提交 740e5dd。IDE 报告 todo-list.tsx import ./todo-item 错误 — 但这是因为 Todo Agent 还没创建完文件，会自行解决。

• Todo Agent 接着完成 — 8 个文件，TypeScript 通过，提交 55a8988。创建了新的 todo-app.tsx 作为 orchestrator（从 App.tsx 提取逻辑），包裹在 <AuthGuard> 中。

• Test Agent 最后完成 — 创建了 8 个测试文件但由于权限不足无法运行测试/提交。Controller 运行 npx vitest run 并代为提交 — 39/39 测试 PASS。

Auth Agent: DONE — 5 files, TypeScript pass
Todo Agent: DONE — 8 files, TypeScript pass
Test Agent: DONE — 8 test files migrated, 39/39 tests pass

步骤 4：Phase 3 — 集成验证

当所有 3 个 agent 完成后，controller 运行集成：

npm run build

Build 失败！ 错误：window is not defined — 因为 useTheme 和 useTodos 在 useState 初始化器中访问了 window/localStorage。这是 Next.js 特有的 SSR 预渲染问题（Vite 没有这个问题）。

修复： 在 hooks 中添加 SSR guard：

// hooks/use-theme.ts
const [theme, setTheme] = useState<'light' | 'dark'>(() => {
  if (typeof window === 'undefined') return 'light' // SSR guard
  const saved = loadTheme()
  if (saved) return saved
  return window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light'
})

// hooks/use-todos.ts
const [todos, dispatch] = useReducer(todoReducer, [], () => {
  if (typeof window === 'undefined') return [] // SSR guard
  return loadTodos()
})

重新运行：npm run build → Build 成功！ npx vitest run → 39/39 测试 PASS！

实际经验： 从 SPA（Vite）迁移到有 SSR 的框架（Next.js）时，始终要 guard 仅浏览器端的 API（window, localStorage, document）在初始状态中。这是最常见的问题。

步骤 5：Verification Gate

在声明迁移完成之前：

1. 运行

npm run build && npx vitest run

2. 阅读

✓ Compiled successfully
Routes:
  ○ /           — Static
  ○ /login      — Static
  ○ /_not-found — Static

Test Suites: 8 passed, 8 total
Tests:       39 passed, 39 total

3. 确认

指标	结果
Build	next build 成功
Tests	39/39 pass（8 个测试文件）
Routes	/（todo app）、/login（auth）
Commits	11 个干净的提交

4. GIT HISTORY

050db4f chore: add .superpowers/ to .gitignore
edfa697 fix: guard window/localStorage access for SSR prerendering
97542b0 test: migrate all test files to __tests__/ directory
55a8988 feat: add todo page with all components
740e5dd feat: add auth pages with client-side route protection
76abbff fix: add "use client" to sonner component, accept Next.js tsconfig updates
e78ce06 feat: add root layout with AuthProvider and Toaster
65ff090 chore: copy unchanged source files
451ad1d chore: configure TypeScript, Vitest, and shadcn
a50080f chore: add project dependencies
bb0f5c5 chore: scaffold Next.js 16 project

---

额外内容：Neo Brutalism 重新设计（继续并行）

迁移完成并验证通过后，团队继续新的需求：按 Neo Brutalism 风格重新设计整个 UI。Superpowers 工作流程完全重复：

头脑风暴 Neo Brutalism

AI 提出 5 个问题：

1. Brutal 程度 → 选择：Bold Neo Brutalism（3px 黑色边框、硬阴影、鲜艳色彩）
2. 配色方案 → 选择：Candy Crush（粉/紫/蓝 — #FF85A1, #A855F7, #38BDF8）
3. 范围 → 选择：全部（login 和 todo 页面都改）
4. 暗色模式 → 选择：保留两种（亮色 Neo Brutalism 为主，暗色适配）
5. 字体 → 选择：Space Grotesk（Neo Brutalism 中流行的几何无衬线字体）

AI 提出 3 种方案 → 选择 CSS-first（通过 CSS variables + Tailwind classes 变更，保持组件结构不变，测试仍然通过）。

Neo Brutalism 计划：6 个任务，4 个阶段

阶段	任务	Agent 数	描述
1: Foundation	Task 1	1	字体替换、CSS variables、工具类
2: Base UI	Task 2	1	button, input, dialog, select, dropdown, popover, sonner, calendar
3: Components	Task 3-5	3 并行	Auth (A), Layout (B), Items (C)
4: Integration	Task 6	1	Build、tests、视觉检查

并行执行

Phase 1+2（合并为 1 个 agent，因为是顺序依赖的）：

• 字体从 Geist → Space Grotesk
• 替换所有 CSS variables（OKLch colors → Candy Crush 配色）
• 添加工具类：.brutal-shadow, .brutal-border, hover/active transforms
• 更新 shadcn/ui 基础组件（button, input, dialog, select...）

Phase 3 — 3 个 agent 并行：

Agent	文件
Agent A: Auth	auth-page, login-form, register-form
Agent B: Layout	header, filter-bar, todo-list
Agent C: Items	todo-item, todo-input, edit-todo-dialog

Phase 4: Build + Test → 39/39 测试仍然通过（因为只更改了样式，没有触及逻辑）。

Neo Brutalism 结果

• 字体：Geist → Space Grotesk Variable
• 颜色：OKLch neutral → Candy Crush (pink/purple/blue)
• 边框：1px transparent → 3px solid black
• 阴影：模糊柔和 → 4px 硬偏移（无模糊）
• Hover/Active：上浮 / 下按变换
• 暗色模式：深蓝背景，彩色边框，保留鲜明色彩
• 重新设计共 5 个提交

---

总体结果

完成迁移和重新设计后：

指标	之前	之后
框架	React 19 + Vite 7 (SPA)	Next.js 16 App Router
路由	无（状态切换）	/ 和 /login，使用 next/navigation
组件	全部客户端	Server shells + Client components
样式	默认 shadcn/ui	Bold Neo Brutalism (Candy Crush)
字体	Geist	Space Grotesk
测试	39 pass	39 pass（未破坏）
提交	—	11（迁移）+ 5（重设计）= 16 commits

• 0 个测试被破坏 — 逻辑 100% 保留
• 借助并行执行时间显著缩短（迁移 Phase 2 的 3 个 agent + 重设计 Phase 3 的 3 个 agent）
• 实际问题即时修复：SSR window guard、sonner 的 "use client" 指令、测试 import 路径

---

关键要点

1. 编码前先头脑风暴。 提出正确的问题（范围、方案、约束）有助于避免错误方向的重构。在这个案例中，5 个头脑风暴问题明确了："仅框架迁移，创建新项目，保留现有逻辑"。

2. 详细计划是并行执行的先决条件。 计划必须明确指出：谁做什么、哪些文件、任务之间的依赖关系。如果不明确文件归属，agent 之间就会冲突。

3. 按依赖关系划分阶段，在每个阶段内并行。 Foundation 必须先完成（scaffold, config），然后才能分派 agent 并行处理功能。这就是模式：顺序阶段 → 阶段内并行任务。

4. Spec 和 plan 都会自动审查。 AI 在编写 spec/plan 后分派 reviewer agent。Reviewer 在执行开始前发现问题（缺少 orchestrator 组件、错误的测试 import 路径）——在代码阶段修复的成本远低于之后。

5. 实际问题总会出现。 在这个案例中，SSR window is not defined 是 SPA → SSR 框架迁移的典型问题。Integration phase（Phase 3）的存在就是为了捕获和修复这些问题。

6. 工作流程可以重复。 迁移完成后，Neo Brutalism 重设计遵循完全相同的工作流程：brainstorm → spec → plan → parallel execution → verify。同样的模式，不同的上下文。

---

总结： 在同一个工作会话中将 React/Vite 应用迁移到 Next.js 16 + Neo Brutalism 重设计。Superpowers 编排整个过程：头脑风暴确定策略、计划按阶段分配任务、并行 agent 同时执行、spec 审查确保质量、verification gate 在声明完成前捕获问题。结果：16 个提交，39/39 测试通过，0 回归。