书籍 / Claude 完全指南：从 API 到 Agent 生产实战
第 45 章

权限系统：5层优先级 / 规则语法 / Sandbox 沙箱完整配置指南

第四十五章：Claude Code 多 Agent 模式：并行任务与 Worktree 隔离

45.1 单 Agent 的瓶颈

Claude Code 在单 Agent 模式下是串行工作的：它处理完一个任务才开始下一个。对于大多数日常编程任务，这已经足够快。但当任务变得庞大时，串行的局限性就显现出来了。

想象你有一个重构任务：需要同时更新 API 层、数据库模型、前端组件和测试文件——这四个部分在逻辑上是相互独立的。单 Agent 会按顺序处理这些任务，而多 Agent 模式可以让四个 Claude 实例同时工作。

Claude Code 的多 Agent 模式建立在两个机制之上：

45.2 Agent 工具：协调器与执行器模式

在 Claude Code 中，AI 可以使用一个特殊工具叫做 Agent，它允许当前 Claude 实例（协调器）启动新的 Claude 实例（执行器）来完成子任务。

这建立了一个层级结构：

用户
 └── 协调器 Claude（Orchestrator）
      ├── 执行器 Claude 1：负责后端 API 修改
      ├── 执行器 Claude 2：负责数据库迁移
      ├── 执行器 Claude 3：负责前端组件更新
      └── 执行器 Claude 4：负责测试更新

启动多 Agent 的对话方式

向 Claude 描述一个需要并行处理的复杂任务：

我需要将项目从 REST API 迁移到 GraphQL。这个任务可以分解为几个独立部分：
1. 创建 GraphQL schema 和 resolvers
2. 更新数据库查询层
3. 更新前端 API 调用
4. 更新相关测试

请使用多 Agent 模式并行处理这些任务，使用 Git Worktree 隔离每个任务的工作空间。

Claude 会分析任务，确认哪些部分可以并行，然后启动多个 Agent 实例。

Claude 作为协调器的工作流

当 Claude 担任协调器角色时，它会：

  1. 任务分解：将大任务拆解为可以独立执行的子任务
  2. 依赖分析：识别哪些子任务有顺序依赖，哪些可以并行
  3. 分配工作：为每个并行任务创建独立的 Worktree 和 Agent
  4. 汇总结果：等待所有 Agent 完成，检查结果，处理冲突
  5. 合并集成：将各分支的修改合并到主分支

45.3 Git Worktree：并行任务的物理隔离

Git Worktree 是 Git 的一项功能，允许你从同一个 Git 仓库同时检出多个工作目录，每个目录可以处于不同的分支：

# 查看当前 Worktree 状态
git worktree list

# 输出示例：
# /path/to/project          abc1234 [main]
# /path/to/project-feat-api def5678 [feature/graphql-api]
# /path/to/project-feat-db  ghi9012 [feature/graphql-db]

每个 Worktree 有独立的工作目录，但共享同一个 .git 数据库，这意味着：

手动创建 Worktree

# 在新 Worktree 中创建并切换到新分支
git worktree add ../project-graphql-api -b feature/graphql-api

# 查看结果
git worktree list

# 在另一个终端中，进入新 Worktree
cd ../project-graphql-api
# 这里处于 feature/graphql-api 分支，但共享主项目的 git 历史

让 Claude 管理 Worktree

在实际的多 Agent 工作流中，你可以让协调器 Claude 负责创建和管理 Worktree：

请帮我并行完成以下任务，为每个任务创建独立的 Git Worktree：

任务 1：graphql-schema
  - 工作目录：../project-graphql-schema
  - 分支：feature/graphql-schema
  - 任务：创建 GraphQL schema 文件和类型定义

任务 2：graphql-resolvers  
  - 工作目录：../project-graphql-resolvers
  - 分支：feature/graphql-resolvers
  - 任务：实现 GraphQL resolvers（依赖 schema，等 schema 完成后开始）

任务 3：frontend-migration
  - 工作目录：../project-frontend
  - 分支：feature/frontend-graphql
  - 任务：更新前端 Apollo Client 配置和查询

Claude 会执行：

# 协调器创建 Worktree
git worktree add ../project-graphql-schema -b feature/graphql-schema
git worktree add ../project-frontend -b feature/frontend-graphql

# 然后为每个 Worktree 启动 Agent
# Agent 1 在 ../project-graphql-schema 中工作
# Agent 3 在 ../project-frontend 中工作（可以并行，因为不依赖 schema）
# Agent 2 等待 schema 完成后再开始

45.4 并行任务的依赖管理

并非所有任务都可以完全并行。多 Agent 模式中的关键技术是依赖图分析：

任务依赖图示例：

