<!-- title: Claude Code Worktree并行实战全流程 -->

# Claude Code Worktree并行实战：从隔离到合并全流程

## 概述

本教程面向已经掌握 Claude Code 基础操作、希望突破"单线程"瓶颈的中级开发者。你将学会使用 Git Worktree 让多个 Claude Code 会话在同一仓库中并行工作、互不干扰——从 `--worktree` 快速启动、Subagent 自动隔离、tmux 并行编排，到数据库端口隔离、合并策略与冲突处理。学完后，你能同时跑 3-5 个 Claude Code Agent 处理独立任务，将开发吞吐量提升 2-3 倍。

**适用人群**：有 Git 基础、已安装 Claude Code CLI 的开发者
**预计教学时长**：3-4 小时（含实操）

---

## 前置条件

| 条件 | 说明 |
|------|------|
| Git ≥ 2.5 | `git --version` 确认，worktree 从 2.5 引入 |
| Claude Code CLI | 已安装并认证，`claude --version` 可运行 |
| tmux（推荐） | 用于多面板并行管理 Agent 会话 |
| 一个 Git 仓库 | 任何已有项目均可作为练习环境 |
| Node.js / Python | 根据项目技术栈，需在每个 worktree 中安装依赖 |

---

## 一、为什么需要 Worktree：问题与解法

### 1.1 痛点：Claude Code 的独占性

Claude Code 假设自己对工作目录有独占控制权。当你在同一个目录下运行两个 Claude Code 会话时：

```
❌ 两个 Agent 同时修改 src/auth/login.ts
❌ 文件状态不一致，上下文被污染
❌ 一个 Agent 的修改被另一个覆盖
```

传统做法是 `git stash` 切分支，但每次切换都要：
- 丢弃 Claude 已建立的深层上下文理解
- 重新 `/init` 或手动恢复对话
- 重新安装依赖、重建 mental model

### 1.2 解法：Git Worktree = 多目录 + 共享历史

Git Worktree 允许你在**不同目录**中同时检出**不同分支**，共享同一个 `.git` 仓库数据库：

```
/projects/
├── my-app/                    ← 主工作树 (main 分支)
│   └── .git/                  ← 真正的 Git 仓库数据
├── my-app-feature-auth/       ← 关联工作树 (feature/auth 分支)
│   └── .git                   ← 文本文件，指向主 .git
└── my-app-bugfix-api/         ← 关联工作树 (bugfix/api 分支)
    └── .git                   ← 同上
```

**核心特性**：

| 属性 | 行为 |
|------|------|
| `.git` 目录 | 所有 worktree 共享 |
| 工作文件 | 每个 worktree 独立 |
| Git 历史 | 共享，commit 全局可见 |
| 分支检出 | 同一分支不能同时被多个 worktree 检出 |
| 文件变更 | 完全隔离 |

### 1.3 效果对比

```mermaid
flowchart LR
    subgraph 传统方式
        A[Agent 1: 功能开发] -->|stash| B[切换分支]
        B --> C[Agent 2: Bug修复]
        C -->|stash + pop| D[恢复Agent 1]
        D --> E[重建上下文...]
    end

    subgraph Worktree方式
        F[Agent 1: Worktree-A<br/>功能开发]
        G[Agent 2: Worktree-B<br/>Bug修复]
        H[Agent 3: Worktree-C<br/>重构]
        F ~~~ G ~~~ H
    end

    传统方式 -->|耗时 4h| I[串行完成]
    Worktree方式 -->|耗时 1.5h| J[并行完成]
```

根据实际使用经验，并行开发的合并冲突率仅为 **3.1%**（来源：Citadel Fleet 模式报告），前提是任务间文件重叠度低。

---

## 二、快速上手：三种启动方式

### 2.1 方式一：`--worktree` 标志（最快）

Claude Code 内置了 worktree 支持，一行命令即可启动隔离会话：

```bash
# 创建名为 feature-auth 的 worktree 并启动 Claude
claude --worktree feature-auth

# 另一个终端，启动第二个隔离会话
claude --worktree bugfix-123

# 省略名称，Claude 自动生成随机名（如 bright-running-fox）
claude --worktree
```

