Claude Code 并行开发实战：Subagents、Agent Teams、Git Worktree 与工作流编排指南

用 Claude Code 开发大型项目时，你是否遇到这样的困境：单个实例处理不过来，上下文越堆越长，响应越来越慢，多个任务只能排队等待？

解决这些问题通常有四条路径：Subagents、Agent Teams、Git Worktree，以及工作流编排。每一条都有其最适用的场景，用对了效率倍增，用错了则事倍功半。

一、痛点：你的 Claude Code 什么时候开始“喘不过气”

单个 Claude 实例处理复杂任务时，通常会遇到三个典型的瓶颈：

节点一：上下文爆炸。 当项目代码量超过几万行，CLAUDE.md、对话历史加上不断打开的文件会把上下文窗口塞满。Claude 开始“失忆”——前面讨论过的事情后面不记得，同一个 Bug 反复修复。这主要是因为模型对超长上下文的检索质量会下降，注意力被严重稀释。

节点二：任务只能串行处理。 想同时让 AI 做两件事？比如一边开发新功能，一边为旧模块补充测试。这在单个实例中几乎不可能。你必须等一个任务彻底完成，才能开启下一个。这中间还伴随着上下文切换的巨大损耗——新会话没有旧会话的记忆，AI 需要重新理解项目。

节点三：多模块开发无法同步推进。 假设你有一个涉及前端、后端和数据库的三层重构任务。单个 Claude 实例每次只能聚焦于一个方向。当你切换到前端时，后端刚刚做出的决策就被中断了；转而处理数据库时，前端刚构建好的模型又需要重新对齐。

这些问题的共同解法是：让多个工作单元并行运行，使它们彼此隔离但又能够有效通信。Claude Code 提供了四套机制来实现这一目标。

二、三种并行方案 + 工作流编排：一张表快速理清

方案	核心作用	适用场景	上手难度
Subagents	同一项目内的多角色分工	一个人管理多个工种（如编码+审查+测试）	★
Agent Teams	多个 Agent 真正并行工作	需要“多个头脑”同时处理不同任务	★★★
Git Worktree	分支级别的硬隔离	长时间重构、多人协作场景	★★
工作流编排	串联与控制各单元	全局协调与任务调度	★★

三、Subagents：用 Markdown 定义你的“团队成员”

3.1 什么是 Subagent

Subagent 本质上是一组存放在特定目录下的 Markdown 文件。它定义了一个“角色”的指令、可用工具以及职责范围。

Claude Code 启动时会自动加载这些 Subagents。之后在对话中直接呼叫角色名称，Claude 就会以对应的角色身份来响应你。

3.2 目录结构：全局 vs 项目级

全局级（跨项目复用）：

~/.claude/agents/
├── code-reviewer.md      # 代码审查员
├── test-writer.md       # 测试工程师
└── security-auditor.md  # 安全审计员

项目级（团队共享，推荐）：

your-project/.claude/agents/
├── frontend-dev.md       # 前端开发
├── backend-dev.md        # 后端开发
└── architect.md          # 架构师

项目级配置的好处是，提交到 Git 仓库后，任何新成员 clone 项目即可拥有完全相同的 AI 角色定义，确保了团队协作效率和标准的一致性。

3.3 如何编写一个 Subagent 文件

# 角色：代码审查员（Code Reviewer）

## 职责
你是一个严格的代码审查员，专注于代码质量、安全性和可维护性。

## 工作原则
- 每次 review 必须覆盖：逻辑错误、安全漏洞、性能问题、代码风格
- 发现问题时必须给出具体的修复建议，不能只说“有问题”
- 优先审查：权限相关代码、数据库操作、外部 API 调用

## 输出格式
每次 review 输出：
1. 问题列表（按严重程度排序）
2. 推荐修复方案
3. 本次 review 综合评分（1-10 分）

## 触发信号
当用户在会话中提到 @code-reviewer 或要求“审查代码”时激活。

关键组成部分：

