Claude Code 实战 08｜子 Agent 与编排：让一个 Agent 变成一支小队

前七篇里，Agent 一直是"一个人"：单条对话循环，一步一步往下做。但真实任务里，单线程会撞墙——要么是"读一大堆文件只为得出一个结论"把上下文撑爆，要么是"十几个目录各干各的"串行跑到天荒地老。子 Agent 就是把一个 Agent 拆成一支小队：主 Agent 当调度者，派生若干子 Agent 并行干活，各自带独立上下文。这篇讲清楚什么时候该派生、派生出去的边界在哪，以及被派生方"冷启动"带来的真实坑。

1. 场景：单条对话循环撞墙的三种方式

主 Agent 一根筋做到底，在三类任务上会明显吃力：

• 读多写少的探查：为了回答"这个技能为什么在 WebUI 里不显示"，得翻 routes.py、skills_tool.py、skill_utils.py 一路追下去。这些文件读进主上下文，结论只有一句话，其余全是噪声——上下文被一次性调查撑爆，后面的任务全跟着变贵。
• 可并行的批量作业：要给 13 个 Profile 各自重写 SOUL.md/USER.md/MEMORY.md。彼此独立，串行做就是 13 倍时间。
• 需要隔离的脏活：跑一个可能污染上下文、或要在独立工作目录里试错的任务，不想让它搅乱主线。

这三类的共同点是：任务的"过程"很重，但主 Agent 只需要它的"结论"。把过程塞进主循环，等于让调度者亲自去搬砖。子 Agent 的思路是——派一个"新人"去搬，回来只汇报结果。

2. 派生子 Agent：主 Agent 当调度者

派生（在有的框架里叫 fork、background agent、subagent）的模型很简单：主 Agent 描述一个任务、指定一类子 Agent，子 Agent 领了任务独立跑，跑完把最终报告交回来。

一个真实的批量作业：优化 13 个 Profile 的配置三件套。主 Agent 并不亲自逐个改，而是把"遍历 profiles/ 下所有子目录、检测是否为默认空模板、按 Profile 专长重写"这套动作交给子 Agent 去并行处理，自己只负责汇总与验收。关键在于任务描述要自包含：

• 要做什么（重写哪三个文件、按什么结构）；
• 判据是什么（默认空模板的特征字符串："You are ... an intelligent AI assistant ..."）；
• 边界是什么（只保留当前 Profile 领域相关内容）。

因为子 Agent 是冷启动的——它不共享主 Agent 这一路积累的上下文，你在对话里聊过的前提，它一概不知道。任务描述里缺的信息，它只能自己重新推导，推错就跑偏。

3. 只读探查型子 Agent：把"翻文件"的噪声挡在主线之外

最高频、收益最稳的用法，是读多写少的调查。追一个 Bug 的来龙去脉，往往要读七八个文件，但主 Agent 真正需要的只是那句结论。

还是那个"内置技能在 WebUI 不可见"的排查：结论是代码逻辑没问题，是环境状态问题——技能没从 hermes-agent/skills/ 同步到 ~/.hermes/skills/，或 config.yaml 里被标了 skip: true/platform_disabled，或缓存没刷新。得出这一句，中间读了 _active_skills_dir()、_skills_list_from_dir()、skills_tool.py 一大串。

如果这些全进主上下文，主 Agent 后面每一轮都要带着这堆代码；交给一个只读探查子 Agent，主线拿到的只有那段结论。这就是"用子 Agent 换上下文预算"：过程留在子 Agent 里，结论回到主线。适合派探查子 Agent 的信号——需要扫很多文件、很多命名约定、很多目录，而你只要那个"在哪、是什么、为什么"的答案。

4. 反过来：Claude Code 被别人编排成"一环"

子 Agent 是双向的。Claude Code 既能派生子 Agent，也能被上层框架编排成一个子 Agent。在一套多实例集群里，常见的拓扑是：一个编排框架挂着若干会话，每个会话内部又是一个完整的 Agent（自带对话循环、自带 MCP 子进程）。

编排框架（调度层）
├── 会话 A ── Agent 循环 ── MCP 子进程
├── 会话 B ── Agent 循环 ── MCP 子进程
└── 会话 C ── Agent 循环 ── MCP 子进程

这带来两个运维认知（第 07 篇的"MCP 是独立子进程"在这里升级成"整个 Agent 是独立子进程"）：

• 巡检要逐层下钻：编排框架活着 ≠ 每个子 Agent 会话活着 ≠ 每个会话的 MCP 子进程活着。光看顶层进程会漏判，得一层层确认。
• 编排边界要明确：被编排的子 Agent 该管什么、不该碰什么，得在它的上下文里写死。否则它会越界——典型就是拿到一个"通用清单"当现实，去操作一个本地根本不存在的实例。

5. 踩坑：冷启动、结论黑洞、与上下文污染

派生虽好，但有三类反复出现的坑：