**默认行为**：
- worktree 创建在 `.claude/worktrees/<名称>/` 下
- 新分支命名为 `worktree-<名称>`
- 基于远程默认分支（`origin/HEAD`）创建

**关键配置**：将 worktree 目录加入 `.gitignore`：

```bash
echo ".claude/worktrees/" >> .gitignore
```

### 2.2 方式二：基于 PR 创建 Worktree

```bash
# 从 PR #1234 创建 worktree
claude --worktree "#1234"

# 等价于
claude --worktree "https://github.com/your-org/your-repo/pull/1234"
```

Claude Code 会自动 fetch `pull/<number>/head` 并创建 worktree。

### 2.3 方式三：手动创建 Git Worktree

```bash
# 创建新分支的 worktree
git worktree add ../my-app-feature -b feature/new-auth

# 使用已有分支
git worktree add ../my-app-bugfix bugfix/issue-456

# 从特定 commit/tag 创建
git worktree add ../my-app-hotfix v2.0.0 -b hotfix/v2-critical

# 在 worktree 中启动 Claude
cd ../my-app-feature && claude
```

**手动方式的优势**：可以完全控制目录位置和分支来源。

---

## 三、配置详解：从 baseRef 到 .worktreeinclude

### 3.1 选择基准分支

默认 worktree 从远程默认分支（`origin/HEAD`）创建。如果需要从当前 HEAD（包含未推送的 commit）创建：

```json
// .claude/settings.json
{
  "worktree": {
    "baseRef": "head"
  }
}
```

可选值只有 `"fresh"`（默认，从远程）和 `"head"`（从本地 HEAD）。

**使用场景**：
- `"fresh"`：独立功能开发，从干净状态开始
- `"head"`：在当前未完成工作基础上隔离 subagent

### 3.2 自动复制 Gitignored 文件

worktree 是全新检出，不包含 `.env` 等未追踪文件。通过 `.worktreeinclude` 自动复制：

```
# .worktreeinclude（使用 .gitignore 语法）
.env
.env.local
config/secrets.json
docker-compose.override.yml
```

**规则**：只有同时满足两个条件才会复制——匹配 `.worktreeinclude` 模式 **且** 被 gitignore。

### 3.3 依赖安装自动化

每个 worktree 是独立的文件系统，需要单独安装依赖：

```bash
# 手动方式
cd ../my-app-feature
npm install  # 或 pip install -r requirements.txt

# 用 Bash 函数自动化（加入 ~/.bashrc 或 ~/.zshrc）
cw() {
  local branch="$1"
  local project=$(basename $(git rev-parse --show-toplevel))
  local path="../${project}-${branch}"
  
  git worktree add "$path" -b "$branch" 2>/dev/null || \
  git worktree add "$path" "$branch"
  
  cd "$path"
  
  # 根据项目类型安装依赖
  [ -f "package.json" ] && npm install
  [ -f "requirements.txt" ] && pip install -r requirements.txt
  [ -f "go.mod" ] && go mod download
  
  claude
}
```

---

## 四、实战：三路并行开发全流程

### 4.1 场景设定

假设你负责一个 Node.js + TypeScript 项目，需要同时处理三个任务：

| 任务 | 分支 | 涉及文件范围 |
|------|------|-------------|
| OAuth2 登录 | `feature/oauth2` | `src/auth/*`, `src/middleware/*` |
| API 限流 Bug | `bugfix/rate-limit` | `src/api/rateLimiter.ts` |
| 工具函数重构 | `refactor/utils` | `src/utils/*` |

### 4.2 第一步：规划任务（Plan Mode）

在主目录用 Plan Mode 分析文件依赖：

```
> /plan
我需要同时处理三个任务：
1. 添加 OAuth2 登录（Google + GitHub）
2. 修复 API 限流 Bug (#456)
3. 重构 src/utils/ 目录

请分析这三个任务是否有文件冲突风险，建议如何分配 worktree。
```

Claude 会分析文件依赖，确认任务间文件重叠度低后给出分配建议。

