场景：代码重构与迁移

用 Claude Code 重构代码结构或迁移技术栈。

重构流程

分析现状 → 制定计划 → 确认方案 → 逐步执行 → 测试验证

常见重构场景

拆分大文件

> src/services/user.service.ts 超过 500 行，按单一职责拆分：
> - 认证逻辑 → auth.service.ts
> - 用户 CRUD → user.service.ts
> - 邮件相关 → user-email.service.ts
> 保持所有公共 API 不变，先写测试确认当前行为，再重构。

提取公共逻辑

> 找到项目中所有重复的数据请求逻辑，提取为统一的 hooks/useQuery.ts：
> - 统一 loading/error/data 状态
> - 支持缓存和自动刷新
> - 替换所有现有的重复实现

升级依赖

> 将项目从 React 18 升级到 React 19：
> 1. 列出所有 breaking changes
> 2. 逐个修改受影响的代码
> 3. 更新类型定义
> 4. 运行测试确认

设计模式重构

> 将这个 God Class 重构为：
> - 数据访问层：Repository 模式
> - 业务逻辑：Service 模式
> - 保持接口兼容，分步执行
> 先分析当前类的职责，列出拆分方案。

技术栈迁移

框架迁移

> 将这个 Express 项目迁移到 Fastify：
> 1. 保留所有路由定义和业务逻辑
> 2. 替换 Express 中间件为 Fastify 插件
> 3. 更新错误处理
> 4. 保持 API 行为不变
> 先列出需要改动的文件清单。

语言迁移

> 将 src/legacy/ 下的 JavaScript 文件迁移到 TypeScript：
> - 添加类型注解
> - 修复类型错误
> - 保持功能不变
> 按文件逐个处理，每个处理完运行测试。

ORM 迁移

> 将 Sequelize 迁移到 Prisma：
> 1. 根据 Sequelize models 生成 Prisma schema
> 2. 创建数据库迁移
> 3. 替换所有 Sequelize 查询为 Prisma
> 4. 删除 Sequelize 依赖
> 保持所有 API 行为不变。

重构要点

要点	说明
先测试	重构前先确认测试通过，作为安全网
分步走	每次只做一个小改动，确认后再继续
保持接口	公共 API 不变，只改内部实现
让 AI 规划	先列出改动方案，不要直接改代码
逐步验证	每步运行测试，不要攒到最后

危险操作注意

• 涉及数据库 schema 变更：先生成迁移脚本，检查 up 和 down
• 大范围重命名：要求 AI 先列出所有受影响的文件
• 删除代码：要求 AI 确认无引用后再删
• 迁移完成前保留旧代码，确认新代码工作后再清理