Claude Code多Agent并行开发实战：Worktree隔离与并行工作流全攻略

graph TB
    A[Git仓库 .git] --> B[主工作目录 main分支]
    A --> C[Worktree 1 feature-auth分支]
    A --> D[Worktree 2 fix-bug-123分支]
    A --> E[Worktree 3 feature-api分支]

    B --> F[Claude Code 会话1]
    C --> G[Claude Code 会话2]
    D --> H[Claude Code 会话3]
    E --> I[Claude Code 会话4]

    style A fill:#f9f,stroke:#333
    style F fill:#bbf,stroke:#333
    style G fill:#bfb,stroke:#333
    style H fill:#fbb,stroke:#333
    style I fill:#fbf,stroke:#333

# 查看当前worktree列表
git worktree list

# 基于main分支创建新worktree
git worktree add ../feature-auth feature-auth

# 基于新分支创建worktree（-b参数）
git worktree add -b feature-new-ui ../worktrees/new-ui main

# 在worktree中工作
cd ../feature-auth
# ... 进行开发 ...
git add . && git commit -m "feat: add auth module"

# 完成后移除worktree
cd /path/to/main-repo
git worktree remove ../feature-auth

# 启动Claude Code并自动创建worktree
claude --worktree

# 指定worktree名称
claude --worktree --worktree-name feature-auth

# 在指定worktree中启动
claude --worktree --worktree-path ../existing-worktree

sequenceDiagram
    participant User as 开发者
    participant CC as Claude Code
    participant Git as Git仓库
    participant WT as Worktree目录

    User->>CC: claude --worktree
    CC->>Git: git worktree add .claude/worktrees/wt-xxx
    Git-->>WT: 创建隔离工作目录
    CC->>CC: 切换工作目录到WT
    CC-->>User: 会话就绪（在worktree中）

    Note over User,WT: 开发过程...

    User->>CC: 完成任务
    CC->>Git: git add & commit（在worktree分支）
    User->>CC: /exit
    CC->>User: 保留或移除worktree？

# 在项目根目录创建 .worktreeinclude
cat > .worktreeinclude << 'EOF'
.env.local
docker-compose.override.yml
.claude/settings.json
.vscode/settings.json
EOF

cd ~/projects/my-app
git status  # 确保工作目录干净
git pull origin main

# 终端标签页1：主工作目录（保持main分支）
# 无需操作，直接运行 claude

# 终端标签页2：创建worktree用于Feature A
git worktree add .claude/worktrees/feat-auth -b feature/auth main
cd .claude/worktrees/feat-auth
claude

# 终端标签页3：创建worktree用于Bug Fix
git worktree add .claude/worktrees/fix-bug-42 -b fix/bug-42 main
cd .claude/worktrees/fix-bug-42
claude

# 标签页1（main）- 代码审查
> 请审查src/api/目录下的代码，找出性能瓶颈

# 标签页2（feature/auth）- 新功能
> 实现JWT认证模块，包含登录、注册、Token刷新接口

# 标签页3（fix/bug-42）- Bug修复
> 修复Issue #42：用户列表分页在超过1000条时返回空结果

# 回到主仓库
cd ~/projects/my-app

# 合并各worktree的提交
git merge feature/auth
git merge fix/bug-42

# 清理worktree
git worktree remove .claude/worktrees/feat-auth
git worktree remove .claude/worktrees/fix-bug-42

#!/bin/bash
# parallel-claude.sh - 并行Claude Code编排脚本

TASKS_FILE="$1"
REPO_ROOT="$(git rev-parse --show-toplevel)"
SESSION_NAME="claude-parallel-$(date +%Y%m%d-%H%M%S)"

# 检查任务文件
if [ -z "$TASKS_FILE" ]; then
    echo "用法: ./parallel-claude.sh tasks.md"
    exit 1
fi

# 解析任务文件（每行一个任务，格式：分支名 | 任务描述）
declare -a BRANCHES=()
declare -a TASKS=()