### 4.3 第二步：创建 Worktree 网格

```bash
# 从主项目目录
git worktree add ../my-app-oauth -b feature/oauth2
git worktree add ../my-app-ratefix -b bugfix/rate-limit
git worktree add ../my-app-refactor -b refactor/utils

# 验证
git worktree list
```

输出：
```
/home/user/projects/my-app          abc1234 [main]
/home/user/projects/my-app-oauth    def5678 [feature/oauth2]
/home/user/projects/my-app-ratefix  ghi9012 [bugfix/rate-limit]
/home/user/projects/my-app-refactor jkl3456 [refactor/utils]
```

### 4.4 第三步：配置环境隔离

```bash
# 为每个 worktree 复制环境文件
for wt in ../my-app-oauth ../my-app-ratefix ../my-app-refactor; do
  cp .env "$wt/.env"
  cp .env.local "$wt/.env.local" 2>/dev/null
done
```

**数据库隔离**（如果使用 SQLite）：

```bash
# 每个 worktree 使用独立数据库
sed -i 's/myapp\.db/myapp-oauth.db/' ../my-app-oauth/.env
sed -i 's/myapp\.db/myapp-ratefix.db/' ../my-app-ratefix/.env
sed -i 's/myapp\.db/myapp-refactor.db/' ../my-app-refactor/.env
```

**端口隔离**：

```bash
# .env 文件中的端口配置
# my-app-oauth/.env
PORT=3001
DATABASE_URL="postgresql://localhost:5433/myapp_oauth"

# my-app-ratefix/.env
PORT=3002
DATABASE_URL="postgresql://localhost:5434/myapp_ratefix"

# my-app-refactor/.env
PORT=3003
DATABASE_URL="postgresql://localhost:5435/myapp_refactor"
```

### 4.5 第四步：安装依赖并启动 Claude

```bash
for wt in ../my-app-oauth ../my-app-ratefix ../my-app-refactor; do
  (cd "$wt" && npm install)
done
```

### 4.6 第五步：tmux 多面板编排

```bash
# 创建专用 tmux 会话
tmux new-session -s claude-parallel

# 第一个面板：OAuth2 功能
cd /home/user/projects/my-app-oauth
claude "实现 OAuth2 登录功能：1) 支持 Google 和 GitHub 提供商
2) 安全存储 token 到数据库 3) 创建保护路由中间件 4) 编写完整测试"

# Ctrl+b % 垂直分割新面板
# 第二个面板：Bug 修复
cd /home/user/projects/my-app-ratefix
claude "修复 API 限流 Bug (#456)。先用 gh issue view 456 了解问题，
然后实现解决方案并编写测试。"

# Ctrl+b % 再分割
# 第三个面板：重构
cd /home/user/projects/my-app-refactor
claude "重构 src/utils/ 目录：1) 删除重复代码 2) 添加 TypeScript 类型
3) 改善错误处理 4) 更新所有 import"
```

```mermaid
flowchart TB
    subgraph tmux["tmux 会话: claude-parallel"]
        direction LR
        P1["面板 1<br/>my-app-oauth<br/>OAuth2 登录开发"]
        P2["面板 2<br/>my-app-ratefix<br/>API 限流修复"]
        P3["面板 3<br/>my-app-refactor<br/>工具函数重构"]
    end

    subgraph repo["Git 仓库 (共享)"]
        G[".git/ 仓库数据库"]
        H["Git 历史记录"]
        R["远程连接"]
    end

    P1 --> G
    P2 --> G
    P3 --> G
    G --> H
    G --> R

    style P1 fill:#4CAF50,color:white
    style P2 fill:#FF9800,color:white
    style P3 fill:#2196F3,color:white
```

### 4.7 第六步：监控与干预

在 tmux 中通过 `Ctrl+b` + 方向键切换面板，检查各 Agent 进度：

- **权限请求**：每个 Agent 可能请求文件写入、命令执行权限
- **问题答疑**：Agent 遇到歧义时会提问，需要及时回应
- **代码审查**：Agent 完成后审阅生成代码