[schema 定义] ──────────────→ [resolver 实现]
      │                              │
      ↓                              ↓
[类型生成]                    [集成测试]
      │
      ↓
[前端类型更新] → [前端组件更新]

在这个依赖图中：

向协调器 Claude 说明这些依赖关系：

任务有以下依赖：
- schema 必须第一个完成
- resolver 和类型生成可以在 schema 完成后并行
- 前端工作可以在类型生成完成后开始
- 集成测试最后运行

请按照这个依赖顺序安排并行工作，最大化并行度。

45.5 后台 Agent：启动异步任务

Claude Code 支持以"后台模式"启动 Agent，让 Agent 在后台运行而不阻塞当前对话：

以后台模式启动以下任务，我会继续其他工作：

后台任务 1：运行完整的测试套件并生成报告
  命令：pnpm test --coverage && pnpm test:e2e
  完成后告诉我结果

后台任务 2：对整个 src/ 目录运行依赖分析
  命令：npx depcheck
  完成后告诉我未使用的依赖

这种模式特别适合：

45.6 多 Agent 的实际案例：大型重构

以下是一个完整的多 Agent 工作流示例：将一个 Node.js 项目从 JavaScript 迁移到 TypeScript。

准备阶段：协调器分析

协调器 Claude 首先分析代码库：

# 分析文件结构
find src/ -name "*.js" | wc -l           # 统计 JS 文件数量
find src/ -name "*.js" -exec ls -la {} \; # 检查文件大小

# 识别入口文件和核心模块
cat package.json | jq '.main, .scripts'

基于分析，协调器确定迁移策略：

分析结果：src/ 下有 47 个 JS 文件，分为 5 个独立模块：
- src/api/（12 个文件）—— REST API 路由
- src/services/（15 个文件）—— 业务逻辑
- src/db/（8 个文件）—— 数据库层
- src/utils/（7 个文件）—— 工具函数
- src/middleware/（5 个文件）—— Express 中间件

建议并行迁移 utils 和 db（相互独立），然后并行迁移 services 和 middleware，最后迁移 api（依赖其他模块）。

执行阶段：并行迁移

# 协调器创建工作树
git worktree add ../migrate-utils -b migrate/utils
git worktree add ../migrate-db -b migrate/db

# 启动两个 Agent 并行工作
# Agent 1：迁移 src/utils/ 到 TypeScript
# Agent 2：迁移 src/db/ 到 TypeScript

每个 Agent 在其 Worktree 中独立工作：

Agent 1（utils 迁移）：

# 在 ../migrate-utils 中
cd src/utils/
# 逐个文件：添加类型注解、将 .js 改为 .ts、修复类型错误
for file in *.js; do
  # Claude 处理每个文件的迁移
done
pnpm tsc --noEmit  # 验证没有类型错误
pnpm test utils    # 运行相关测试
git add . && git commit -m "migrate: convert src/utils to TypeScript"

Agent 2（db 迁移）：类似流程，在独立 Worktree 中进行。

合并阶段：协调器整合结果

# 两个并行任务都完成后
git checkout main

# 合并 utils 迁移
git merge migrate/utils --no-ff -m "merge: TypeScript migration for utils"

# 合并 db 迁移
git merge migrate/db --no-ff -m "merge: TypeScript migration for db"

# 如果有冲突（不太可能，因为工作在不同目录），手动处理

# 清理 Worktree
git worktree remove ../migrate-utils
git worktree remove ../migrate-db

45.7 Worktree 的限制与注意事项

使用 Git Worktree 时需要注意以下限制：

共享文件的冲突

某些文件不适合在多个 Worktree 中同时修改：

在任务分配时，确保这类共享文件只由一个 Agent 负责修改。

Node.js 项目的 node_modules 问题

每个 Worktree 独立安装依赖可能占用大量磁盘空间。解决方案：

# 使用 pnpm（支持跨 Worktree 的内容寻址存储）
pnpm install  # 自动复用主目录的依赖

# 或者创建软链接
ln -s ../project/node_modules ./node_modules

同一分支不能用于多个 Worktree

Git 不允许同一个分支同时在两个 Worktree 中检出。确保每个并行任务使用不同的分支名称。

45.8 多 Agent 模式的适用场景判断

不是所有任务都值得使用多 Agent 模式，以下是判断框架：

适合多 Agent 的场景：

不适合多 Agent 的场景：

经验法则： 如果任务预计耗时少于 15 分钟，单 Agent 串行处理更简单高效；超过 30 分钟且可分解，多 Agent 开始有价值。

小结

Claude Code 的多 Agent 模式通过 Agent 工具和 Git Worktree 的组合，实现了大规模并行开发任务的自动化。

关键要点：

本章评分
4.7  / 5  (3 评分)

💬 留言讨论