陌上花开HIMMR
102.29M · 2026-04-08
写在前面
Claude Code 2.1.79 的 Sub-Agent 功能让复杂任务分解并行处理成为可能！这一期我们深入讲解如何使用 Sub-Agents 进行团队协作，让 AI 帮你完成大规模项目开发。
在单一 AI 会话中处理复杂任务时，你是否遇到过以下情况？
Sub-Agents 是 Claude Code 2.1 引入的强大功能，允许你在一个会话中创建多个 AI 助手并行工作。这不仅仅是一个简单的「多线程」概念，而是一套完整的多代理协作系统。
传统方式：单一 AI 串行处理所有任务
┌─────────┐
│ 任务 A │ ──┐
└─────────┘ │
┌─────────┐ ├──→ 总时间 = A + B + C
│ 任务 B │ ──┤
└─────────┘ │
┌─────────┐ │
│ 任务 C │ ──┘
└─────────┘
Sub-Agents：多个 AI 并行处理
┌─────────┐
┌─────→│ 任务 A │
│ └─────────┘
│ ┌─────────┐
├─────→│ 任务 B │
│ └─────────┘ 总时间 = max(A, B, C)
│ ┌─────────┐
└─────→│ 任务 C │
└─────────┘
| 优势 | 说明 |
|---|---|
| 并行加速 | 同时处理多个任务，理论上可获得 7 倍吞吐量提升 |
| 故障隔离 | 单个 Agent 失败不影响其他 Agent 的执行 |
| 专业化分工 | 每个 Agent 可以专注于特定领域，提高输出质量 |
| 资源优化 | 根据任务性质选择合适的模型（如 Haiku 处理简单任务） |
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 的技能列表 |
{
"tool": "Task",
"params": {
"description": "分析代码库结构",
"prompt": "分析这个项目的目录结构，重点关注 src 目录下的模块划分。",
"subagent_type": "explore"
}
}
{
"tool": "Task",
"params": {
"description": "并行开发前端组件",
"prompt": "开发用户管理页面的前端组件，包括列表、编辑表单、详情弹窗。",
"run_in_background": true
}
}
{
"tool": "Task",
"params": {
"description": "重构认证模块",
"prompt": "重构 src/auth 目录下的认证模块，改为使用 JWT。",
"isolation": "worktree"
}
}
{
"tool": "Task",
"params": {
"description": "复杂架构设计",
"prompt": "设计微服务架构方案，包括服务划分、通信协议、部署策略。",
"model": "opus"
}
}
当 run_in_background: true 时：
/tasks 命令查看所有后台任务（也作 /bashes）自动后台
当 CLAUDE_AUTO_BACKGROUND_TASKS 环境变量设置后，超过 120 秒非交互时间，后台任务会自动激活。可以通过 CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1 完全禁用后台任务。
每个 Task 工具调用都会创建一个独立的会话，并返回 session_id。你可以使用这个 ID 继续与同一个 Agent 对话：
// 继续之前的会话
{
"tool": "Task",
"params": {
"session_id": "ses_abc123",
"prompt": "还需要添加单元测试。"
}
}
这对于需要多轮交互的复杂任务非常有用，避免了重复传递上下文。
Claude Code 从以下位置按优先级加载 Agent 配置：
优先级顺序（从高到低）：
1. 项目级 Agent：.claude/agents/ —— 仅在当前项目可用
2. 用户级 Agent：~/.claude/agents/ —— 所有项目可用
3. 托管 Agent：从企业管理设置加载 —— 企业/ MDM
4. 插件 Agent：由安装的插件提供
虽然仍可使用，但新版本推荐使用 Markdown 文件方式定义 Agent：
{
"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}"
}
}
}
推荐使用 Markdown 文件定义 Agent，位置为 .claude/agents/ 目录下的 .md 文件：
.claude/agents/
├── frontend.md # 前端开发 Agent
├── backend.md # 后端开发 Agent
├── code-review.md # 代码审查 Agent
└── test-runner.md # 测试运行 Agent
---
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 |
Claude Code 中的 Agent 定义有三种来源：
BuiltInAgentDefinition — Claude Code 内置，动态系统提示
CustomAgentDefinition — 用户/项目级的 .md 文件
PluginAgentDefinition — 由安装的插件提供
---
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）
- 基础的单元测试
开始工作吧！
---
description: 专业代码审查 Agent，专注于代码质量和安全
tools: [Read, Grep, lsp_*]
model: opus
maxTurns: 30
---
你是专业的代码审查 Agent。审查代码时关注以下方面：
**质量检查**：
- 代码逻辑是否正确
- 是否有潜在的 bug
- 错误处理是否完善
- 是否有内存泄漏风险
**安全检查**：
- 是否有 SQL 注入风险
- 是否有 XSS 漏洞
- 敏感数据是否妥善处理
- 认证授权是否正确
**性能检查**：
- 是否有不必要的重复计算
- 数据库查询是否优化
- 是否有阻塞渲染的代码
**代码风格**：
- 是否遵循项目规范
- 命名是否清晰
- 注释是否充分
输出格式：
```markdown
## 审查结果
### 问题
| 严重程度 | 位置 | 问题描述 | 建议修复 |
|:---|:---|:---|:---|
| 高 | file.ts:42 | ... | ... |
### 建议
- ...
### 优点
- ...
#### 3. 测试运行 Agent
```markdown
---
description: 运行测试并生成报告
tools: [Bash, Read]
model: haiku
background: true
---
你是测试运行 Agent。执行以下步骤：
1. 首先安装依赖：`npm install` 或 `yarn`
2. 运行测试：`npm test` 或指定测试命令
3. 收集失败的测试用例
4. 生成简洁的测试报告，包含：
- 通过/失败/跳过的测试数量
- 失败的测试用例（文件路径和行号）
- 失败原因摘要
输出格式为 Markdown 报告。
Git worktree 允许你为同一个仓库维护多个独立的工作目录。每个 worktree 可以签出不同的分支，使你能够同时在多个分支上工作而无需频繁切换。
项目根目录/
├── .git/ # 共享的 Git 仓库
├── src/ # 主工作目录
├── package.json # 共享的配置
└── ...
│
├── worktree-feature-a/ # 特性分支 worktree
│ ├── .git # 指向主仓库的引用
│ ├── src/ # 独立的文件副本
│ └── package.json # 独立安装的依赖
│
└── worktree-feature-b/ # 另一个 worktree
├── .git
└── src/
当多个 Agent 并行工作时，它们可能会：
Worktree 隔离解决了这些问题，每个 Agent 在独立的文件系统中操作。
---
description: 特性开发 Agent
isolation: worktree
---
{
"tool": "Task",
"params": {
"description": "开发支付功能",
"prompt": "实现支付模块...",
"isolation": "worktree"
}
}
| 阶段 | 操作 | 说明 |
|---|---|---|
| 创建 | claude-code create --project /path --worktree feature/name | 创建目录并签出分支，生成 .claude-code-context.md |
| 开发 | 在独立环境中工作 | 每个 Agent 拥有独立文件系统 |
| 整合 | 合并到主分支 | 解决可能的冲突 |
| 清理 | git worktree remove wt-name | 删除 worktree 和分支 |
# 创建新的 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. 初始化独立的环境配置
# 查看所有 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 确认状态。
CLAUDE.md 作用域，父目录的开发规范不会自动继承npm install 等）当 Agent 需要相互通信时，可以使用 SendMessage 工具：
{
"tool": "SendMessage",
"params": {
"to": "frontend-agent", // Agent 名称
"prompt": "我已完成 API 开发，请告诉我你需要的数据结构。"
}
}
需求分析 → 架构设计 → 并行开发 → 整合测试
↓ ↓ ↓
[Agent A] [Agent B] [Agent C]
↓ ↓
整合结果 ←────────┘
适用场景：具有明确依赖关系的任务，需要按顺序执行。
┌──────────────┐
│ 主 Agent │
│ (协调者) │
└──────┬───────┘
│
┌────┴────┬────────┐
▼ ▼ ▼
┌─────┐ ┌─────┐ ┌─────┐
│ A │ │ B │ │ C │
│前端 │ │后端 │ │测试 │
└─────┘ └─────┘ └─────┘
适用场景：相互独立的任务，可以完全并行处理。
┌─────────┐ 审查 ┌─────────┐ 修复 ┌─────────┐
│ 主 Agent │ ─────────→ │审查 Agent │ ─────────→ │ 主 Agent │
│ 开发 │ │ │ │ 修复 │
└─────────┘ └─────────┘ └─────────┘
适用场景：需要高质量保证的关键代码。
同一任务 → Agent A 方案 → Agent B 方案 → 对比选择
适用场景：需要多种解决方案或不确定最佳实现方式时。
Claude Code 提供了几个内置 Agent，可直接使用：
| Agent 类型 | 用途 | 特点 |
|---|---|---|
General | 通用任务 | 默认 Agent，适用于大多数委托任务 |
Explore | 代码探索 | 只读探索代码库，一次性任务，无后续消息 |
Librarian | 外部搜索 | 搜索外部资源（文档、GitHub 示例、官方文档） |
Plan | 计划生成 | 生成结构化计划，一次性任务，无后续消息 |
Oracle | 技术咨询 | 复杂架构、调试、逻辑问题的专家级咨询 |
Verification | 计划验证 | 验证计划执行（需 feature flag） |
{
"tool": "Task",
"params": {
"subagent_type": "explore",
"description": "查找认证实现",
"prompt": "我需要了解项目中用户认证的实现方式。查找：登录/登出逻辑、token 生成、密码验证。返回相关文件路径和关键代码片段。"
}
}
使用场景：
用于搜索外部资源（如文档、GitHub 示例）：
{
"tool": "Task",
"params": {
"subagent_type": "librarian",
"description": "查找 React 最佳实践",
"prompt": "查找 React 组件的最佳实践，特别关注：状态管理、副作用处理、性能优化。我需要生产级的代码模式。"
}
}
使用场景：
Oracle 是昂贵但高质量的推理模型，用于复杂问题：
{
"tool": "Task",
"params": {
"subagent_type": "oracle",
"description": "架构设计咨询",
"prompt": "我需要设计一个高可用的微服务架构。需要考虑：服务发现、负载均衡、容错机制、部署策略。请给出详细的架构建议和关键技术选型。"
}
}
使用场景：
$ 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
Name: BlogSystemOrchestrator
Description: 博客系统多 Agent 协调器
Commands:
- develop-fullstack: 全栈开发
Subagents:
- AuthAgent: 用户认证模块
- ArticleAgent: 文章管理模块
- CommentAgent: 评论系统模块
- FrontendAgent: 前端界面
实验性功能
Agent Teams 是实验性功能，需要启用 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 或 --agent-teams CLI 标志。还需要远程 feature gate 处于激活状态。
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> | 创建新任务 |
// 完整参数示例
{
"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": [] // 可选：传递的技能列表
}
}
---
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 间传递消息Q4：Worktree 隔离有什么限制？
A：需要注意：
Q5：如何选择合适的模型？
A：参考以下指南：
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 即可继续对话：
{"session_id": "ses_abc123", "prompt": "继续之前的工作..."}
run_in_background: truesession_id 继续重要任务的多轮对话/tasks 检查所有后台任务状态| 功能 | 说明 |
|---|---|
| Task 工具 | 创建和管理 Sub-Agents 的核心 API |
| 自定义 Agent | 通过 Markdown 文件定义专业化 Agent |
| Worktree 隔离 | 独立文件系统，避免冲突 |
| Agent 通信 | SendMessage 实现 Agent 间协作 |
| Agent Teams | 实验性功能，支持同伴 Agent 协作 |
| 内置 Agent | Explore、Librarian、Oracle 等专用 Agent |
| 适用场景 | 复杂项目、多模块并行、大规模重构 |