### 4.8 第七步：合并与清理

```bash
# 回到主项目
cd /home/user/projects/my-app

# 逐个合并（先测试通过的先合）
git merge feature/oauth2
git merge bugfix/rate-limit
git merge refactor/utils

# 或通过 Claude 创建 PR
cd ../my-app-oauth
claude "为这些变更创建一个 PR，包含全面描述"

# 合并后清理
git worktree remove ../my-app-oauth
git worktree remove ../my-app-ratefix
git worktree remove ../my-app-refactor

# 清理过期引用
git worktree prune

# 删除已合并的分支
git branch -d feature/oauth2 bugfix/rate-limit refactor/utils
```

---

## 五、Subagent Worktree 隔离

### 5.1 自动隔离模式

Claude Code 支持在 Subagent 级别自动使用 worktree 隔离：

**方式一：对话中指定**

```
> 请用 worktree 隔离你的 agents，并行完成以下三个测试任务...
```

**方式二：Agent 配置文件中设置**

```yaml
# .claude/agents/perf-tester.md
---
name: perf-tester
description: 性能测试 Agent
tools: Read, Glob, Grep, Bash
isolation: worktree    # ← 关键配置
---
# Performance Tester Agent
...对 src/api/ 目录下的每个端点进行性能测试...
```

**生命周期**：
- Subagent 启动时自动创建临时 worktree
- 完成后无变更 → 自动删除
- 有变更 → 保留等待主 Agent 处理
- 超过 `cleanupPeriodDays` → 自动清理

### 5.2 Subagent 并行编排示例

```markdown
# .claude/skills/parallel-test/skill.md
---
name: parallel-test
description: 并行执行多模块测试，自动 worktree 隔离
---

## 并行测试编排

请为以下模块各启动一个 worktree 隔离的 subagent：

1. **auth-tester**: 测试 src/auth/ 下所有认证逻辑
2. **api-tester**: 测试 src/api/ 下所有 API 端点
3. **ui-tester**: 测试 src/components/ 下所有 UI 组件

每个 subagent 使用 `isolation: worktree` 配置。
收集所有 subagent 的测试结果后，汇总报告。
```

```mermaid
sequenceDiagram
    participant User as 用户
    participant Main as 主 Agent
    participant WTA as Worktree-A<br/>auth-tester
    participant WT_B as Worktree-B<br/>api-tester
    participant WT_C as Worktree-C<br/>ui-tester
    
    User->>Main: /parallel-test
    Main->>WTA: 创建 worktree + 启动测试
    Main->>WT_B: 创建 worktree + 启动测试
    Main->>WT_C: 创建 worktree + 启动测试
    
    Note over WTA,WT_C: 三个 subagent 并行执行
    
    WTA-->>Main: 认证测试结果 (12/12 passed)
    WT_B-->>Main: API 测试结果 (23/25 passed, 2 failed)
    WT_C-->>Main: UI 测试结果 (18/18 passed)
    
    Main->>User: 汇总报告 + 失败详情
    
    Note over Main: 自动清理 worktree
```

---

## 六、数据库与端口隔离实战

### 6.1 SQLite 方案

最简单的隔离方式——每个 worktree 使用独立的数据库文件：

```bash
# 每个 worktree 的 .env
DB_PATH="./data/myapp-$(basename $(pwd)).db"
```

### 6.2 PostgreSQL 方案

为每个 worktree 创建独立数据库：

```bash
# 从主项目执行
for db in myapp_oauth myapp_ratefix myapp_refactor; do
  createdb "$db"
  # 运行迁移
  DATABASE_URL="postgresql://localhost:5432/$db" npx prisma migrate deploy
done
```

### 6.3 Docker Compose 方案

```yaml
# docker-compose.worktree.yml
version: '3.8'
services:
  db-${WORKTREE_NAME}:
    image: postgres:15
    environment:
      POSTGRES_DB: myapp_${WORKTREE_NAME}
      POSTGRES_USER: user
      POSTGRES_PASSWORD: pass
    ports:
      - "${DB_PORT}:5432"
```