• 角色名称（顶部的 # 标题）：Subagent 的身份标识
• 职责：这个角色是干什么的
• 工作原则：具体怎么干
• 输出格式：交付什么东西
• 触发信号：什么时候会被激活

3.4 在会话中调用 Subagent

在 Claude Code 的会话中直接呼叫即可：

@code-reviewer
帮我 review 一下 src/auth/login.ts 这个文件

Claude 会自动切换到 code-reviewer 角色，并以该角色的指令集来响应。审查完成后，可以切回主会话继续其他任务。

3.5 实战：同时配置“代码审查员”与“测试工程师”

步骤一：创建角色文件

mkdir -p ~/.claude/agents

# 创建测试工程师角色文件
cat > ~/.claude/agents/test-writer.md << 'EOF'
# 角色：测试工程师（Test Writer）

## 职责
为代码编写可执行的测试用例，确保覆盖核心路径。

## 工作原则
- 测试文件名格式：原文件名 + .test.ts
- 必须包含：正常路径、边界条件、错误处理
- 每个测试用例要有中文注释说明意图
- 使用 Jest + Testing Library

## 输出格式
输出完整的测试文件内容，并说明覆盖了哪些场景。
EOF

# 创建代码审查员角色文件
cat > ~/.claude/agents/code-reviewer.md << 'EOF'
# 角色：代码审查员（Code Reviewer）

## 职责
审查代码质量、安全性和可维护性。

## 工作原则
- 必须覆盖：逻辑错误、安全漏洞、性能问题、代码风格
- 发现问题要给出具体修复建议
- 优先审查：权限、数据库、外部 API 调用相关代码

## 输出格式
问题列表 + 修复建议 + 综合评分（1-10）
EOF

步骤二：在会话中并行调用

@code-reviewer @test-writer
我需要对 src/services/user.ts 做全面审查，同时生成对应的测试用例。
code-reviewer 负责代码审查，test-writer 负责编写测试。
你们两个可以并行工作。

3.6 Subagents 的局限性

Subagents 本质上是同一个 Claude 实例在运行，只是根据不同的指令集切换角色来响应。它并不解决真正的并行计算问题，主要作用是让角色分工更加清晰。要实现真正的并行，需要依靠 Agent Teams。

四、Agent Teams：多窗口并行的正确打开方式

4.1 什么时候需要 Agent Teams

当一个 Claude 实例的处理能力达到瓶颈，需要真正同时运行多个独立的 AI Agent时，Agent Teams 就是你的最佳选择。

典型场景包括：

• 前端界面和后端 API 需要同步开发，且两者互不依赖。
• 需要“架构师”和“开发者”同时在线讨论一个技术设计方案。
• 同一个功能模块，让两个 AI 各自探索不同的实现路径，最后择优合并。

4.2 如何启用 Agent Teams

方法一：通过 settings.json 配置（推荐）

mkdir -p ~/.claude
cat > ~/.claude/settings.json << 'EOF'
{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  },
  "teammateMode": "tmux"
}
EOF

方法二：通过环境变量启用

export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

注意：agentTeams.enabled 是旧版本的写法。当前版本（v2.1+）正确的配置项是 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS 环境变量，或在 settings.json 中设置 "teammateMode": "tmux"。

4.3 tmux 在 Agent Teams 中的作用

在 Agent Teams 中，tmux 是 Claude Code 用来托管多个队友（Agent）窗口的底层容器。

4.3.1 工作原理
Claude Code 会自动：

• 为每个队友创建一个独立的 tmux 窗口。
• 每个窗口拥有独立的终端会话，显示该队友的全部输出。
• 你无需手动执行 tmux split-window 等命令，Claude Code 会自动完成所有窗口管理。

4.3.2 在多个队友窗口间切换

操作	按键
切换到下一个队友窗口	Shift+↑
切换到上一个队友窗口	Shift+↓
直接接管某个队友的操作	先切换到该队友窗口，然后直接输入指令

