Claude Code多Agent并行开发：从Subagent到Worktree全实战

graph TD
    A[主Agent<br/>Orchestrator] --> B{任务分析}
    B --> C[模式一：Subagent<br/>同一Worktree内]
    B --> D[模式二：Worktree<br/>物理隔离目录]
    C --> E[轻量级任务<br/>搜索/分析/小修改]
    C --> F[只读任务<br/>代码审查/调研]
    D --> G[写操作任务<br/>功能开发/Bug修复]
    D --> H[长期任务<br/>重构/批量迁移]

请同时执行以下三个任务：
1. 搜索所有使用了deprecated API的文件，列出文件路径和行号
2. 分析src/utils目录的测试覆盖率，找出未覆盖的函数
3. 检查package.json中是否有安全漏洞的依赖

帮我搜索X，然后搜索Y，最后搜索Z

请并行执行以下独立任务，每个任务使用单独的Explore Subagent：

任务A：在src/api/目录中搜索所有使用了fetch的文件，统计每个文件的调用次数

任务B：在tests/目录中搜索所有测试文件，列出哪些源文件缺少对应测试

任务C：搜索所有TODO和FIXME注释，按优先级分类汇总

---
name: code-reviewer
description: 专注于代码审查的Subagent，检查代码质量、安全漏洞和最佳实践
model: sonnet
tools:
  - Read
  - Grep
  - Glob
  - Bash
---

你是一个严格的代码审查专家。你的职责：

1. 检查代码是否符合项目规范
2. 发现潜在的安全漏洞（XSS、注入、敏感数据泄露）
3. 评估错误处理的完整性
4. 检查命名规范和代码风格一致性

审查输出格式：
- 🔴 严重问题（必须修复）
- 🟡 建议改进（推荐修复）
- 🟢 良好实践（值得保留）

不要修改任何文件，只输出审查报告。

---
name: test-writer
description: 自动编写单元测试的Subagent
model: sonnet
tools:
  - Read
  - Write
  - Edit
  - Bash
  - Grep
  - Glob
---

你是一个测试工程师。根据给定的源代码文件：

1. 分析所有导出函数和类的方法
2. 为每个函数设计测试用例（正常路径、边界条件、错误处理）
3. 使用项目已有的测试框架（检查package.json确认）
4. 编写测试文件到对应的tests/目录
5. 运行测试确认全部通过

.claude/
├── agents/
│   ├── reviewer.md      # 代码审查Agent
│   ├── tester.md        # 测试编写Agent
│   └── docs-writer.md   # 文档生成Agent
├── CLAUDE.md            # 项目指令
└── settings.json        # Agent配置

请使用code-reviewer Agent审查src/auth/login.ts文件，审查完告诉我结果

请启动以下后台任务：
1. 使用后台模式让code-reviewer审查整个src/目录
2. 同时使用tester为src/utils/calculator.ts编写测试
3. 两个任务完成后汇报结果

sequenceDiagram
    participant M as 主Agent
    participant W1 as Worktree Agent A
    participant W2 as Worktree Agent B

    M->>W1: 创建worktree, 派生任务A
    M->>W2: 创建worktree, 派生任务B
    W1->>W1: 在隔离目录工作
    W2->>W2: 在隔离目录工作
    W1->>M: 完成任务, 返回结果
    W2->>M: 完成任务, 返回结果
    M->>M: 合并结果/分支

请并行执行以下两个开发任务，每个任务使用独立的Worktree隔离：

任务A：在feature/auth-redesign分支中重写认证模块
任务B：在feature/api-v2分支中升级API路由

两个任务完成后，分别创建PR。

所有并行任务完成后：
1. 汇总每个Agent的修改内容
2. 检查是否有文件冲突
3. 如果无冲突，合并到主分支
4. 如果有冲突，列出冲突文件让我手动处理

graph LR
    A[主仓库<br/>main分支] --> B[Worktree 1<br/>feature/auth]
    A --> C[Worktree 2<br/>feature/api]
    A --> D[Worktree 3<br/>bugfix/login]
    B --> E[独立目录<br/>独立Agent]
    C --> F[独立目录<br/>独立Agent]
    D --> G[独立目录<br/>独立Agent]