```bash
# 在每个 worktree 中启动
WORKTREE_NAME=oauth DB_PORT=5433 docker-compose -f docker-compose.worktree.yml up -d
```

### 6.4 Redis 端口隔离

```bash
# 每个 worktree 使用不同 Redis DB 编号（0-15）
REDIS_URL="redis://localhost:6379/1"  # worktree 1
REDIS_URL="redis://localhost:6379/2"  # worktree 2
REDIS_URL="redis://localhost:6379/3"  # worktree 3
```

---

## 七、合并策略与冲突处理

### 7.1 "Rebase Before PR" 模型

推荐的分支策略：

```
Start:  总是从最新的 main 创建分支
Work:   在隔离的 feature 分支和 worktree 中工作
Finish: 创建 PR 前，先 rebase
Push:   git push --force-with-lease
Merge:  PR → staging 测试 → main 生产
Clean:  合并后删除 worktree 和分支
```

```bash
# 在 worktree 中准备 PR
cd ../my-app-oauth
git fetch origin
git rebase origin/main

# 解决可能的冲突后推送
git push --force-with-lease
```

### 7.2 冲突预防策略

```mermaid
flowchart TD
    A[开始规划并行任务] --> B{Claude 分析文件依赖}
    B -->|重叠度低| C[放心并行]
    B -->|有重叠| D{能否拆分文件边界?}
    D -->|能| E[重新划分任务范围]
    D -->|不能| F[串行执行该部分]
    E --> C
    C --> G[创建独立 worktree]
    G --> H[并行执行]
    H --> I{定期 rebase main}
    I -->|无冲突| J[继续开发]
    I -->|有冲突| K[立即解决]
    K --> J
    J --> L[完成 → 创建 PR]
```

### 7.3 用 Claude 辅助冲突分析

在创建 worktree 前，让 Claude 分析任务间冲突风险：

```
> 分析以下三个任务的文件依赖冲突风险：
> 1. 添加 OAuth2 登录 → src/auth/*, src/middleware/*
> 2. 修复 API 限流 → src/api/rateLimiter.ts
> 3. 重构 utils → src/utils/*
> 
> 按低/中/高评估每个任务对的冲突概率。
```

Claude 典型输出：
```
任务对 1-2（OAuth vs 限流）: 低风险 — 文件无重叠
任务对 1-3（OAuth vs 重构）: 低风险 — auth 不依赖 utils
任务对 2-3（限流 vs 重构）: 中风险 — rateLimiter 可能导入 utils 函数
建议：任务 2 和 3 串行执行，或明确约定不修改 utils 的特定导出
```

### 7.4 常见合并冲突处理

**场景：两个 worktree 修改了同一文件的不同部分**

```bash
git merge feature/oauth2
# Auto-merging src/config/routes.ts
# CONFLICT (content): Merge conflict in src/config/routes.ts
```

让 Claude 解决：

```
> 解决当前 merge conflict，保留两个分支的所有变更
```

**场景：package.json 冲突**

```bash
# 两个 worktree 都添加了依赖
git merge feature/oauth2
# CONFLICT in package.json

# 策略：合并后重新安装
git merge feature/oauth2  # 手动解决 package.json 冲突
npm install               # 重新生成 lock file
```

---

## 八、高级技巧

### 8.1 自定义 WorktreeCreate Hook

通过 Hook 完全自定义 worktree 创建逻辑：

```json
// .claude/settings.json
{
  "hooks": {
    "WorktreeCreate": [{
      "command": "bash .claude/scripts/create-worktree.sh",
      "timeout": 30000
    }]
  }
}
```

```bash
#!/bin/bash
# .claude/scripts/create-worktree.sh
BRANCH="$1"
PATH="$2"

# 自定义目录结构
git worktree add "$PATH" -b "$BRANCH"

# 自动复制配置文件
cp .env "$PATH/.env"
cp docker-compose.override.yml "$PATH/"

# 安装依赖
cd "$PATH" && npm install

# 运行数据库迁移
npx prisma migrate deploy
```

### 8.2 Worktree 间会话切换