4.3.3 iTerm2 用户的福音：原生分屏显示
如果你使用 macOS 和 iTerm2，可以开启 tmux 控制模式，获得原生的分屏体验：

# 启动 tmux 控制模式（iTerm2 专用）
tmux -CC

iTerm2 会自动将每个队友窗口渲染为并排的 Split Pane，真正做到同时看到所有 Agent 的输出，无需来回切换窗口。

4.3.4 tmux 基础命令（仅供调试参考）
正常使用时 Claude Code 会自动管理 tmux，以下命令仅在需要手动清理残留会话时使用：

# 查看当前所有 tmux 会话
tmux list-sessions

# 断开会话（会话在后台保持运行）
Ctrl+b 然后按 d

# 重新接入某个会话
tmux attach -t my-project

# 强制删除某个残留会话（出问题时使用）
tmux kill-session -t my-project

4.4 创建你的第一个 Agent Team

步骤一：创建团队配置目录

mkdir -p ~/.claude/teams/dev

步骤二：配置团队成员

cat > ~/.claude/teams/dev/config.json << 'EOF'
{
  "name": "dev",
  "members": [
    {
      "name": "frontend-dev",
      "role": "前端开发",
      "instructions": "你是一个专业的前端开发工程师，擅长 React、TypeScript 和 Tailwind CSS。"
    },
    {
      "name": "backend-dev",
      "role": "后端开发",
      "instructions": "你是一个专业的后端开发工程师，擅长 Node.js、Python FastAPI 和 PostgreSQL。"
    },
    {
      "name": "architect",
      "role": "架构评审",
      "instructions": "你是一个资深架构师，关注系统的可扩展性、稳定性和工程化最佳实践。"
    }
  ]
}
EOF

步骤三：启动团队会话

claude --team dev

启动后，Claude Code 会创建一个主会话，并同时启动各个配置好的成员 Agent。它们可以独立工作，也能够相互通信，这种多 Agent 协作模式非常适合复杂项目的并行开发。

4.5 Agent Teams 任务分配示例

在团队会话中，你可以这样分配任务：

architect：请分析一下 src/architecture 目录的结构，给出模块划分的优化建议。

frontend-dev：根据 architect 的建议，用 Next.js 重构 pages 目录。优先处理 /user 和 /dashboard 两个路由。

backend-dev：同步开始编写 user 和 dashboard 对应的 RESTful API。要求：Node.js + Express + PostgreSQL，API 规范参考 OpenAPI 3.0。

三个 Agent 可以同时接收任务，并行工作。当 architect 的分析结果出来后，frontend-dev 和 backend-dev 可以直接引用该结论，无需你手动传递上下文。

4.6 Agent Teams 的通信机制

团队成员之间通过共享上下文进行通信。主会话持有全局上下文，各成员可以读取和写入。例如，架构师的分析结论会自动对前端和后端开发 Agent 可见，极大减少了信息传递的损耗。

4.7 常见问题与解决

Q：启动 Agent Teams 时报错“tmux not found”
A：你需要先安装 tmux。macOS 用户使用 brew install tmux，Ubuntu/Debian 用户使用 sudo apt install tmux。Windows 用户需要在 WSL2 环境中运行。

Q：团队成员不响应指令
A：检查 ~/.claude/teams/{团队名}/config.json 文件的格式是否正确，确保 JSON 语法严格合法。

Q：队友窗口太多，分不清当前是哪个
A：使用 Shift+↑ / Shift+↓ 切换并确认当前窗口。也可以使用 tmux list-windows 查看所有窗口状态。iTerm2 用户强烈建议使用 tmux -CC 模式，分屏显示更清晰。

五、Git Worktree：分支级别的硬隔离方案

5.1 适用场景

当你需要在一个项目中同时处理多个可能相互冲突的改动时，Git Worktree 提供了比 Agent Teams 更底层、更彻底的隔离方案。

典型场景：