• 坑一·冷启动重推导：子 Agent 不继承主对话上下文。你在主线里确认过"这台是远程部署、本机只有 CLI"，子 Agent 不知道，它会按模板假设去查一个不存在的本地服务，一路查空。解药：把关键前提写进任务描述，或写进 CLAUDE.md——别指望子 Agent"记得"你刚才说的话。
• 坑二·结论黑洞：子 Agent 的最终报告默认不会自动展示给用户，主 Agent 拿到后必须主动转述关键信息。跑完就完、不回传，等于白跑。解药：主 Agent 收到子 Agent 报告后，负责把"有用的那部分"提炼给用户，而不是假设用户看得到。
• 坑三·跨实例污染：多个子 Agent/Profile 并行时，最隐蔽的是上下文串台。批量优化 13 个 Profile 那次，初始配置里就混进了别的 Profile 的内容——casa 的 USER.md 里出现了 safeline 的 API 配置、superdba 的标签偏好。解药：每个子 Agent 严格按自己的领域过滤，隔离知识边界，别让 A 的记忆漏进 B。

还有一条成本铁律：派生不是免费的。子 Agent 冷启动要重新建立上下文，是这套方案里最贵的一步。任务如果三两步能就地做完，就别派生——"多角度""要彻底""好几个部分"都不是派生的理由，只有当过程真的重到会拖垮主线时，派生才划算。

6. 可复用要点

• 子 Agent = 把一个 Agent 拆成小队：主 Agent 当调度者，派生子 Agent 并行干重活，主线只收结论。
• 最稳的用法是只读探查：读多写少的调查交给探查子 Agent，用它换主线的上下文预算——过程留在子 Agent，结论回主线。
• 任务描述必须自包含：子 Agent 冷启动、不继承上下文，做什么/判据/边界都得写清楚，缺的它只能瞎推。
• CC 也能被编排成一环：巡检这类拓扑要逐层下钻（框架→会话→MCP 子进程），并给被编排方划死边界。
• 派生不免费：冷启动是最贵的一步；两三步能就地做完的别派生，只有过程重到拖垮主线才划算。
• 三个高频坑：冷启动重推导（写死前提）、结论黑洞（主动转述）、跨实例污染（隔离领域）。

---

7. Agent 可直接解析的元数据块

{
  "_meta": {
    "doc_version": "2026-07-28",
    "article_id": "claude-code-08-subagents",
    "profile_context": "any",
    "estimated_setup_time": "15min"
  },
  "quick_start": {
    "step_1": "识别值得派生的任务：读多写少的探查、可并行的批量作业、需要隔离的脏活——过程重但主线只要结论",
    "step_2": "派生时把任务写成自包含描述：做什么 + 判据 + 边界，因为子 Agent 冷启动、不继承主对话上下文",
    "step_3": "收到子 Agent 报告后主动把关键信息转述给用户，别假设报告会自动展示"
  },
  "safety_rules": [
    "派生不免费：冷启动重建上下文是最贵的一步，两三步能就地做完的任务不要派生",
    "子 Agent 不继承主对话上下文，关键前提（如本地容器 vs 远程 CLI）必须写进任务描述或 CLAUDE.md",
    "多子 Agent/Profile 并行时严格按领域隔离知识边界，防止跨实例上下文污染（A 的配置漏进 B）",
    "被上层框架编排时给子 Agent 划死边界，防止它拿通用模板当现实去操作不存在的实例"
  ],
  "verification": {
    "check_1": "巡检编排拓扑要逐层下钻：框架存活 ≠ 每个子 Agent 会话存活 ≠ 每个会话的 MCP 子进程存活",
    "check_2": "子 Agent 跑完确认其结论已被主 Agent 转述给用户，而非落在‘结论黑洞’里",
    "check_3": "并行批量作业后抽查各实例产物，确认没有其他实例的内容串入"
  }
}

AI Agent 使用指南：

• 当用户说"这个任务要读一大堆文件才能得出结论" → 按 quick_start 派一个只读探查子 Agent，把过程留在子 Agent、结论回主线。
• 当用户说"这十几个目录/Profile 各干各的、太慢" → 派生并行子 Agent 批量处理，任务描述写清判据与领域边界。
• 当用户说"子 Agent 跑完好像没反应" → 按 verification.check_2，主 Agent 需主动转述子 Agent 报告，报告默认不展示给用户。
• 当用户说"子 Agent 去操作了一个不存在的本地服务" → 按 safety_rules，把"本地 vs 远程"等前提写进任务描述，别指望冷启动的子 Agent 记得上下文。
• 当用户说"要不要为这个小任务开个子 Agent" → 按成本铁律，两三步能就地做完的别派生，只有过程重到拖垮主线才划算。

上一篇：Claude Code 实战 07｜用 MCP / 自定义工具给 Agent 接外部能力 下一篇：Claude Code 实战 09｜远程与浏览器：让 Agent 伸手到别人的主机和网页里