在 Claude Code 会话中直接切换 worktree：

```
> 切换到 bugfix-123 的 worktree
```

Claude 会使用 `EnterWorktree` 工具直接跳转到 `.claude/worktrees/` 下的对应目录。

### 8.3 批量清理脚本

```bash
#!/bin/bash
# cleanup-worktrees.sh
# 清理所有已合并的 worktree

echo "当前 worktree 列表："
git worktree list

for wt in $(git worktree list --porcelain | grep "^worktree" | cut -d' ' -f2); do
  if [ "$wt" != "$(git rev-parse --show-toplevel)" ]; then
    branch=$(git -C "$wt" branch --show-current)
    # 检查分支是否已合并到 main
    if git branch --merged main | grep -q "$branch"; then
      echo "清理已合并: $wt ($branch)"
      git worktree remove "$wt"
      git branch -d "$branch"
    fi
  fi
done

git worktree prune
echo "清理完成"
```

### 8.4 CLAUDE.md 中的 Worktree 规范

在项目的 `CLAUDE.md` 中加入 worktree 工作规范：

```markdown
## Worktree 工作规范

- 所有新功能必须在 worktree 中开发，使用 `claude --worktree <名称>` 启动
- 每个 worktree 使用独立的数据库（见 .env 配置）
- 端口分配：3001-3010，按 worktree 创建顺序递增
- 每日 rebase main 分支：`git fetch origin && git rebase origin/main`
- 合并前必须通过所有测试：`npm test`
- 合并后立即清理：`git worktree remove <path>`
```

---

## 九、完整实战案例：电商系统并行开发

### 9.1 项目背景

电商平台后端（Node.js + Express + PostgreSQL），需要同时推进：

1. **支付系统集成**（Stripe + 支付宝）
2. **商品搜索优化**（Elasticsearch 重构）
3. **订单导出功能**（CSV/PDF 导出）

### 9.2 第一步：Plan Mode 分析

```bash
cd ~/projects/ecommerce-api
claude

> /plan
请分析以下三个任务的文件依赖关系，评估并行可行性：
1. 集成 Stripe 和支付宝支付（涉及 src/payment/*, src/orders/*, src/webhooks/*）
2. 用 Elasticsearch 重构商品搜索（涉及 src/search/*, src/products/*）
3. 添加订单 CSV/PDF 导出（涉及 src/orders/*, src/exports/*）

注意任务 1 和 3 都涉及 src/orders/，分析具体冲突风险。
```

### 9.3 第二步：创建 Worktree 矩阵

```bash
# 创建三个 worktree
git worktree add ../ecommerce-payment -b feature/payment-integration
git worktree add ../ecommerce-search -b feature/elasticsearch
git worktree add ../ecommerce-export -b feature/order-export

# 配置环境隔离
for i in 1 2 3; do
  cp .env "../ecommerce-$(echo 'payment search export' | cut -d' ' -f$i)/.env"
done

# 修改各 worktree 的端口和数据库
sed -i 's/PORT=3000/PORT=3011/' ../ecommerce-payment/.env
sed -i 's/PORT=3000/PORT=3012/' ../ecommerce-search/.env
sed -i 's/PORT=3000/PORT=3013/' ../ecommerce-export/.env

sed -i 's/myapp_db/myapp_payment/' ../ecommerce-payment/.env
sed -i 's/myapp_db/myapp_search/' ../ecommerce-search/.env
sed -i 's/myapp_db/myapp_export/' ../ecommerce-export/.env

# 安装依赖
for wt in ../ecommerce-payment ../ecommerce-search ../ecommerce-export; do
  (cd "$wt" && npm install)
done
```

### 9.4 第三步：任务分配与执行