• 同时开发 Feature A 和进行 Refactor B，但两者的修改范围有重叠，无法在同一个分支上串行进行。
• 在保持当前工作目录干净的同时，需要并行处理一个紧急的 Bugfix。
• 多人协作时，避免频繁的合并冲突。

5.2 工作原理

Git Worktree 允许你为同一个 Git 仓库创建多个独立的工作目录，每个目录关联一个独立的分支。这些工作目录共享同一个 .git 对象库（节省存储空间），但文件系统和提交历史是完全隔离的。

5.3 基础命令

# 查看当前所有 Worktree
git worktree list

# 创建新的 Worktree（同时创建新分支）
git worktree add ../feature-auth -b feature/auth
git worktree add ../bugfix-urgent -b bugfix/urgent

# 在新的 Worktree 目录中启动 Claude Code
cd ../feature-auth
claude

# 工作完成后，合并回主分支并清理
git checkout main
git merge feature/auth
git worktree remove ../feature-auth
git branch -d feature/auth

5.4 实战：结合 Claude Code 进行并行开发

# 场景：同时处理新功能开发与数据库重构

# 1. 在主分支目录继续开发新功能
cd ~/projects/myapp
claude
# 在主会话中继续 feature-auth 的功能开发

# 2. 创建独立的 Worktree 进行数据库重构（完全隔离）
git worktree add ../refactor-db -b refactor/db
cd ../refactor-db
claude
# 在新的 Claude 会话中专门进行数据库重构，完全不影响主分支的工作

# 3. 两边工作都完成后，进行合并
git checkout main
git merge refactor/db
git worktree remove ../refactor-db
git branch -d refactor/db

5.5 Git Worktree vs Agent Teams 如何选择

维度	Git Worktree	Agent Teams
隔离级别	分支级别（文件系统硬隔离）	上下文级别（内存隔离）
适用场景	大范围重构、并行分支开发	快速探索、多角色协作讨论
Claude Code 集成	完全兼容，无需特殊配置	需要 tmux 支持
多人协作	完美支持	主要为单人使用设计
上手难度	★★	★★★

选择 Git Worktree：当你的改动可能会相互冲突、需要文件系统级别的硬隔离、或者是多人协作场景时。
选择 Agent Teams：当你需要快速并行探索不同方案、或多个“角色”需要同时在线讨论时。

六、工作流编排：让并行单元有序运转

6.1 什么是工作流编排

前三部分解决了“如何并行”的问题，但多个工作单元如何有序配合、谁先谁后、结果如何整合，这是更高层的“工作流编排”问题。

在 Claude Code 的生态中，工作流编排有三个关键工具：Plan 模式、Agent Teams（本身也具备协作编排能力）、以及项目 CLAUDE.md 中的任务分解规范。其中，Agent Teams 既是执行层，也是编排层的核心——通过它可以协调多个 Agent 按顺序或并行完成复杂任务。

6.2 Plan 模式：动手之前的全局任务分解

Claude Code 内置的 /plan 命令，不是一个执行命令，而是一个任务规划工具。

# 在 Claude Code 会话中输入
/plan

# Claude 会分析当前项目结构和你的需求
# 然后输出一个分步骤的详细计划，等待你确认后才开始执行

输出格式示例：

📋 Plan Mode

正在分析代码库...
正在设计实现方案...

计划概要：
- 使用 d3-cloud 实现词云布局
- 后端添加 /api/news/wordcloud 端点
- 前端创建 WordCloud 组件
- 支持点击筛选、深色主题适配

预估工作量：2 天

详细步骤 [点击展开]...
[批准计划]  [修改建议]  [取消]

Plan 模式的真正价值在于：将“想清楚做什么”和“动手去做”两个阶段分离开。很多时候 AI 编程效率低下，不是因为 AI 写代码慢，而是因为初始指令模糊、需求边界不清、优先级混乱。Plan 模式强制你先获得一个完整的实施方案，再决定是否执行。

6.3 在工作流中嵌入 Plan 模式

