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

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

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

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[并行完成]

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

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

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

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

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

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

# 创建新分支的 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

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

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

# 手动方式
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
}

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

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

# 从主项目目录
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]

# 为每个 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

# 每个 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

# .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"

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

# 创建专用 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"

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

# 回到主项目
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

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

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

# .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 的测试结果后，汇总报告。

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

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

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

# 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"

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

# 每个 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

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

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

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

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]

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

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

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

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

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

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

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

#!/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

> 切换到 bugfix-123 的 worktree

#!/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 "清理完成"

## Worktree 工作规范

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

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/，分析具体冲突风险。

# 创建三个 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

# 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. 编写测试"

# 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

cd ~/projects/ecommerce-api

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

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

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

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

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

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

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

# .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 可用"
}

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

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