```bash
# tmux 设置
tmux new-session -s ecommerce-dev

# 面板 1：支付集成
cd ../ecommerce-payment
claude "集成 Stripe 和支付宝支付：
1. 创建 PaymentService 抽象层
2. 实现 StripePaymentProvider
3. 实现 AlipayPaymentProvider  
4. 添加支付 webhook 处理
5. 只修改 src/payment/ 和 src/webhooks/ 目录
6. 不要修改 src/orders/ 中的导出相关代码
7. 编写完整单元测试和集成测试"

# 面板 2：搜索重构
cd ../ecommerce-search
claude "用 Elasticsearch 重构商品搜索：
1. 安装 @elastic/elasticsearch 依赖
2. 创建 SearchService 接口
3. 实现 ElasticsearchSearchProvider
4. 添加商品索引同步机制
5. 只修改 src/search/ 和 src/products/ 中的搜索逻辑
6. 编写搜索性能基准测试"

# 面板 3：订单导出（注意与支付任务的文件边界）
cd ../ecommerce-export
claude "添加订单导出功能：
1. 创建 ExportService 抽象层
2. 实现 CsvExporter
3. 实现 PdfExporter
4. 添加导出 API 路由
5. 只修改 src/exports/ 和 src/orders/ 中的导出相关函数
6. 不要修改 src/orders/ 中的支付处理逻辑
7. 编写测试"
```

### 9.5 第四步：监控进度

通过 tmux 切换面板查看各 Agent 状态：

```bash
# Ctrl+b + 方向键切换面板
# 查看进度摘要（在主项目目录）
claude --worktree-summary  # 如果可用

# 或直接查看各 worktree 的 git 状态
for wt in ../ecommerce-payment ../ecommerce-search ../ecommerce-export; do
  echo "=== $(basename $wt) ==="
  git -C "$wt" status --short
  echo ""
done
```

### 9.6 第五步：合并策略

由于任务 1（支付）和任务 3（导出）都涉及 `src/orders/`，采用串行合并：

```bash
cd ~/projects/ecommerce-api

# 先合并不涉及冲突的搜索重构
git merge feature/elasticsearch

# 再合并支付集成
git merge feature/payment-integration

# 最后合并导出功能（可能有冲突，需要仔细解决）
git merge feature/order-export

# 如果冲突，让 Claude 解决
claude "解决 src/orders/ 目录下的 merge conflict，保留两个功能的所有变更"
```

### 9.7 第六步：清理

```bash
git worktree remove ../ecommerce-payment
git worktree remove ../ecommerce-search  
git worktree remove ../ecommerce-export
git worktree prune
git branch -d feature/payment-integration feature/elasticsearch feature/order-export
```

---

## 十、常见问题与解决方案

### Q1：worktree 中 npm install 特别慢

**解决方案**：使用符号链接共享 `node_modules`：

```bash
# 在主项目有完整 node_modules 后
ln -s $(pwd)/node_modules ../ecommerce-payment/node_modules
```

注意：如果不同分支的依赖版本不同，此方法可能导致问题。

### Q2：数据库迁移冲突

**解决方案**：每个 worktree 使用独立数据库，只在合并到 main 后运行一次迁移：

```bash
# 各 worktree 开发时用自己的测试数据库
# 合并后统一迁移
git merge feature/payment-integration
npx prisma migrate dev --name add-payment-tables
```

### Q3：端口被占用

**解决方案**：创建端口分配表：

```bash
# .claude/port-registry.txt
# Worktree 端口分配表
# main: 3000
# worktree-1: 3001
# worktree-2: 3002
# ...

# 启动前检查端口
check_port() {
  lsof -i :$1 >/dev/null 2>&1 && echo "端口 $1 被占用" || echo "端口 $1 可用"
}
```

### Q4：忘记清理 worktree 导致 .git/worktrees/ 膨胀

**解决方案**：设置定期清理 cron 或 git hook：

```bash
# .git/hooks/post-merge（在主仓库中）
#!/bin/bash
echo "检查过期 worktree..."
git worktree prune
git worktree list
```

### Q5：非 Git 项目怎么办

Claude Code 支持非 Git VCS 的 worktree。配置 `WorktreeCreate` 和 `WorktreeRemove` hooks 即可自定义隔离逻辑（如 SVN、Fossil 等）。

---

## 十一、最佳实践总结

