实战 B5：Claude Code 大型项目实战——Worktrees 并行、分阶段重构与团队 Skills 共享

Claude Code大型项目Worktrees重构实战教程

实战教程系列 系列 B：B1 配置实战 | B2 日常开发 | B3 审查与重构 | B4 多 Agent | B5 大型项目 ← 本文

# Claude Code 大型项目 ## Worktrees 并行 - 多分支同时推进 - 隔离文件系统 - 批量迁移模式 ## 分阶段重构 - 4 阶段节奏控制 - 小步快跑每步验证 - CommonJS→ESM 案例 ## 团队 Skills - .claude/skills/ 共享 - 版本管理策略 - 新成员零成本复用 ## 核心原则 - 隔离、分阶段、共享 - Effort 节制 - 上下文管理

案例 1：Worktrees 并行开发——多分支同时推进

在大型项目中，Claude Code 的 Worktrees 允许多个独立分支并行开发：

主工作区：正在开发新功能
Worktree 1：重构 auth 模块（独立进行，不影响主工作区）
Worktree 2：修复生产 bug（紧急，需要隔离环境）
Worktree 3：技术验证——尝试新的缓存方案

每个 worktree 是独立的 Git 工作目录，有自己的文件系统视图。Claude Code 在 worktree 中的操作不会影响主工作区或其他 worktree。

使用方式

claude
/batch migrate all logger.error calls to use structured logging across all services

Claude Code 自动创建多个 worktree，在每个中独立执行迁移，完成后汇总结果。

案例 2：分阶段重构——大型迁移的节奏控制

场景：将整个代码库从 CommonJS 迁移到 ESM。涉及 200+ 文件。

错误做法

把所有文件改成 ESM 语法

→ 一次性改动太大，测试全红，不知道从哪修。

正确做法：分阶段

Phase 1: 基础设施
- 更新 package.json 添加 "type": "module"
- 更新 tsconfig.json
- 先改 5 个工具函数文件，确认基础设施正确

Phase 2: 按模块推进
- 每次改 1 个模块（10-20 个文件）
- 改完就跑这个模块的测试
- 任何模块测试失败，停下来修复再继续

Phase 3: 集成验证
- 运行全量测试
- 修复剩余的 import 路径问题

Phase 4: 清理
- 移除旧格式的兼容代码
- 更新文档
flowchart TB P1[Phase1 基础设施] --> V1[验证配置] V1 --> P2[Phase2 按模块推进] P2 --> V2[逐模块测试] V2 --> P3[Phase3 集成验证] P3 --> V3[全量测试] V3 --> P4[Phase4 清理] P4 --> V4[移除兼容] V4 --> D[完成迁移]

关键原则：小步快跑，每步验证。

案例 3：团队 Skills 共享

团队 Skills 通过 .claude/skills/ 目录在 Git 中共享。每个 Skill 独立一个目录，可以独立更新而不影响其他。

Skills 版本策略

.claude/skills/
  release/SKILL.md         ← v1.2: stable, 所有人使用
  incident/SKILL.md        ← v2.0: 新增 Slack 通知步骤
  review-checklist/SKILL.md ← v1.0: 审查检查清单

新成员 clone 仓库后，所有 Skills 立即可用。Skill 更新通过正常的 PR 流程——谁改了 Skill 就要跑一遍验证。

Claude Code 大型项目的核心原则

  1. Worktree 隔离：大规模改动用 worktree，不污染主工作区
  2. 分阶段执行：200 个文件分 20 批，每批验证
  3. Skills 共享：团队经验编码为 Skills，新成员零成本复用
  4. Effort 节制：ultracode 只在真正需要时用，用完即关
  5. 上下文管理：长任务中用 /compact 保持 Token 在窗口内

下一章：系列 C：双工具协同实战

实操清单

  • 使用 Worktrees 同时推进多个独立分支（开发 + 修复 + 验证）
  • 将一次 200+ 文件的大重构拆分为 4-5 个阶段，每阶段独立验证
  • 团队 Skills 通过 .claude/skills/ 目录纳入 Git 版本控制
  • 新成员 onboarding 时，确保 clone 后 Skills 立即可用
  • 长任务中定期运行 /compact 保持 Token 在窗口内
  • 建立团队 Effort 使用规范：日常=high，上线前=xhigh，ultracode=需审批