字节笔记本
2026年10月6日 · 约 15 分钟读完
Agent 编程课 17：Subagent 并行编排实战
本文是本站 Agentic 编程实战课系列的第 17 讲，主题是 Subagent（子智能体）与并行编排。没读过前面的内容也不影响上手：这一讲自成一体，从一个常见痛点讲起，讲完就能照着做。
很多人用 Agent 的习惯是：开一个会话，从头指挥到尾，所有事都让一个 Agent 干。任务一大，这个会话就会越来越慢、越来越忘。这一讲换个玩法：不再只带一个兵，而是指挥一群 Agent 并行干活。Subagent 是主 Agent 调度出来的"子 Agent"，每个负责一个独立的子任务。用好了，原本要一天的工作，可能一小时就能收工。
一、什么是 Subagent
一句话定义：Subagent 就是一个被主 Agent 调度的子 Agent，负责一个独立的子任务。
打个比方，主 Agent 是包工头，手底下有几个专业工人：砌墙工专管前端，水电工专管后端 API，油漆工专管样式，质检员专管测试。包工头不需要亲自干所有活，它负责分工、协调、验收。
单 Agent 在大项目里有四个瓶颈：
- 上下文爆炸：一个会话干太多事，前面学到的信息后面就忘了；
- 无法并行：A 任务必须等 B 任务结束才能开始，而这种等待很多时候并不必要；
- 专业度不够：一个 Agent 从头调到底，没有针对具体工种的专项优化；
- 错误传染：A 模块的 bug 混进 B 模块的产出里。
Subagent 的解法正好一一对应：每个 subagent 拥有独立上下文，互不污染；多个 subagent 并行执行；每个 subagent 有专属角色，系统提示词单独优化；错误被隔离在单个 subagent 内部，不会扩散。
二、哪些任务适合交给 Subagent
不是所有事都需要 subagent，判断标准只有一句话：这两个任务能同时干吗？能，就拆给 subagent 并行；不能，就老实串行。
适合的场景：
| 场景 | 例子 |
|---|---|
| 独立可并行的任务 | 同时做前端页面、后端 API 和测试用例 |
| 专项深挖 | 一个 subagent 专攻安全审计，另一个专攻性能优化 |
| 大量重复 | 100 个文件都要跑同样的检查，开 100 个 subagent 并行 |
| 跨域调研 | 同时调研 5 个技术方案的优劣 |
| 多视角评审 | 一个 subagent 演开发者，一个演用户，一个演攻击者 |
不适合的场景：
| 场景 | 原因 |
|---|---|
| 强依赖的串行任务 | 后端没做完，前端无从下手 |
| 简单任务 | 杀鸡用牛刀，调度开销超过收益 |
| 需要共享上下文的任务 | subagent 之间不共享记忆，硬拆会丢信息 |
| 新手阶段 | 先把单 Agent 用熟，再上 subagent |
三、实战：用 Subagent 并行优化一个项目
拿一个具体的销售数据看板项目做全面优化。主 Agent 负责调度，四个 subagent 并行开工：
┌─→ Sub A: 性能优化（数据加载、图表渲染）
[主 Agent] ──────┼─→ Sub B: 用户体验（loading 状态、错误提示）
调度 + 集成 ├─→ Sub C: 安全审计（SQL 注入、XSS 检查）
└─→ Sub D: 测试补全（边界用例、集成测试）
给主 Agent 的指令可以直接照抄：
任务：并行优化销售看板项目。请用 4 个 subagent 并行处理以下任务，
每个 subagent 独立工作，最后由你整合结果。
Subagent A，性能优化：检查 src/data_loader.py 和 src/calculator.py，
找出可以缓存、批量处理、减少重复计算的地方，报告 3 到 5 个具体优化点和预期收益。
Subagent B，用户体验：检查 src/render.py 和最终 dashboard.html，
找出加载状态缺失、错误提示不友好、移动端适配差等问题，报告 3 到 5 个改进点。
Subagent C，安全审计：检查所有读 CSV、拼 SQL、渲染 HTML 的地方，
找出注入、XSS、路径穿越等风险，报告风险点和修复建议。
Subagent D，测试补全：检查 tests/ 目录，找出边界用例缺失、集成测试缺失、
覆盖率不足的地方，建议补充 5 到 10 个测试用例。
四个 subagent 只报告、不改代码。全部完成后汇总成一份优化报告，
按高、中、低优先级排序。这里有个关键设计：让所有 subagent 只报告不改代码。四个 subagent 同时改代码必然冲突，改代码这一步由主 Agent 串行执行。
主 Agent 汇总出的报告大致长这样：
# 优化报告
## 高优先级（建议立即修复）
1. [安全 C] CSV 路径未校验，可能路径穿越
风险：用户传 ../../../etc/passwd 能读到敏感文件
修复：用 os.path.realpath 校验路径在 data/ 目录下
2. [安全 C] 客户名直接渲染到 HTML，可能 XSS
修复：用 html.escape 转义
3. [测试 D] clean_data 缺少"全为空"的边界测试
修复：补 test_empty_dataframe
## 中优先级
4. [性能 A] calc_kpis 每次全表扫描，可以加缓存
5. [体验 B] 加载数据时没有 loading 动画
## 低优先级
（略）拿到报告后，让主 Agent 按优先级串行修复：按高优先级顺序逐个修复，每修一个提交一次 commit，跑全量测试，确认通过再修下一个。
四、给 Subagent 配专业角色
Subagent 最强大的地方在于：每个 sub 都可以有专属角色（系统提示词）。角色配置放在项目的 .claude/agents/ 目录下，一个 markdown 文件对应一个角色。先看安全审计员：
# .claude/agents/security-auditor.md
## 角色
你是一名资深安全审计工程师，10 年经验。
专注 Web 应用安全：OWASP Top 10、注入、XSS、CSRF、权限绕过。
## 工作方式
- 永远从攻击者视角看代码
- 不要相信任何用户输入
- 检查每个边界：未授权访问、参数篡改、注入点
## 输出格式
- 严重程度分高、中、低三档
- 必须给出：漏洞位置、PoC（概念证明）、修复建议
- 不要写"升级到最新框架"这种空话，要具体到代码再配一个测试工程师：
# .claude/agents/test-engineer.md
## 角色
你是一名测试工程师，TDD 拥护者。
信条：没有测试的代码等于没写完的代码。
## 工作方式
- 永远先写失败的测试，再写实现
- 覆盖三类：正常路径、边界情况、错误路径
- 测试要快（单个小于 1 秒），彼此独立（不依赖执行顺序）
## 输出格式
- 测试用例必须可独立运行
- 每个测试聚焦一个断言
- 说明"为什么这个测试重要"每个角色都是一份专业经验的代码化，也是你的领域知识沉淀。写好之后，不同 Agent 客户端的语法各有差异，但思路一致：用 security-auditor 跑安全审计，用 test-engineer 补测试，并行执行，最后汇总。
五、一个真实场景：周报生成 5 倍提速
一位学员的痛点很有代表性：每周要做 5 个部门的周报。串行做法下，每份周报分析数据加写报告要 30 分钟，5 份就是 2.5 小时。
改用 subagent：5 个 subagent 并行，每个负责一个部门的周报，共用同一套周报模板加该部门的专属指标。每个 subagent 还是 30 分钟，但五个同时跑，总时长就是 30 分钟。2.5 小时缩到半小时，5 倍提速。并行的力量就体现在这里。
六、三种协调模式
多个 subagent 怎么协调？常用的是三种模式。
模式一，竞争式（Voting）：多个 subagent 各给方案，主 Agent 挑最好的。比如让 3 个 subagent 各写一版营销文案，选最优的那版。适合创意类、没有唯一正确答案的任务。
模式二，分工式（Partition）：每个 subagent 负责一块，互不重叠。比如 A 写登录模块，B 写支付模块，C 写通知模块，三个模块独立无依赖。适合模块边界清晰的项目。
模式三，流水线式（Pipeline）：subagent 串行接力。调研、设计、实现、测试，一环扣一环，每个环节专业化。适合有依赖关系的复杂任务。
实际项目经常三种混用：先用流水线做调研和设计，再用分工式并行实现各模块，最后用竞争式选出最佳方案。
七、五个常见的坑
- subagent 之间不共享上下文。A 不知道 B 做了什么。解法：让主 Agent 当信息中转站，A 的接口定义先交给主 Agent，再作为输入约束传给 B。
- 并行改同一个文件。几个 subagent 都动 main.py，必然冲突。解法：约定每个 subagent 只改自己的文件。
- subagent 数量爆炸。10 个并行，主 Agent 调度开销巨大。通常 3 到 5 个是甜蜜点。
- 单个 subagent 任务太大。一个 subagent 又想干整个项目，等于没分。解法：每个任务控制在 30 分钟以内。
- 并行 token 成本翻倍。5 个并行就是 5 倍 token 消耗。解法：算一算省下的时间值不值多花的钱，简单任务不值得。
八、进阶：自主编排
Anthropic 的报告里提到一个趋势：Agent 自己决定怎么编排。你可以只给一个大任务，让 Agent 先出编排计划：需不需要 subagent、需要几个、各负责什么、用什么模式、怎么集成验证，计划确认后再执行。
比如"把销售看板项目从 Python 迁移到 TypeScript"，Agent 可能给出的计划是：第一阶段用流水线，一个 subagent 分析现有 Python 代码结构，输出 TS 项目结构建议；第二阶段用分工式，三个 subagent 并行迁移数据加载、计算和渲染模块；第三阶段回到流水线，补 TypeScript 类型与测试，跑通端到端。
关键在于：Agent 自己规划，但你拍板，这是 Agentic 编排的精髓。也要提醒一句，自主编排有可能失控，新手先把上文的手动编排练熟，再尝试自主模式。
九、在 Claude Code 里落地
具体到 Claude Code，subagent 的用法分三步。第一步，定义角色：在项目 .claude/agents/ 目录下建 markdown 文件，比如 architect.md、code-reviewer.md、security-auditor.md、test-engineer.md。第二步，使用：对话里输入 /agents 可以查看可用的 subagent，也可以直接说"用 code-reviewer 审查 src/ 目录"。第三步，并行：同时启动多个 subagent，全部完成后汇总。
一套值得直接抄的标准团队配置：
| 角色文件 | 专长 | 何时用 |
|---|---|---|
| architect.md | 模块划分、依赖管理、技术选型 | 项目开始或大重构前 |
| code-reviewer.md | 找 bug、坏味道、改进建议 | commit 前、PR 审查 |
| security-auditor.md | OWASP Top 10、注入、XSS、权限 | 上线前、处理用户数据时 |
| test-engineer.md | 边界用例、集成测试、覆盖率 | 功能完成后、上线前 |
把这四个角色配上，项目就有了一支随叫随到的虚拟团队。
动手练习
- 在你已完成的销售看板项目上，跑一遍第三节的并行优化流程，得到一份优化报告。
- 配置第九节的四个标准角色，分别让它们工作一次，体会专业角色和通用角色的差别。
- 找一个你经常重复做的任务（写周报、整理素材、批量翻译），改造成 subagent 并行版。
- 给主 Agent 一个大任务，让它自己规划编排方案，你审阅后再执行。
- 思考题：要决定下一个产品用 React 还是 Vue，该用哪种协调模式？答案是竞争式，让多个 subagent 各自论证一个方案，你选最优。
要点回顾
- Subagent 是主 Agent 调度出的专业化子员工，解决上下文爆炸、串行慢、不专业、错误传染四个瓶颈。
- 适合独立可并行、专项深挖、大量重复、多视角评审的任务；强依赖串行、简单任务、需要共享上下文的任务别硬拆。
- 三种协调模式：竞争、分工、流水线，实际项目常混用。
- 配置角色就是把专业经验代码化。
- subagent 只报告不改代码，改代码由主 Agent 串行做，避免冲突。
- 自主编排是趋势，但先练熟手动编排。
延伸方向：MCP
Subagent 解决的是"人手"问题，工具连接是另一个方向：MCP 让 Agent 能读数据库、调 API、操作文件系统、控制浏览器。Agent 接上 MCP，才算真正长出了手和眼，本系列后续会单独展开。
参考：
- Claude Code Subagents 文档：https://docs.claude.com/en/docs/claude-code/sub-agents
- 并行编排模式参考：MapReduce / Pipeline / Fan-out-Fan-in