```mermaid
mindmap
  root((Worktree 并行开发))
    规划先行
      Plan Mode 分析依赖
      识别文件冲突风险
      低重叠 → 并行
      高重叠 → 串行
    环境隔离
      独立数据库
      独立端口
      .worktreeinclude
      独立 .env
    执行纪律
      每日 rebase main
      明确文件边界
      及时响应权限请求
      代码审查
    合并策略
      Rebase before PR
      先合无冲突的
      Claude 辅助解冲突
      合并后跑全量测试
    清理维护
      合并即清理
      定期 prune
      删除远端分支
      端口释放
```

| 原则 | 说明 |
|------|------|
| **任务不超 3 个** | 超过 3 个并行 session，管理开销开始抵消并行收益 |
| **文件零重叠** | 并行任务间文件重叠度应低于 10% |
| **定期 rebase** | 每天至少一次从 main rebase，避免分支漂移 |
| **即时清理** | 合并后立即删除 worktree 和分支 |
| **明确指令** | 给每个 Claude session 清晰的文件边界约束 |

---

## 训练营适用性评估

| 训练营类型 | 适用性 | 教学时长 | 说明 |
|-----------|--------|---------|------|
| AI 开发工具实战营 | ★★★★★ | 3-4 小时 | 核心技能，直接提升开发效率 |
| DevOps 工程师训练营 | ★★★★☆ | 2-3 小时 | 侧重 CI/CD 集成和环境隔离 |
| 全栈开发训练营 | ★★★★☆ | 3 小时 | 实际项目中并行处理需求常见 |
| 团队管理训练营 | ★★★☆☆ | 2 小时 | 了解并行开发模式的管理要点 |
| 初学者训练营 | ★★☆☆☆ | 不建议 | 需要 Git 基础和 Claude Code 经验 |

**前置要求**：Git 基础操作、Claude Code 基本使用、熟悉项目依赖管理。

---

## 参考来源

1. [Run parallel sessions with worktrees — Claude Code 官方文档](https://code.claude.com/docs/en/worktrees) — 官方 worktree 功能文档，涵盖 `--worktree` 标志、subagent 隔离、.worktreeinclude 配置
2. [The Complete Guide to Git Worktrees with Claude Code — Muthukrishnan](https://notes.muthu.co/2026/02/the-complete-guide-to-git-worktrees-with-claude-code/) — 详细的 worktree + Claude Code 并行开发指南，含自动化脚本
3. [Parallel Development with ClaudeCode and Git Worktrees — DEV Community](https://dev.to/yooi/parallel-development-with-claudecode-and-git-worktrees-305a) — 实战经验分享，含冲突分析和 "Rebase Before PR" 模型
4. [How to Run Multiple Claude Code Agents in Parallel — BSWen](https://docs.bswen.com/blog/2026-03-21-git-worktrees-parallel-claude-code/) — tmux 并行编排方案和合并策略
5. [How to Use Git Worktrees with Claude Code — MindStudio](https://www.mindstudio.ai/blog/git-worktrees-claude-code-parallel-development) — 数据库隔离、端口冲突处理等环境配置细节

> [!tip] 51学通信知识星球
> **星主：爱卫生**（微信：gprshome201101）——公众号「51学通信」创办者，19 年通信行业运维与讲师经验，著有《GPRS网络信令实例详解》《EPC原理与实践》《5G核心网原理与实践》三本纸质书（各大电商平台有售）。
> **星球定位**：深耕 5G 核心网、IMS、NFV/AI、云原生等 ICT 领域，主打运维岗位与信令分析。
> **当前规模**：5200 篇主题 / 990 个回答，198 元/年。
> **加入福利**：加入星球后请加爱卫生微信，拉您进知识星球年度陪伴与答疑群——不限量回复您的各种问题，另有群内分享。
> **AI 加持**：51学通信知识星球已作为 skill 接入 WorkBuddy，使用 deepseek-4-flash 在海量星球帖子中精准找贴、找视频、找 FAQ 和案例，做总结、找文档和 PPT 等场景全覆盖。

![51学通信知识星球海报-扫码加入](https://wiki.500nian.com/images/zhixingqiu_qrcode.png)