# 方法一：CLI直接启动Worktree模式
claude --worktree

# 方法二：指定Worktree名称
claude --worktree --worktree-name feature-auth

# 方法三：在对话中切换到Worktree
# 直接告诉Claude Code：
# "请使用worktree模式开始feature/dashboard的开发"

{
  "worktree": {
    "autoCleanup": true,
    "defaultBranch": "worktree/",
    "includePatterns": [
      "src/**",
      "tests/**",
      "package.json"
    ]
  }
}

# .worktreeinclude - 指定Worktree间同步的文件
CLAUDE.md
.claude/agents/**
.claude/settings.json
.claude/skills/**

# 创建Worktree并启动Claude Code
git worktree add .claude/worktrees/auth feature/auth
cd .claude/worktrees/auth
claude

你是认证模块开发Agent。请在这个Worktree中完成以下任务：
1. 将现有的session认证改为JWT
2. 添加refresh token机制
3. 编写对应的单元测试
4. 完成后创建commit，分支名为feature/auth-jwt

git worktree add .claude/worktrees/api-v2 feature/api-v2
cd .claude/worktrees/api-v2
claude

git worktree add .claude/worktrees/dashboard feature/dashboard
cd .claude/worktrees/dashboard
claude

# 查看各Worktree的状态
git worktree list

# 合并各分支
git checkout main
git merge feature/auth-jwt
git merge feature/api-v2
git merge feature/dashboard

# 清理Worktree
git worktree remove .claude/worktrees/auth
git worktree remove .claude/worktrees/api-v2
git worktree remove .claude/worktrees/dashboard

请执行以下两阶段任务：

第一阶段（并行调研）：
- Subagent A（Explore）：分析现有代码架构，列出所有需要修改的文件
- Subagent B（Explore）：调研最佳实践，给出参考实现方案

第二阶段（Worktree隔离实现）：
- 根据调研结果，使用Worktree模式派生实现Agent
- 实现Agent完成编码后运行测试
- 汇报结果

graph TD
    O[主Agent<br/>接收需求] --> A[Worktree Agent<br/>功能开发]
    O --> B[Worktree Agent<br/>测试编写]
    A --> C{代码完成?}
    B --> D{测试完成?}
    C --> E[Subagent<br/>代码审查]
    D --> E
    E --> F{审查通过?}
    F -->|是| G[合并到主分支]
    F -->|否| A

请使用三Agent并行模式处理以下需求：实现用户导出CSV功能

1. 开发Agent（Worktree隔离）：在feature/export-csv分支实现CSV导出API
2. 测试Agent（Worktree隔离）：在test/export-csv分支编写集成测试
3. 两个Agent完成后，派生审查Agent检查代码质量

要求：
- 开发和测试同时进行
- 审查在两者都完成后启动
- 如果审查不通过，修复后重新审查

请将项目中所有Class组件迁移为Function组件。

使用并行Agent模式：
1. 首先用Explore Agent扫描所有Class组件文件
2. 将文件列表分为5组
3. 每组派生一个Worktree Agent并行迁移
4. 所有Agent完成后，汇总结果并运行全量测试

约束：
- 每个Agent处理不超过10个文件
- 迁移后保持功能不变
- 保留原有的PropTypes类型定义

请用Explore Subagent执行以下任务，只提供必要的上下文：

在src/api/routes/目录中搜索所有使用了req.params.id的地方，
检查是否有SQL注入风险。不需要读取其他目录的文件。

每个Subagent请按以下格式返回结果：

## 任务：[任务名称]
### 状态：[完成/失败/部分完成]
### 修改文件：[文件列表]
### 发现：[关键发现列表]
### 建议：[后续操作建议]

# 项目目录
mkdir parallel-refactor && cd parallel-refactor
git init

# 创建Claude Code配置
mkdir -p .claude/agents

---
name: async-converter
description: 将回调风格代码转换为async/await
model: sonnet
---

你是异步代码转换专家。将目标文件中的所有回调风格代码转换为async/await风格。

转换规则：
1. 将callback(err, result)模式改为throw/return
2. 将Promise回调链改为await表达式
3. 保持函数签名不变（外部接口兼容）
4. 添加适当的try/catch错误处理
5. 转换完成后运行项目测试确认无破坏性变更

---
name: error-handler
description: 添加Express错误处理中间件
model: sonnet
---

你是错误处理专家。为Express.js项目添加统一的错误处理中间件。

要求：
1. 创建src/middleware/errorHandler.js
2. 处理4种错误类型：ValidationError、AuthError、NotFoundError、通用Error
3. 每种错误返回正确的HTTP状态码
4. 在生产环境隐藏错误堆栈
5. 添加请求日志记录

请启动4个并行Worktree Agent处理以下任务：

Agent 1（async-converter）：将src/routes/目录下所有文件转换为async/await
Agent 2（error-handler）：在src/middleware/中添加错误处理中间件
Agent 3（tester）：为src/routes/中每个路由编写集成测试
Agent 4（docs-writer）：根据最终的路由代码更新API文档

约束：
- Agent 1 和 Agent 2 先执行（无依赖）
- Agent 3 在 Agent 1 完成后启动（测试需要基于新代码）
- Agent 4 在所有Agent完成后启动（文档需要反映最终状态）

每个Agent使用独立的Worktree隔离。

graph TD
    START[启动并行任务] --> A1[Agent 1: async转换]
    START --> A2[Agent 2: 错误处理]
    A1 --> A1D{转换完成?}
    A2 --> A2D{中间件完成?}
    A1D -->|是| A3[Agent 3: 测试编写]
    A2D -->|是| WAIT{等待A3}
    A3 --> A3D{测试通过?}
    A3D -->|是| A4[Agent 4: 文档更新]
    A3D -->|否| FIX[修复测试]
    FIX --> A3
    A4 --> MERGE[合并所有分支]
    MERGE --> FINAL[运行全量测试]
    FINAL --> DONE[完成]

# 合并所有分支后运行完整验证
npm test                    # 运行所有测试
npm run lint                # 代码风格检查
npm run build              # 确认构建通过

# 检查Git日志确认所有修改
git log --oneline --graph --all

请帮我分析上一次Subagent调度的效果：

1. 列出所有派生的Subagent及其任务
2. 检查是否有Subagent的任务范围重叠
3. 评估是否有任务应该串行而非并行
4. 建议更优的任务分配方案

# 强制清理残留的Worktree
git worktree prune

# 查看所有Worktree状态
git worktree list

# 手动清理特定Worktree
git worktree remove --force .claude/worktrees/feature-x

## 并行开发规范

### Subagent使用规则
- 只读任务（搜索、分析、审查）：使用Explore Subagent
- 写入任务（编码、修改）：必须使用Worktree隔离
- 单个Subagent任务不超过15分钟
- 并行Subagent不超过8个

### Worktree命名规范
- 格式：{类型}/{简短描述}
- 示例：feature/user-export, bugfix/login-timeout, refactor/api-v2

### 合并策略
- 每个Worktree完成后先自测
- 使用Squash Merge保持主分支整洁
- 合并前必须通过CI

# .github/workflows/parallel-agent.yml
name: Parallel Agent CI

on:
  pull_request:
    branches: [main]

jobs:
  detect-worktree:
    runs-on: ubuntu-latest
    outputs:
      branches: ${{ steps.detect.outputs.branches }}
    steps:
      - uses: actions/checkout@v4
        fetch-depth: 0
      - id: detect
        run: |
          # 检测来自并行Agent的分支
          BRANCHES=$(git branch -r | grep 'worktree/' | jq -R . | jq -s .)
          echo "branches=$BRANCHES" >> $GITHUB_OUTPUT

  test:
    needs: detect-worktree
    strategy:
      matrix:
        branch: ${{ fromJson(needs.detect-worktree.outputs.branches) }}
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          ref: ${{ matrix.branch }}
      - run: npm ci && npm test

# 统计各Worktree的修改量
for wt in .claude/worktrees/*/; do
  echo "=== $(basename $wt) ==="
  git -C "$wt" diff --stat HEAD~5
done

# 计算并行效率
# 理论耗时 = 所有Agent耗时之和
# 实际耗时 = 最长Agent的耗时
# 效率 = 理论耗时 / 实际耗时