13 Sub-agents 并行
本节目标
-
理解 Sub-agent 的核心价值:隔离上下文 + 并行执行
-
掌握何时使用 Sub-agents(探索、审查、并行任务)
-
学会配置自定义 Agent 的 YAML 文件(name、description、tools、model)
-
理解模型选择策略:Haiku 做探索、Sonnet 做实现、Opus 做审查
-
掌握 SendMessage 和 TaskCreate 两种通信机制
-
量化理解 Sub-agents 的 token 效率优势(40%+ 节省)
核心知识点
Sub-agent 的本质:隔离的上下文工作者
Sub-agent 不是一个新的大模型实例,而是一个独立的、隔离的上下文窗口。它与主会话的关系如下:
主会话 (Claude Code) Sub-agent 1 (独立上下文) │ │ ├── 任务分配 ──────────────→ │ 执行探索任务 │ │ 只加载目标文件 │ │ 生成探索报告 │ ←────────────── 结果回传 ── │ │ │ 销毁,释放上下文 ├── 任务分配 ──────────────→ Sub-agent 2 (独立上下文) │ │ 执行审查任务 │ │ ...
关键特性:
-
上下文隔离:每个 Sub-agent 拥有独立的 200K token 上下文窗口
-
按需加载:Sub-agent 只加载任务相关的文件,不被主对话历史污染
-
并行执行:多个 Sub-agent 可以同时运行,不相互阻塞
-
结果序列化:Sub-agent 完成后的输出被压缩为结构化结果,不携带完整对话历史
何时使用 Sub-agents
场景 1:代码库探索
你有一个大型仓库,需要分析某个功能的完整影响范围:
主会话: 启动 3 个探索型 Sub-agents ├── Agent A: 分析 src/api/ 下的所有 API 端点 ├── Agent B: 分析 src/components/ 下的所有组件依赖 └── Agent C: 分析 tests/ 下的测试覆盖情况 3 个 Agents 并行执行 → 汇总报告 → 主会话获得全局视图
如果不用 Sub-agents,主会话需要逐个读取几百个文件,进行一次对话可能就用掉 80% 的上下文窗口。
场景 2:多文件代码审查
一次提交涉及 20 个文件:
主会话: 启动 4 个审查型 Sub-agents ├── Agent A: 审查 5 个前端组件文件 ├── Agent B: 审查 5 个 API 路由文件 ├── Agent C: 审查 5 个数据库迁移文件 └── Agent D: 审查 5 个测试文件 每个 Agent 独立审查 → 汇总审查报告 → 主会话生成总评
场景 3:多视角分析
对同一个技术方案进行多角度评估:
主会话: 启动 4 个分析型 Sub-agents ├── 架构视角: 这个方案是否符合我们的架构原则 ├── 安全视角: 有没有引入新的安全风险 ├── 性能视角: 对性能的影响量化分析 └── 可靠性视角: 边界情况和故障模式分析
自定义 Agent YAML 配置
在 ~/.claude/agents/ 目录下创建 YAML 文件定义自定义 Agent:
# ~/.claude/agents/code-explorer.yml name: code-explorer description: > 代码库探索专家。用于快速扫描和理解代码结构、 依赖关系、API 表面积和测试覆盖情况。 适合在修改代码前进行影响范围分析。 tool: Glob, Grep, Read, Bash(git:*) model: haiku auto_run: true
配置字段说明:
| 字段 | 必需 | 说明 |
|---|---|---|
| name | 是 | Agent 的唯一标识符 |
| description | 是 | 描述此 Agent 的能力和适用场景,影响任务分配的准确性 |
| tool | 是 | 允许的工具列表,使用通配符或具体工具名 |
| model | 否 | 使用的模型,默认 haiku(成本最优) |
| auto_run | 否 | 是否无需用户确认即可自动运行,默认 false |
工具权限控制:
# 只读探索型 Agent tool: Glob, Grep, Read # 代码生成型 Agent tool: Glob, Grep, Read, Write, Edit, Bash(git:*,npm:test) # 完全权限(谨慎使用) tool: *
模型选择策略
这是 Sub-agents 系统中最有智慧的省钱策略——不同任务用不同模型:
任务复杂度 │ │ Opus (审查/决策) │ ───────────────── │ Sonnet (实现/重构) │ ───────────────── │ Haiku (探索/搜索/格式化) │ ───────────────── └──────────────────────→ 成本 典型任务-模型映射: Haiku (最便宜,90% Sonnet 能力): - 全局代码搜索(Grep/Glob) - 依赖关系分析 - 重复代码检测 - 格式化检查 - 文档查询 Sonnet (平衡): - 功能实现 - 代码重构 - 测试编写 - 架构设计 Opus (最深度推理): - 安全审查 - 架构决策 - 复杂调试 - 技术债务评估
实际成本对比:
场景:分析一个 monorepo 中 auth 模块的完整重构影响范围 方案 A:单个 Sonnet 主会话 上下文消耗: 150K tokens 成本: ~$0.45 方案 B:4 个 Haiku Sub-agents 并行 Agent 1: 50K tokens → 分析 API 层 Agent 2: 50K tokens → 分析数据库层 Agent 3: 50K tokens → 分析前端层 Agent 4: 50K tokens → 分析测试层 总成本: ~$0.12 (节约 73%) 总时间: 并行 30 秒 vs 串行 120 秒
SendMessage 与 TaskCreate 通信
Sub-agents 与主会话之间有两种通信方式:
SendMessage (子→主通信)
Sub-agent 通过 SendMessage 将结果汇报给主会话:
[Sub-agent 完成探索任务]
→ SendMessage: {
"status": "completed",
"summary": "auth 模块影响 23 个文件,分布在 4 个包中",
"details": { ... },
"risks": ["passport.js 版本不兼容", "session 存储方案需变更"]
}
TaskCreate (主→子通信)
主会话通过 TaskCreate 创建和分配任务给 Sub-agent:
[主会话]
→ TaskCreate: {
"agent": "code-explorer",
"task": "分析 src/auth/ 目录下所有文件的依赖关系,
重点关注: import 链路、共享类型、测试文件位置",
"context_files": ["src/auth/index.ts", "package.json"],
"expected_output": "JSON 格式的依赖图和影响范围"
}
实操步骤
步骤 1:创建你的第一个自定义 Agent
mkdir -p ~/.claude/agents
# ~/.claude/agents/security-scanner.yml name: security-scanner description: > 安全扫描专家。扫描指定文件中的安全漏洞, 包括:硬编码密钥、SQL 注入、XSS、路径遍历、不安全的依赖。 tool: Read, Grep, Glob, Bash(git:diff,npm:audit) model: sonnet
步骤 2:并行执行多 Agent 任务
在 Claude Code 主会话中:
我需要对这个 PR 做全面分析。请同时启动 3 个 Sub-agents: 1. security-scanner: 扫描所有变更文件的安全问题 2. code-explorer: 分析变更的影响范围和依赖关系 3. test-analyzer: 检查测试覆盖是否充分 所有 Agent 完成后,帮我汇总成一份总评报告。
Claude Code 会并行启动 3 个 Agent:
[Sub-agent: security-scanner] 运行中... [Sub-agent: code-explorer] 运行中... [Sub-agent: test-analyzer] 运行中... [security-scanner] ✅ 完成 发现 2 个 MEDIUM 问题: 错误日志中泄露了用户邮箱 [code-explorer] ✅ 完成 影响范围: 15 个文件, 3 个包 [test-analyzer] ✅ 完成 新增功能覆盖率: 72% (不足 80% 阈值) ===== 汇总报告 ===== 需要修复后才能合并: 测试覆盖率不足,有信息泄露风险
步骤 3:用 Haiku Agent 做代码库 "预热"
这是 Sub-agents 最实用的模式——让 Haiku Agent 先扫描代码库,主会话再接手:
在开始重构 src/payment/ 模块之前,先启动一个 Haiku explorer: @explorer 扫描 src/payment/ 目录,列出: 1. 所有导出函数的签名 2. 所有 import 依赖(项目内部 + 第三方) 3. 每个文件被哪些其他文件引用 4. 关联的测试文件位置
Haiku Agent 以极低成本完成扫描,主会话获得一份结构化的"地图",然后才能精准地执行重构。
避坑指南
坑 1:给 Sub-agent 分配了过于模糊的任务
# 错误:任务描述太模糊 "帮我审查一下代码" → Sub-agent 不知从何下手,可能产出泛泛之谈 # 正确:明确范围、格式和标准 "审查 src/auth/ 下所有文件: 1. 检查是否有硬编码密钥 (按 OWASP 标准) 2. 检查 SQL 查询是否使用了参数化 3. 按严重级别分类,JSON 格式输出 4. 每个问题附上具体行号和修复建议"
坑 2:所有 Agent 都用 Sonnet
Haiku 在搜索和探索任务上的能力是 Sonnet 的 90%,但成本只有 1/3。对于以下任务,Haiku 完全够用:
-
代码搜索和模式匹配
-
文件列表和依赖分析
-
格式化和 lint 检查
-
文档查询和摘要
只有需要生成新代码或做复杂推理时,才切换为 Sonnet 或 Opus。
坑 3:忽略 Agent 的上下文限制
每个 Sub-agent 也有上下文窗口限制(通常 200K tokens)。如果你要求一个 Agent 分析一个 5000 文件的仓库,它会超载。
解决:对大任务进行合理的"分片":
# 不对:"分析整个 src/ 目录" # 应该分片: Agent 1: 分析 src/api/ Agent 2: 分析 src/components/ Agent 3: 分析 src/utils/
坑 4:Sub-agent 输出未结构化
如果 Agent 输出是自由文本格式,主会话可能难以提取关键信息。在任务描述中明确要求输出格式:
请以以下 JSON 格式输出:
{
"issues": [
{
"file": "路径",
"line": 行号,
"severity": "CRITICAL|HIGH|MEDIUM|LOW",
"category": "security|performance|quality|testing",
"description": "问题描述",
"suggestion": "修复建议"
}
],
"summary": "一句话总结"
}
课后作业
作业 1:为你的项目创建 3 个专用 Agent
创建以下 YAML 配置文件:
-
code-explorer: 只读探索,使用 Haiku
-
test-writer: 测试生成,使用 Sonnet
-
pr-analyzer: PR 综合分析,使用 Sonnet
每个 Agent 文件中明确:
-
允许的工具列表
-
适用的模型
-
详细的 description
作业 2:实验并行 vs 串行效率
找一个涉及至少 15 个文件的实际任务:
-
先用串行方式完成(一个主会话逐步执行)
-
再用并行方式完成(拆分为 3+ 个 Sub-agents)
-
对比:
-
总耗时
-
Token 消耗
-
结果质量
-
记录你的发现和结论。
作业 3:设计 Agent "工作流"
为你的团队设计一套标准的 Agent 工作流:
## 新功能开发 Agent 工作流 1. explorer Agent (Haiku): 扫描相关模块,输出影响范围 2. designer Agent (Sonnet): 设计实现方案和接口 3. implementer Agent (Sonnet): 按方案实现代码 4. reviewer Agent (Opus): 审查实现的正确性和安全性 5. tester Agent (Sonnet): 补充测试用例
总结
Sub-agents 系统的真正威力不在于"更快地做同一件事",而在于改变你对任务分解的思考方式:
-
以前你会想"这个任务太大了,塞不进一次对话"
-
现在你可以想"这个任务可以拆成 5 个并行的子任务,用 5 个低成本 Agent 搞定"
模型选择策略(Haiku 探索 / Sonnet 实现 / Opus 审查)的精髓在于:用最便宜的模型做最确定性的事,把最贵的模型留给最模糊的问题。这才是真正的 AI 工程经济学。
记住:一个善于使用 Sub-agents 的开发者,不是"更会用工具",而是"更会拆解问题"。
AtomGit 是由开放原子开源基金会联合 CSDN 等生态伙伴共同推出的新一代开源与人工智能协作平台。平台坚持“开放、中立、公益”的理念，把代码托管、模型共享、数据集托管、智能体开发体验和算力服务整合在一起，为开发者提供从开发、训练到部署的一站式体验。
更多推荐
0
0- 0
已为社区贡献16条内容
所有评论(0)