while IFS='|' read -r branch task; do
    branch=$(echo "$branch" | xargs)
    task=$(echo "$task" | xargs)
    [ -z "$branch" ] && continue
    BRANCHES+=("$branch")
    TASKS+=("$task")
done < "$TASKS_FILE"

NUM_TASKS=${#BRANCHES[@]}
echo "🚀 启动 $NUM_TASKS 个并行Claude Code会话..."

# 创建tmux会话
tmux new-session -d -s "$SESSION_NAME" -c "$REPO_ROOT"

for i in "${!BRANCHES[@]}"; do
    BRANCH="${BRANCHES[$i]}"
    TASK="${TASKS[$i]}"
    WT_PATH="$REPO_ROOT/.claude/worktrees/$BRANCH"

    # 创建worktree
    git worktree add "$WT_PATH" -b "$BRANCH" main 2>/dev/null || \
    git worktree add "$WT_PATH" "$BRANCH" 2>/dev/null

    if [ $i -eq 0 ]; then
        # 第一个窗口
        tmux rename-window -t "$SESSION_NAME:0" "$BRANCH"
    else
        # 后续窗口
        tmux new-window -t "$SESSION_NAME" -n "$BRANCH" -c "$WT_PATH"
    fi

    # 在窗口中启动Claude Code并发送任务
    tmux send-keys -t "$SESSION_NAME:$BRANCH" "cd $WT_PATH && claude" Enter
    sleep 3
    tmux send-keys -t "$SESSION_NAME:$BRANCH" "$TASK" Enter

    echo "  ✅ 已启动: $BRANCH"
done

# 附着到tmux会话
echo ""
echo "📋 所有会话已启动！运行以下命令查看："
echo "   tmux attach -t $SESSION_NAME"
tmux attach -t "$SESSION_NAME"

feature/user-profile | 实现用户个人资料编辑页面，包含头像上传、基本信息修改、密码修改
fix/memory-leak | 修复WebSocket连接断开后未释放事件监听器导致的内存泄漏问题，文件在src/ws/
feature/api-v2 | 设计并实现API v2版本的速率限制中间件，支持按用户、按IP、按端点三级限制
test/integration | 为src/api/目录下的所有端点编写集成测试，覆盖正常流程和错误场景
docs/api-docs | 根据src/routes/中的路由定义，生成OpenAPI 3.0规范的API文档

chmod +x parallel-claude.sh
./parallel-claude.sh tasks.md

🚀 启动 5 个并行Claude Code会话...
  ✅ 已启动: feature/user-profile
  ✅ 已启动: fix/memory-leak
  ✅ 已启动: feature/api-v2
  ✅ 已启动: test/integration
  ✅ 已启动: docs/api-docs

📋 所有会话已启动！运行以下命令查看：
   tmux attach -t claude-parallel-20260610-143052

graph LR
    A[tasks.md任务文件] --> B[parallel-claude.sh]
    B --> C[创建tmux会话]
    C --> D[窗口1: feature/user-profile]
    C --> E[窗口2: fix/memory-leak]
    C --> F[窗口3: feature/api-v2]
    C --> G[窗口4: test/integration]
    C --> H[窗口5: docs/api-docs]

    D --> I[独立Worktree]
    E --> J[独立Worktree]
    F --> K[独立Worktree]
    G --> L[独立Worktree]
    H --> M[独立Worktree]

    I --> N[git merge]
    J --> N
    K --> N
    L --> N
    M --> N

    N --> O[主分支合并完成]

> 我需要你同时处理以下三个任务：
> 1. 重构src/utils/目录，将通用工具函数提取到独立的npm包
> 2. 为src/api/users.ts添加完整的CRUD接口和错误处理
> 3. 编写E2E测试覆盖用户注册到下单的完整流程
> 
> 请使用Agent工具并行处理这三个任务，每个任务在独立的worktree中进行。

# Agent并行策略

## 自动Worktree隔离
当使用Agent工具处理独立任务时，始终使用isolation: "worktree"参数。

## 任务分发原则
- 无依赖关系的任务可以并行
- 共享文件修改的任务必须串行
- 每个子Agent完成后，在主会话中统一合并

graph TD
    A[评估分支依赖关系] --> B{分支间有依赖?}
    B -->|否| C[按优先级逐个合并]
    B -->|是| D[先合并基础分支]
    D --> E[再合并依赖分支]
    C --> F[运行完整测试套件]
    E --> F
    F --> G{测试通过?}
    G -->|是| H[推送合并结果]
    G -->|否| I[回退并修复冲突]
    I --> F

# 1. 先合并bug修复（最安全、最紧急）
git checkout main
git merge fix/memory-leak
make test  # 确认通过

# 2. 再合并基础设施变更（其他分支可能依赖）
git merge feature/api-v2
make test

# 3. 然后合并功能开发
git merge feature/user-profile
make test

# 4. 最后合并文档和测试（最低风险）
git merge test/integration
git merge docs/api-docs
make test

# 并行开发区域划分

## 分支与文件映射
- feature/user-profile: src/pages/profile/*, src/components/UserForm/*
- fix/memory-leak: src/ws/*, src/utils/eventBus.ts
- feature/api-v2: src/middleware/rateLimit.ts, src/config/rateLimit.ts
- test/integration: tests/integration/*
- docs/api-docs: docs/openapi/*

## 交叉文件处理
修改以上范围之外的文件时，需要先在主分支完成。

# 在每个worktree中创建锁文件
echo "feature/user-profile" > .claude/worktree-lock

# Worktree锁机制
修改文件前，先检查.git/worktree-lock文件。如果该文件被其他分支锁定，
则需要等待或协调。

# .github/workflows/worktree-conflict-check.yml
name: Worktree Conflict Detection
on:
  pull_request:
    types: [opened, synchronize]

jobs:
  check-conflicts:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Check merge conflicts with other open PRs
        run: |
          # 获取所有open的PR分支
          BRANCHES=$(gh pr list --state open --json headRefName -q '.[].headRefName')
          for branch in $BRANCHES; do
            if [ "$branch" != "${{ github.head_ref }}" ]; then
              git merge --no-commit --no-ff "origin/$branch" 2>/dev/null
              if [ $? -ne 0 ]; then
                echo "⚠️ 冲突检测: ${{ github.head_ref }} 与 $branch 有文件冲突"
                git merge --abort
              else
                git merge --abort
              fi
            fi
          done

# 在主仓库中尝试合并
git merge feature/user-profile

# 如果有冲突，启动Claude Code
claude

> 当前有合并冲突，请帮我解决。
> 策略：对于src/utils/helpers.ts，保留两个分支的修改（合并而非覆盖）。
> 对于package.json，使用feature分支的版本。

graph TD
    A[单体应用重构] --> B[阶段1: 分析依赖]
    A --> C[阶段2: 提取模块]
    A --> D[阶段3: 更新引用]
    A --> E[阶段4: 测试验证]

    B --> B1[Agent: 生成依赖图]

    C --> C1[Agent A: 提取用户模块]
    C --> C2[Agent B: 提取订单模块]
    C --> C3[Agent C: 提取支付模块]

    D --> D1[Agent D: 更新所有import路径]

    E --> E1[Agent E: 运行全量测试]

    style C1 fill:#bfb
    style C2 fill:#bbf
    style C3 fill:#fbb

claude

> 分析当前项目的模块依赖关系，生成以下内容：
> 1. 文件依赖图（Mermaid格式）
> 2. 按领域分组的模块划分建议
> 3. 每个模块的外部依赖列表
> 4. 重构风险评估（高/中/低）
> 
> 只做分析，不做任何代码修改。

refactor/user-module | 将src/controllers/userController.ts、src/services/userService.ts、src/models/User.ts提取到modules/user/目录，创建独立的index.ts导出文件
refactor/order-module | 将src/controllers/orderController.ts、src/services/orderService.ts、src/models/Order.ts提取到modules/order/目录，创建独立的index.ts导出文件
refactor/payment-module | 将src/controllers/paymentController.ts、src/services/paymentService.ts、src/models/Payment.ts提取到modules/payment/目录，创建独立的index.ts导出文件

./parallel-claude.sh refactor-tasks.md

> 三个模块已经提取完成并合并。现在请：
> 1. 更新src/routes/中所有路由文件的import路径
> 2. 更新src/middleware/中引用了旧路径的文件
> 3. 更新tsconfig.json的paths配置
> 4. 删除旧的文件位置
> 5. 运行npm run build确认编译通过

# 在任何修改之前，先进入Plan Mode
claude

> /plan
> 我要把项目从CommonJS迁移到ES Modules。
> 请先制定详细的迁移计划，包括：
> - 需要修改的文件列表
> - 每个文件的修改策略
> - 依赖链顺序（哪些文件必须先改）
> - 回滚方案

graph LR
    subgraph 上下文窗口 200K tokens
        A[系统提示] --> B[CLAUDE.md内容]
        B --> C[对话历史]
        C --> D[已读取的文件]
        D --> E[工具调用结果]
    end

    F[新请求] --> G{剩余空间足够?}
    G -->|是| H[正常处理]
    G -->|否| I[自动压缩/Compaction]
    I --> J[保留关键信息]
    I --> K[丢弃早期细节]

/compact

/compact 保留以下关键信息：
1. User模块的接口定义和数据库schema
2. 我们决定的错误处理策略（统一用AppError类）
3. 性能优化的决策记录（Redis缓存vs内存缓存，选择Redis）
丢弃所有关于UI样式的讨论和中间调试日志。

project-root/
├── CLAUDE.md                    # 全局项目规范
├── .claude/
│   └── settings.json            # 权限和安全配置
├── src/
│   ├── api/
│   │   └── CLAUDE.md            # API模块专属规范
│   ├── frontend/
│   │   └── CLAUDE.md            # 前端模块专属规范
│   └── tests/
│       └── CLAUDE.md            # 测试规范

# 项目配置

## 技术栈
- Backend: Node.js 20 + Express + TypeScript 5.4
- Database: PostgreSQL 16 + Prisma ORM
- Cache: Redis 7
- Testing: Vitest + Supertest

## 代码规范
- 使用ESLint + Prettier，配置在.eslintrc.json
- 提交信息遵循Conventional Commits
- 所有API端点必须有JSDoc注释
- 错误处理统一使用src/utils/AppError.ts

## 常用命令
- 构建: npm run build
- 测试: npm test
- Lint: npm run lint
- 数据库迁移: npx prisma migrate dev

## 依赖安装
- 优先使用项目已有的依赖，不要引入新的包
- 如果必须引入新包，先在CLAUDE.md中说明理由

## Git规范
- 分支命名: feature/*, fix/*, refactor/*
- 不要在worktree之间共享未提交的代码

# API模块规范

## 路由定义
- 所有路由在src/api/routes/目录下定义
- 使用Express Router，每个资源一个文件
- 路由前缀在src/api/index.ts中统一注册

## 中间件顺序
1. rateLimiter
2. authValidator
3. requestValidator
4. controller
5. errorHandler

## 响应格式
所有API响应遵循统一格式：
{
  "success": boolean,
  "data": T | null,
  "error": { "code": string, "message": string } | null
}

graph TB
    T1[任务1: 评论功能] --> |需要修改| F1[src/models/Review.ts]
    T1 --> |需要修改| F2[src/api/routes/reviews.ts]
    T1 --> |需要修改| F3[src/frontend/ReviewList.tsx]

    T2[任务2: 购物车Bug] --> |需要修改| F4[src/services/CartService.ts]

    T3[任务3: Redis缓存] --> |需要修改| F5[src/middleware/cache.ts]
    T3 --> |需要修改| F6[src/api/routes/products.ts]

    T4[任务4: E2E测试] --> |只新建文件| F7[tests/e2e/payment.flow.ts]

    T5[任务5: API文档] --> |只修改| F8[docs/openapi.yaml]

    style T1 fill:#bfb
    style T2 fill:#fbb
    style T3 fill:#bbf
    style T4 fill:#fbf
    style T5 fill:#ff9

feature/reviews | 实现商品评论功能：1) 创建Review模型（src/models/Review.ts），字段包括userId、productId、rating(1-5)、content、createdAt；2) 创建评论路由（src/api/routes/reviews.ts），包含POST创建评论、GET获取商品评论列表（分页）、DELETE删除自己的评论；3) 创建前端组件（src/frontend/ReviewList.tsx），展示评论列表和提交表单。参考现有src/api/routes/orders.ts的代码风格。
fix/cart-overflow | 修复购物车数量溢出Bug：当用户在购物车中添加超过库存数量的商品时，系统没有正确校验导致可以下单超过库存。修改src/services/CartService.ts的addToCart方法，添加库存校验逻辑，参考src/services/InventoryService.ts的checkStock方法。同时添加单元测试。
feature/redis-cache | 为商品API添加Redis缓存层：1) 创建缓存中间件src/middleware/cache.ts，支持按路由配置TTL；2) 在src/api/routes/products.ts中应用缓存，GET /products缓存5分钟，GET /products/:id缓存1分钟；3) 商品创建/更新/删除时自动清除相关缓存。使用ioredis客户端（项目已安装）。
test/payment-e2e | 编写支付流程的E2E测试：覆盖完整流程：用户登录→浏览商品→添加购物车→填写地址→选择支付方式→确认支付→验证订单状态。使用项目已有的Playwright框架（参考tests/e2e/auth.flow.ts）。至少覆盖：正常支付、余额不足、网络超时三种场景。
docs/api-update | 更新API文档（docs/openapi.yaml）：1) 添加评论相关端点（POST /reviews、GET /products/:id/reviews、DELETE /reviews/:id）；2) 更新购物车端点，添加库存校验相关的400错误响应；3) 添加缓存相关头（X-Cache、X-Cache-TTL）到商品端点响应头。保持与现有文档风格一致。

./parallel-claude.sh tasks-ecommerce.md

# 在tmux中查看所有窗口
# Ctrl+B 然后按 w 显示窗口列表

# 或者在另一个终端查看worktree状态
for wt in .claude/worktrees/*/; do
    branch=$(git -C "$wt" branch --show-current)
    commits=$(git -C "$wt" rev-list --count HEAD ^main)
    echo "📂 $wt → 分支: $branch → 提交数: $commits"
done

📂 .claude/worktrees/feature/reviews/ → 分支: feature/reviews → 提交数: 7
📂 .claude/worktrees/fix/cart-overflow/ → 分支: fix/cart-overflow → 提交数: 3
📂 .claude/worktrees/feature/redis-cache/ → 分支: feature/redis-cache → 提交数: 5
📂 .claude/worktrees/test/payment-e2e/ → 分支: test/payment-e2e → 提交数: 4
📂 .claude/worktrees/docs/api-update/ → 分支: docs/api-update → 提交数: 2

cd ~/projects/ecommerce-app
git checkout main

# 1. Bug修复优先
git merge fix/cart-overflow
echo "✅ 购物车修复已合并"

# 2. 基础设施
git merge feature/redis-cache
echo "✅ Redis缓存已合并"

# 3. 功能开发
git merge feature/reviews
echo "✅ 评论功能已合并"

# 4. 测试
git merge test/payment-e2e
echo "✅ E2E测试已合并"

# 5. 文档
git merge docs/api-update
echo "✅ API文档已合并"

# 全量测试
npm test
echo "🎉 所有分支合并完成，测试通过！"

# 清理worktree
for wt in .claude/worktrees/*/; do
    git worktree remove "$wt"
done
echo "🧹 Worktree已清理"

flowchart TB
    START([开始]) --> ANALYZE[分析任务依赖关系]
    ANALYZE --> PARTITION[按文件范围分区]
    PARTITION --> CREATE_WT[创建5个独立Worktree]
    CREATE_WT --> PARALLEL

    subgraph PARALLEL [并行执行 - 约45分钟]
        direction LR
        A1[Agent 1: 评论功能<br/>7个提交]
        A2[Agent 2: 购物车Bug<br/>3个提交]
        A3[Agent 3: Redis缓存<br/>5个提交]
        A4[Agent 4: E2E测试<br/>4个提交]
        A5[Agent 5: API文档<br/>2个提交]
    end

    PARALLEL --> MONITOR[监控进度]
    MONITOR --> MERGE[按优先级合并]
    MERGE --> TEST[全量测试]
    TEST --> PASS{测试通过?}
    PASS -->|是| CLEAN[清理Worktree]
    PASS -->|否| FIX[修复失败测试]
    FIX --> TEST
    CLEAN --> DONE([完成])

    style PARALLEL fill:#e8f5e9
    style DONE fill:#c8e6c9

# 在CLAUDE.md中添加

## Agent通信协议
每个Agent在worktree根目录创建.agent-status文件，格式：
```json
{
  "task": "feature/reviews",
  "status": "in-progress",  // pending | in-progress | blocked | complete
  "progress": "60%",
  "blocking_issues": [],
  "files_modified": ["src/models/Review.ts", "src/api/routes/reviews.ts"],
  "estimated_completion": "2026-06-10T15:30:00Z"
}

### 8.2 自动冲突检测脚本

```bash
#!/bin/bash
# check-conflicts.sh - 在合并前检测潜在冲突

TARGET_BRANCH="${1:-main}"

for wt in .claude/worktrees/*/; do
    branch=$(git -C "$wt" branch --show-current 2>/dev/null)
    [ -z "$branch" ] && continue

    # 模拟合并检测冲突
    git merge --no-commit --no-ff "$branch" > /dev/null 2>&1
    status=$?

    if [ $status -ne 0 ]; then
        echo "❌ $branch 与 $TARGET_BRANCH 有冲突："
        git diff --name-only --diff-filter=U
        git merge --abort > /dev/null 2>&1
    else
        echo "✅ $branch 无冲突"
        git merge --abort > /dev/null 2>&1
    fi
done

# 项目配置

## 并行开发策略
本项目支持多Agent并行开发，遵循以下原则：

### 文件所有权
- src/api/: API开发Agent拥有修改权
- src/frontend/: 前端开发Agent拥有修改权
- src/services/: 业务逻辑Agent拥有修改权
- tests/: 测试Agent拥有修改权
- docs/: 文档Agent拥有修改权

### 共享文件规则
以下文件可能被多个Agent修改，需要特殊处理：
- package.json: 任何Agent都可以添加依赖，但合并时由主会话处理冲突
- src/types/index.ts: 类型定义变更需要通知其他Agent
- .env.example: 新增环境变量时同步更新

### Worktree生命周期
1. 从main分支创建
2. 完成任务后提交
3. 主会话审核并合并
4. 合并后立即清理worktree

### 合并顺序
1. fix/* (Bug修复，最高优先级)
2. refactor/* (重构)
3. feature/* (新功能)
4. test/* (测试)
5. docs/* (文档)

## 技术栈
[... 你的项目配置 ...]

# 查看推荐并行数
echo "CPU核心: $(nproc)"
echo "推荐并行Agent数: $(( $(nproc) > 4 ? 5 : $(nproc) - 1 ))"

{
  "hooks": {
    "WorktreeCreate": {
      "command": "cp -r /path/to/project /path/to/project-worktree-$CLAUDE_WORKTREE_ID"
    },
    "WorktreeRemove": {
      "command": "rm -rf /path/to/project-worktree-$CLAUDE_WORKTREE_ID"
    }
  }
}

#!/bin/bash
# docker-parallel-claude.sh

TASKS=("task1" "task2" "task3")

for task in "${TASKS[@]}"; do
    docker run -d --name "claude-$task" \
        -v "$(pwd):/workspace" \
        -e "TASK=$task" \
        claude-code-image \
        claude -p "完成以下任务：$task"
done

# 等待所有容器完成
for task in "${TASKS[@]}"; do
    docker wait "claude-$task"
    docker logs "claude-$task" > "result-$task.log"
    docker rm "claude-$task"
done