将 Plan 模式嵌入到多 Agent 工作流中，可以显著减少返工：

architect（在 Agent Team 中）：使用 /plan 分析 src/modules 中各模块的依赖关系，给出重构的优先级建议。

（等待 architect 的 plan 被确认后）
将任务分配给 frontend-dev 和 backend-dev 分别执行。

backend-dev：
/plan
根据 architect 的分析结果，设计 database schema 的迁移方案。

（等待 backend-dev 的 plan 被确认后）
执行数据库迁移。

这样，每个 Agent 在动手之前都有一个“深思熟虑”的环节，大大降低了“埋头苦干半天，发现方向错了”的风险。

6.4 Multi-Agent 协作工作流模板

一个典型的多 Agent 协同工作流可以这样设计：

阶段一：任务分解（Plan 模式）
├─ 主会话：定义项目总体范围和目标
├─ 执行 /plan：将大目标拆解为具体可执行的模块任务
└─ 输出：完整的任务分解清单

阶段二：角色分配（启用 Agent Teams）
├─ architect：负责整体架构设计和技术方案评审
├─ frontend-dev：负责前端界面和逻辑的实现
└─ backend-dev：负责后端 API 和服务的实现

阶段三：并行执行
├─ 各 Agent 在自己的上下文中独立工作
├─ 通过共享上下文或主会话中转进行必要通信
└─ architect 负责协调解决模块间的设计冲突

阶段四：整合与审查（调用 Subagents）
├─ code-reviewer：对完成的代码进行全面审查
├─ test-writer：为关键模块生成测试用例
└─ architect：进行最终的架构一致性评审

阶段五：合并与部署（使用 Git Worktree）
├─ 将各特性分支合并到 main 分支
└─ 运行完整的集成测试套件

6.5 将工作流模板固化到 CLAUDE.md

上面 6.4 的工作流模板，如果每个新项目都要手动配置一遍就太麻烦了。最佳实践是：将团队配置和工作流规范固化到项目的 CLAUDE.md 文件中，Claude Code 启动时会自动加载这些配置。

在项目根目录创建或编辑 CLAUDE.md，写入以下内容：

# 项目 AI 团队配置

## 默认团队
本项目使用以下 Agent 团队配置：

| 角色 | 职责 |
|------|------|
| architect | 架构设计和技术方案评审 |
| frontend-dev | 前端开发，技术栈：React/TypeScript/Tailwind CSS |
| backend-dev | 后端开发，技术栈：Node.js/Python + PostgreSQL |
| code-reviewer | 代码审查，聚焦安全与代码质量问题 |

## 工作流规范
1. **任务分解**：涉及多模块的复杂任务，必须先使用 `/plan` 进行拆解，确认方案后再执行。
2. **方案优先**：必须由 architect 评审通过的技术方案，才能分配给前端或后端开发执行。
3. **审查前置**：所有代码在合并前必须经过 code-reviewer 的审查。

