写在前面
Claude Code 2.1.79 的 Sub-Agent 功能让复杂任务分解并行处理成为可能!这一期我们深入讲解如何使用 Sub-Agents 进行团队协作,让 AI 帮你完成大规模项目开发。
🎯 一、为什么要使用 Sub-Agents?
传统方式的瓶颈
在单一 AI 会话中处理复杂任务时,你是否遇到过以下情况?
- 任务相互阻塞:需要等待前一个任务完成才能开始下一个
- 上下文稀释:一个任务的处理消耗了其他任务的上下文空间
- 效率低下:大量等待时间被浪费在串行处理上
Sub-Agents 的核心价值
Sub-Agents 是 Claude Code 2.1 引入的强大功能,允许你在一个会话中创建多个 AI 助手并行工作。这不仅仅是一个简单的「多线程」概念,而是一套完整的多代理协作系统。
css
传统方式:单一 AI 串行处理所有任务
┌─────────┐
│ 任务 A │ ──┐
└─────────┘ │
┌─────────┐ ├──→ 总时间 = A + B + C
│ 任务 B │ ──┤
└─────────┘ │
┌─────────┐ │
│ 任务 C │ ──┘
└─────────┘
Sub-Agents:多个 AI 并行处理
┌─────────┐
┌─────→│ 任务 A │
│ └─────────┘
│ ┌─────────┐
├─────→│ 任务 B │
│ └─────────┘ 总时间 = max(A, B, C)
│ ┌─────────┐
└─────→│ 任务 C │
└─────────┘
核心优势
| 优势 | 说明 |
|---|---|
| 并行加速 | 同时处理多个任务,理论上可获得 7 倍吞吐量提升 |
| 故障隔离 | 单个 Agent 失败不影响其他 Agent 的执行 |
| 专业化分工 | 每个 Agent 可以专注于特定领域,提高输出质量 |
| 资源优化 | 根据任务性质选择合适的模型(如 Haiku 处理简单任务) |
🚀 二、Task 工具详解
什么是 Task 工具?
Task 工具(又称 Agent 工具)是 Claude Code 中创建和管理 Sub-Agents 的核心方式。当 Claude 调用这个工具时,它会 spawn 一个拥有独立对话上下文、工具访问权限,以及可选的隔离 git worktree 的子代理。
工具参数一览
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
description |
字符串 | ✅ | 任务的简短描述(3-5 个词),用于标识任务 |
prompt |
字符串 | ✅ | 完整的任务提示词,包含 Agent 需要完成的具体工作 |
subagent_type |
字符串 | ❌ | 指定专用 Agent 类型(如 explore、librarian、oracle) |
model |
字符串 | ❌ | 覆盖默认模型:sonnet、opus、haiku |
run_in_background |
布尔值 | ❌ | 设置为 true 时异步运行,Claude 会在完成时收到通知 |
isolation |
字符串 | ❌ | 设置为 "worktree" 时在隔离的 git worktree 中运行 |
cwd |
字符串 | ❌ | Agent 工作目录的绝对路径,覆盖默认工作目录 |
name |
字符串 | ❌ | Agent 名称,用于后续通过 SendMessage 寻址 |
session_id |
字符串 | ❌ | 现有会话 ID,用于继续之前的 Agent 对话 |
load_skills |
数组 | ❌ | 传递给 Agent 的技能列表 |
基础使用示例
1. 同步执行(阻塞等待结果)
json
{
"tool": "Task",
"params": {
"description": "分析代码库结构",
"prompt": "分析这个项目的目录结构,重点关注 src 目录下的模块划分。",
"subagent_type": "explore"
}
}
2. 异步执行(后台运行)
json
{
"tool": "Task",
"params": {
"description": "并行开发前端组件",
"prompt": "开发用户管理页面的前端组件,包括列表、编辑表单、详情弹窗。",
"run_in_background": true
}
}
3. 隔离执行(使用 worktree)
json
{
"tool": "Task",
"params": {
"description": "重构认证模块",
"prompt": "重构 src/auth 目录下的认证模块,改为使用 JWT。",
"isolation": "worktree"
}
}
4. 指定模型
json
{
"tool": "Task",
"params": {
"description": "复杂架构设计",
"prompt": "设计微服务架构方案,包括服务划分、通信协议、部署策略。",
"model": "opus"
}
}
后台任务机制
当 run_in_background: true 时:
- 立即返回:Agent 立即返回任务 ID,Claude Code 继续处理其他事务
- 完成通知:任务完成后,系统会发送通知
- 任务管理 :可以通过
/tasks命令查看所有后台任务(也作/bashes)
自动后台
当 CLAUDE_AUTO_BACKGROUND_TASKS 环境变量设置后,超过 120 秒非交互时间,后台任务会自动激活。可以通过 CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1 完全禁用后台任务。
任务会话管理
每个 Task 工具调用都会创建一个独立的会话,并返回 session_id。你可以使用这个 ID 继续与同一个 Agent 对话:
json
// 继续之前的会话
{
"tool": "Task",
"params": {
"session_id": "ses_abc123",
"prompt": "还需要添加单元测试。"
}
}
这对于需要多轮交互的复杂任务非常有用,避免了重复传递上下文。
📦 三、Agent 配置详解
配置文件位置
Claude Code 从以下位置按优先级加载 Agent 配置:
markdown
优先级顺序(从高到低):
1. 项目级 Agent:.claude/agents/ ------ 仅在当前项目可用
2. 用户级 Agent:~/.claude/agents/ ------ 所有项目可用
3. 托管 Agent:从企业管理设置加载 ------ 企业/ MDM
4. 插件 Agent:由安装的插件提供
agents.json(旧版配置)
虽然仍可使用,但新版本推荐使用 Markdown 文件方式定义 Agent:
css
{
"agents": {
"frontend": {
"model": "claude-sonnet-4-20250514",
"description": "前端开发专家",
"instructions": "你是一个专业的前端开发者,擅长 React、Vue 等框架"
},
"backend": {
"model": "claude-opus-4-5-20251120",
"description": "后端开发专家",
"instructions": "你是一个专业的后端开发者,擅长 Node.js、Python 等"
},
"feature": {
"isolation": "worktree",
"worktreePath": "./features/{name}"
}
}
}
🎨 四、自定义 Agent 完整指南
Markdown 文件格式
推荐使用 Markdown 文件定义 Agent,位置为 .claude/agents/ 目录下的 .md 文件:
bash
.claude/agents/
├── frontend.md # 前端开发 Agent
├── backend.md # 后端开发 Agent
├── code-review.md # 代码审查 Agent
└── test-runner.md # 测试运行 Agent
Agent 文件结构
yaml
---
description: 运行完整的测试套件并总结失败情况
tools: [Bash, Read]
model: haiku
permissionMode: default
maxTurns: 20
mcpServers: []
hooks: []
skills: []
memory: project
background: false
isolation: worktree
---
你是一个测试运行 Agent。运行 `npm test` 并报告所有失败,包含文件路径和行号。
完整配置字段说明
| 字段 | 类型 | 说明 |
|---|---|---|
description |
字符串 | 必需。描述 Agent 的功能和使用场景 |
tools |
数组 | 允许使用的工具白名单(如 [Bash, Read, Edit]) |
disallowedTools |
数组 | 明确禁止使用的工具 |
model |
字符串 | 使用的模型。可选值:sonnet、opus、haiku、inherit(继承父 Agent 模型) |
effort |
字符串 | 努力级别,影响思考预算 |
permissionMode |
字符串 | 权限模式,如 plan、auto |
maxTurns |
数字 | Agent 停止前的最大交互轮数 |
mcpServers |
数组 | 可用的 MCP 服务器(可以是名称引用或内联配置) |
hooks |
数组 | Agent 启动时注册的会话级钩子 |
skills |
数组 | 预加载的技能名称 |
memory |
字符串 | 持久化记忆范围:user(用户级)、project(项目级)、local(本地) |
background |
布尔值 | 为 true 时,spawn 时总是作为后台任务运行 |
isolation |
字符串 | 设置为 worktree 时总是在隔离的 git worktree 中运行 |
initialPrompt |
字符串 | 首次用户消息前追加的文本,支持斜杠命令 |
requiredMcpServers |
数组 | 声明需要的 MCP 服务器;如果未配置则隐藏该 Agent |
Agent 定义类型
Claude Code 中的 Agent 定义有三种来源:
css
BuiltInAgentDefinition --- Claude Code 内置,动态系统提示
CustomAgentDefinition --- 用户/项目级的 .md 文件
PluginAgentDefinition --- 由安装的插件提供
实战:创建专业 Agent
1. 前端开发 Agent
yaml
---
description: 专业前端开发 Agent,擅长 React、TypeScript、样式解决方案
tools: [Bash, Read, Edit, Write, Glob, Grep, lsp_*]
model: sonnet
skills: [frontend-ui-ux, vercel-react-best-practices]
maxTurns: 50
---
你是专业的前端开发 Agent。你需要:
1. **代码规范**:遵循 React 最佳实践,使用 TypeScript 严格类型
2. **组件设计**:创建可复用、组合优先的组件
3. **样式方案**:优先使用 Tailwind CSS,或使用 CSS Modules
4. **性能优化**:实现懒加载、memo 优化、避免不必要的重渲染
5. **可访问性**:确保组件符合 WCAG 标准
当你需要创建组件时,确保包含:
- 完整的 TypeScript 类型定义
- 必要的 props 接口
- 合理的默认值
- 样式(使用 tailwind 或 css modules)
- 基础的单元测试
开始工作吧!
2. 代码审查 Agent
yaml
---
description: 专业代码审查 Agent,专注于代码质量和安全
tools: [Read, Grep, lsp_*]
model: opus
maxTurns: 30
---
你是专业的代码审查 Agent。审查代码时关注以下方面:
**质量检查**:
- 代码逻辑是否正确
- 是否有潜在的 bug
- 错误处理是否完善
- 是否有内存泄漏风险
**安全检查**:
- 是否有 SQL 注入风险
- 是否有 XSS 漏洞
- 敏感数据是否妥善处理
- 认证授权是否正确
**性能检查**:
- 是否有不必要的重复计算
- 数据库查询是否优化
- 是否有阻塞渲染的代码
**代码风格**:
- 是否遵循项目规范
- 命名是否清晰
- 注释是否充分
输出格式:
```markdown
## 审查结果
### 问题
| 严重程度 | 位置 | 问题描述 | 建议修复 |
|:---|:---|:---|:---|
| 高 | file.ts:42 | ... | ... |
### 建议
- ...
### 优点
- ...
yaml
#### 3. 测试运行 Agent
```markdown
---
description: 运行测试并生成报告
tools: [Bash, Read]
model: haiku
background: true
---
你是测试运行 Agent。执行以下步骤:
1. 首先安装依赖:`npm install` 或 `yarn`
2. 运行测试:`npm test` 或指定测试命令
3. 收集失败的测试用例
4. 生成简洁的测试报告,包含:
- 通过/失败/跳过的测试数量
- 失败的测试用例(文件路径和行号)
- 失败原因摘要
输出格式为 Markdown 报告。
⚙️ 五、工作树隔离(Worktree Isolation)
什么是 Worktree?
Git worktree 允许你为同一个仓库维护多个独立的工作目录。每个 worktree 可以签出不同的分支,使你能够同时在多个分支上工作而无需频繁切换。
bash
项目根目录/
├── .git/ # 共享的 Git 仓库
├── src/ # 主工作目录
├── package.json # 共享的配置
└── ...
│
├── worktree-feature-a/ # 特性分支 worktree
│ ├── .git # 指向主仓库的引用
│ ├── src/ # 独立的文件副本
│ └── package.json # 独立安装的依赖
│
└── worktree-feature-b/ # 另一个 worktree
├── .git
└── src/
为什么需要隔离?
当多个 Agent 并行工作时,它们可能会:
- 修改同一个文件的不同部分
- 创建冲突的分支
- 相互覆盖对方的更改
- 在不同功能上工作时弄脏主工作区
Worktree 隔离解决了这些问题,每个 Agent 在独立的文件系统中操作。
Worktree 配置
方式一:在 Agent 配置中设置
yaml
---
description: 特性开发 Agent
isolation: worktree
---
方式二:通过 Task 工具参数
json
{
"tool": "Task",
"params": {
"description": "开发支付功能",
"prompt": "实现支付模块...",
"isolation": "worktree"
}
}
Worktree 生命周期
| 阶段 | 操作 | 说明 |
|---|---|---|
| 创建 | claude-code create --project /path --worktree feature/name |
创建目录并签出分支,生成 .claude-code-context.md |
| 开发 | 在独立环境中工作 | 每个 Agent 拥有独立文件系统 |
| 整合 | 合并到主分支 | 解决可能的冲突 |
| 清理 | git worktree remove wt-name |
删除 worktree 和分支 |
创建 Worktree 命令
bash
# 创建新的 worktree
claude-code create --project /path/to/repo --worktree feature/auth
# 这会执行以下操作:
# 1. 创建 /path/to/repo/wt-feature-auth 目录
# 2. 创建并签出 feature/auth 分支
# 3. 生成 .claude-code-context.md
# 4. 初始化独立的环境配置
清理命令
bash
# 查看所有 worktree
git worktree list
# 移除 worktree
git worktree remove wt-feature-auth
# 删除本地分支
git branch -d feature/auth
# 删除远程分支
git push origin --delete feature/auth
注意
使用 --force 删除 worktree 可能丢失未保存的更改。删除前使用 git worktree list 确认状态。
Worktree 隔离的重要注意事项
- CLAUDE.md 隔离 :每个 worktree 有独立的
CLAUDE.md作用域,父目录的开发规范不会自动继承 - 依赖安装 :每个 worktree 需要独立安装依赖(
npm install等) - 非 Git 目录:在非 Git 目录中,可能强制使用 worktree 隔离
- 配置同步:大型项目中需要仔细管理各 worktree 间的配置一致性
🤝 六、Agent 通信与协作
SendMessage 工具
当 Agent 需要相互通信时,可以使用 SendMessage 工具:
json
{
"tool": "SendMessage",
"params": {
"to": "frontend-agent", // Agent 名称
"prompt": "我已完成 API 开发,请告诉我你需要的数据结构。"
}
}
团队协作模式
1. 流水线模式
css
需求分析 → 架构设计 → 并行开发 → 整合测试
↓ ↓ ↓
[Agent A] [Agent B] [Agent C]
↓ ↓
整合结果 ←────────┘
适用场景:具有明确依赖关系的任务,需要按顺序执行。
2. 并行独立模式
css
┌──────────────┐
│ 主 Agent │
│ (协调者) │
└──────┬───────┘
│
┌────┴────┬────────┐
▼ ▼ ▼
┌─────┐ ┌─────┐ ┌─────┐
│ A │ │ B │ │ C │
│前端 │ │后端 │ │测试 │
└─────┘ └─────┘ └─────┘
适用场景:相互独立的任务,可以完全并行处理。
3. 评审模式
┌─────────┐ 审查 ┌─────────┐ 修复 ┌─────────┐
│ 主 Agent │ ─────────→ │审查 Agent │ ─────────→ │ 主 Agent │
│ 开发 │ │ │ │ 修复 │
└─────────┘ └─────────┘ └─────────┘
适用场景:需要高质量保证的关键代码。
4. 并行实验模式
css
同一任务 → Agent A 方案 → Agent B 方案 → 对比选择
适用场景:需要多种解决方案或不确定最佳实现方式时。
📚 七、内置 Agent 详解
Claude Code 提供了几个内置 Agent,可直接使用:
| Agent 类型 | 用途 | 特点 |
|---|---|---|
General |
通用任务 | 默认 Agent,适用于大多数委托任务 |
Explore |
代码探索 | 只读探索代码库,一次性任务,无后续消息 |
Librarian |
外部搜索 | 搜索外部资源(文档、GitHub 示例、官方文档) |
Plan |
计划生成 | 生成结构化计划,一次性任务,无后续消息 |
Oracle |
技术咨询 | 复杂架构、调试、逻辑问题的专家级咨询 |
Verification |
计划验证 | 验证计划执行(需 feature flag) |
Explore Agent 用法
json
{
"tool": "Task",
"params": {
"subagent_type": "explore",
"description": "查找认证实现",
"prompt": "我需要了解项目中用户认证的实现方式。查找:登录/登出逻辑、token 生成、密码验证。返回相关文件路径和关键代码片段。"
}
}
使用场景:
- 理解现有代码库结构
- 查找特定模式的实现
- 探索模块间的依赖关系
Librarian Agent 用法
用于搜索外部资源(如文档、GitHub 示例):
json
{
"tool": "Task",
"params": {
"subagent_type": "librarian",
"description": "查找 React 最佳实践",
"prompt": "查找 React 组件的最佳实践,特别关注:状态管理、副作用处理、性能优化。我需要生产级的代码模式。"
}
}
使用场景:
- 查找官方文档
- 搜索 GitHub 上的实现示例
- 了解外部库的用法
Oracle Agent 用法
Oracle 是昂贵但高质量的推理模型,用于复杂问题:
json
{
"tool": "Task",
"params": {
"subagent_type": "oracle",
"description": "架构设计咨询",
"prompt": "我需要设计一个高可用的微服务架构。需要考虑:服务发现、负载均衡、容错机制、部署策略。请给出详细的架构建议和关键技术选型。"
}
}
使用场景:
- 复杂架构设计决策
- 疑难问题调试
- 多系统权衡分析
💡 八、实战:并行开发示例
场景:开发一个完整的博客系统
less
$ claude
> 帮我开发一个博客系统,包含:
> - 用户认证模块(注册、登录、JWT)
> - 文章管理模块(CRUD、分类、标签)
> - 评论系统模块(评论、回复、点赞)
> - 前端界面(React + TypeScript)
Claude Code:
好的!这是一个复杂的多模块任务,我将启动四个 Sub-Agents 并行开发:
🤖 [Agent 1: 用户认证]
→ isolation: worktree
→ 开发 src/auth 目录
→ JWT 认证、注册登录、权限验证
🤖 [Agent 2: 文章管理]
→ isolation: worktree
→ 开发 src/articles 目录
→ 文章 CRUD、分类标签、搜索
🤖 [Agent 3: 评论系统]
→ isolation: worktree
→ 开发 src/comments 目录
→ 评论、回复、点赞、通知
🤖 [Agent 4: 前端界面]
→ isolation: worktree
→ 开发 src/components 和 src/pages
→ React 组件和页面
[并行执行中... 各自独立开发]
✅ [Agent 1] 用户认证模块完成
✅ [Agent 2] 文章管理模块完成
✅ [Agent 3] 评论系统模块完成
✅ [Agent 4] 前端界面完成
正在整合所有模块...
在 CLAUDE.md 中配置 Agent 团队
在项目的 CLAUDE.md 文件中可以定义 Agent 团队结构:
yaml
# CLAUDE.md
Name: BlogSystemOrchestrator
Description: 博客系统多 Agent 协调器
Commands:
- develop-fullstack: 全栈开发
Subagents:
- AuthAgent: 用户认证模块
- ArticleAgent: 文章管理模块
- CommentAgent: 评论系统模块
- FrontendAgent: 前端界面
🔧 九、Agent Teams(实验性功能)
实验性功能
Agent Teams 是实验性功能,需要启用 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 或 --agent-teams CLI 标志。还需要远程 feature gate 处于激活状态。
什么是 Agent Teams?
Agent Teams 允许 Claude spawn 同伴(teammate)Agent,这些 Agent 作为对等进程而非直接子代理运行。同伴 Agent 可以从协调者接收后续消息并异步协作。
团队参数
当 Agent Teams 启用时,Task 工具新增以下参数:
| 参数 | 说明 |
|---|---|
name |
spawn 的同伴名称,用于通过 SendMessage({to: name}) 寻址 |
team_name |
团队名称;省略时使用当前团队上下文 |
mode |
spawn 的同伴权限模式(如 plan) |
协调者模式
设置 CLAUDE_CODE_COORDINATOR_MODE=1 会将标准内置 Agent 列表替换为协调者专用的 Agent,用于管理 worker Agent 池。
⌨️ 十、完整命令与参数速查
命令行命令
| 命令 | 功能 |
|---|---|
claude --worktree <name> |
创建 worktree |
claude code |
启动交互式会话 |
会话内命令
| 命令 | 功能 |
|---|---|
/agents |
列出所有配置的 Agent |
/tasks |
列出所有后台任务(也作 /bashes) |
/agent <name> |
创建指定类型的 Agent |
/task <description> |
创建新任务 |
Task 工具完整参数
json
// 完整参数示例
{
"tool": "Task",
"params": {
"description": "简短描述", // 必填:3-5 个词的任务标识
"prompt": "完整任务提示", // 必填:Agent 需要完成的工作
"subagent_type": "explore", // 可选:专用 Agent 类型
"model": "sonnet", // 可选:sonnet/opus/haiku
"run_in_background": false, // 可选:是否异步执行
"isolation": "worktree", // 可选:是否隔离执行
"cwd": "/path/to/dir", // 可选:工作目录
"name": "agent-name", // 可选:Agent 名称
"session_id": "ses_xxx", // 可选:继续已有会话
"load_skills": [] // 可选:传递的技能列表
}
}
Agent Markdown 配置字段速查
yaml
---
description: Agent 描述(必需)
tools: [允许的工具列表]
disallowedTools: [禁止的工具]
model: sonnet|opus|haiku|inherit
effort: low|medium|high|maximum
permissionMode: auto|plan|restricted
maxTurns: 20
mcpServers: [MCP 服务器列表]
hooks: [钩子列表]
skills: [技能列表]
memory: user|project|local
background: true|false
isolation: worktree
initialPrompt: 初始提示文本
requiredMcpServers: [必需的 MCP 服务器]
---
Agent 的系统提示...
📝 十一、常见问题
Q1:Sub-Agents 消耗更多 tokens 吗?
A:是的,每个 Sub-Agent 都会消耗额外的 tokens。但并行处理的效率提升通常值得这笔开销。特别是在以下场景中收益明显:
- 多模块独立开发
- 大规模代码重构
- 并行测试执行
Q2:可以限制 Sub-Agents 的数量吗?
A:Claude Code 最多支持 7 个并行 Agent。你可以通过合理分配任务来控制并发数量,避免资源耗尽。
Q3:Sub-Agents 可以共享上下文吗?
A:默认情况下不能直接共享。可以通过以下方式传递信息:
- 使用
SendMessage在 Agent 间传递消息 - 通过共享文件(如 JSON、Markdown)交换数据
- 使用共享的 MCP 服务
Q4:Worktree 隔离有什么限制?
A:需要注意:
- 项目必须是 Git 仓库
- 每个 worktree 需要独立安装依赖
- 父 worktree 的 CLAUDE.md 不会自动继承到子 worktree
- 非 Git 目录中可能强制使用 worktree 隔离
Q5:如何选择合适的模型?
A:参考以下指南:
- Haiku:简单、快速的批量任务
- Sonnet:日常开发任务(默认)
- Opus:复杂逻辑、架构决策、高质量要求
Q6:后台任务自动激活是什么?
A:当 CLAUDE_AUTO_BACKGROUND_TASKS 环境变量设置后,如果用户超过 120 秒没有与 Claude 交互,后台任务会自动激活继续执行。可以通过 CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1 禁用此功能。
Q7:如何继续与 Sub-Agent 对话?
A:使用 Task 工具的 session_id 参数。每次调用 Task 都会返回 session_id,后续使用该 ID 即可继续对话:
json
{"session_id": "ses_abc123", "prompt": "继续之前的工作..."}
🎯 十二、最佳实践清单
- 为每个专业 Agent 定义清晰的职责范围
- 优先使用 worktree 隔离避免文件冲突
- 长时间运行的任务使用
run_in_background: true - 为关键 Agent 命名以便通信
- 合理使用模型:简单任务用 Haiku,复杂任务用 Opus
- 使用
session_id继续重要任务的多轮对话 - 完成后使用
/tasks检查所有后台任务状态 - 定期清理不再使用的 worktree
- 在 CLAUDE.md 中定义 Agent 团队结构
- 使用内置 Agent(Explore、Librarian、Oracle)处理特定场景
🎉 总结
| 功能 | 说明 |
|---|---|
| Task 工具 | 创建和管理 Sub-Agents 的核心 API |
| 自定义 Agent | 通过 Markdown 文件定义专业化 Agent |
| Worktree 隔离 | 独立文件系统,避免冲突 |
| Agent 通信 | SendMessage 实现 Agent 间协作 |
| Agent Teams | 实验性功能,支持同伴 Agent 协作 |
| 内置 Agent | Explore、Librarian、Oracle 等专用 Agent |
| 适用场景 | 复杂项目、多模块并行、大规模重构 |