## 启动命令
```bash
claude --team dev

启动后，architect 会自动分析项目结构并给出初步的模块划分建议。

这样，下次在该项目中启动 Claude Code 时，预设的团队和工作流就会自动就位，无需重复配置，这大大提升了 [DevOps](https://yunpan.plus/f/33-1) 流程的标准化和效率。

### 6.6 实践中容易踩的“坑”

**坑一：Subagent 记忆不共享**
不同的 Subagent 之间不共享对话历史，各自拥有独立的上下文。若需要跨角色传递信息，必须在主会话中进行“中转”。

**坑二：Agent Teams 的上下文窗口竞争**
多个 Agent 同时运行，但它们共享同一个上下文窗口。如果每个 Agent 都输出大量内容，上下文会被迅速填满。解决方案：在每个 Agent 的指令（instructions）中明确限制其输出长度。

**坑三：Git Worktree 合并冲突**
虽然 Worktree 共享 `.git` 对象库，但工作目录完全独立。合并前，请确保主分支（main）没有未提交的改动，否则 Git 的保护机制可能会拒绝合并操作。

**坑四：过度使用 Plan 模式导致节奏拖慢**
每次任务都用 `/plan` 可能会拖慢开发节奏。经验法则：**在多模块重构、引入新技术、进行架构调整时使用 Plan 模式；对于常规的 CRUD 功能或小型需求，可以直接执行。**

### 6.7 Routines：让并行任务定时自动运行
Claude Code 后期版本引入了一个新功能：Routines。前面几节解决了“如何并行”，Routines 则解决了“何时让这些任务自动运行”的问题。

**6.7.1 核心概念**
你可以将“一条指令（prompt）+ 代码仓库 + 触发条件”打包成一个 Routine 配置。这个 Routine 可以提交到 Anthropic 的云端运行，无需你的本地电脑保持开机状态。

三种触发方式：
| 触发方式 | 说明 | 典型场景 |
| :--- | :--- | :--- |
| **定时触发** | 使用 cron 表达式，按小时/天/自定义周期执行 | 每天早上 8 点自动进行代码审查 |
| **API 触发** | 调用 REST API 接口手动触发执行 | 由外部系统（如 CI/CD）触发流水线 |
| **GitHub 事件** | 响应 PR 创建、代码推送、Issue 评论等事件 | PR 创建时自动进行 Code Review |

**6.7.2 与 Agent Teams 的强力组合**
最具潜力的组合是：**Routines 作为调度层，Agent Teams 作为执行层**，构建真正的“无人值守开发流水线”。

Routines（定时触发器，例如 08:00）
└─→ 触发指定的 Agent Teams 开始工作
├─ architect：执行每日架构巡检
├─ backend-dev：自动修复已知的简单 Bug
└─ frontend-dev：检查并更新依赖项
└─→ 将审查或执行结果自动发布为 PR 评论或发送邮件通知

整个流程无需你守在电脑前，醒来即可查看夜间自动完成的工作成果。

**6.7.3 配置示例**
```bash
# 创建一个定时 Routine：每天早上 8 点自动执行代码审查
# 在 Claude Code 会话中执行
/claude routine create \
  --name "morning-review" \
  --prompt "审查从昨晚到现在的所有 commits，重点关注：安全漏洞、性能问题、测试覆盖率" \
  --trigger "0 8 * * *" \
  --repo ./my-project

6.7.4 当前限制与注意事项

• Routines 功能目前处于研究预览阶段，稳定性和功能仍在迭代中。
• 需要能够访问 Anthropic 云端服务。
• 部分触发器（特别是 GitHub 事件）需要配置 webhook 回调地址。
• 模型限制：Routines 运行在 Anthropic 云端，目前仅支持 Claude 官方模型，暂不支持通过 OpenRouter 等第三方 API 路由使用的模型。如果你在使用第三方模型，需等待后续支持或社区方案。

使用建议：先从简单的定时触发 Routine 开始，体验完整流程。待熟悉后，再尝试集成 GitHub 事件触发等高级功能。

七、总结：根据场景选择最佳方案

场景	推荐方案
同一项目内需要多工种分工（如 review + test）	Subagents
需要真正的多 AI Agent 同时处理不同任务	Agent Teams
长时间重构、需要在多个分支上并行开发	Git Worktree
复杂任务需要分解，并由不同角色协调完成	工作流编排（Plan + Teams）
希望定时自动运行任务（无人值守）	Routines（调度层） + Agent Teams（执行层）
快速处理小型需求、单人单线开发	单个 Claude 实例 足矣

这四种方案并非互斥，在一个复杂的项目开发周期中，它们经常被组合使用。用 Subagents 定义清晰的角色，用 Agent Teams 处理需要高度并行的部分，用 Git Worktree 应对需要硬隔离的长期分支，最后用工作流编排将所有环节串联起来，形成高效的自动化开发管线。

掌握这些并行开发策略，能让你在 AI 编程 的探索之路上走得更快、更稳。