importzhh

Claude Code 编排篇：子智能体、Fork 模式与协调器

Claude Code; Subagent; 多智能体; Agent 3211 字 17 min read

前面几篇讲的都是单个 Claude Code 会话怎么配置、怎么扩展。但真正的复杂任务——大规模重构、跨模块的 bug 修复、需要先探索再规划再执行的工程——往往超出单个上下文窗口能承载的范围。这时候就要靠委派：把子任务交给专门的子智能体（Subagent），让它们在各自独立的上下文里干活，只把结果带回来。

这篇拆解 Claude Code 的子智能体机制：三种来源、四种内置角色、两种并行策略（Fork 与协调器），最后落到一个实战中争议很大的问题——自定义 SubAgent 到底值不值得做。

一、为什么需要子智能体

想象一个交响乐团：指挥不需要亲自演奏每种乐器，而是把不同声部交给各自领域的专家。子智能体就是这个思路——主智能体是指挥，把专门的活派给专门的 Agent。

但委派的核心价值其实是上下文经济学。sshh.io 那篇《我如何使用 Claude Code 每一项功能》里有一个很清晰的算式：

一个复杂任务需要 X token 的输入上下文（例如”如何运行测试”），工作过程中累积 Y token，产出一个 Z token 的答案。运行 N 个这样的任务，意味着你的主窗口里会有 (X + Y + Z) × N 个 token。子智能体的解决方案是，把 (X + Y) × N 的工作外包给专门的 Agent，这些 Agent 只返回最终的 Z token 答案，从而保持主上下文清爽。

一句话：子智能体让你用一个干净的主上下文，撬动大量的探索和执行工作。探索、编译、跑测试这些会污染上下文的脏活，都在子进程里完成，主会话只看到结论。

二、三种智能体来源

Claude Code 的智能体按加载优先级从低到高有六层，但本质是三种来源：

graph TD
    A["内置智能体<br/>开箱即用，默认选项"]
    B["插件智能体<br/>可覆盖同名内置智能体"]
    C["用户设置 ~/.claude/settings.json"]
    D["项目设置 .claude/settings.json"]
    E["Flag 设置 CLI 启动参数"]
    F["策略设置<br/>企业管理配置，最高优先级"]

    A -->|被覆盖| B
    B -->|被覆盖| C
    C -->|被覆盖| D
    D -->|被覆盖| E
    E -->|被覆盖| F

    style F fill:#ff6b6b,stroke:#c0392b,color:#fff
    style A fill:#bdc3c7,stroke:#7f8c8d,color:#333
  • 内置智能体（built-in）：编译进二进制，优先级最低，作为默认
  • 插件智能体（plugin）：插件提供，可覆盖内置
  • 自定义智能体：用户/项目/Flag/策略设置，通过 Markdown 文件声明式定义

这个优先级链和配置篇讲的六层配置源是同一套思路。它带来一个企业级能力：策略级的自定义智能体可以覆盖同名内置智能体。比如金融科技公司可以在策略设置里定义一个 code-review 智能体，覆盖内置版本，强制加入 PCI-DSS 合规检查清单——无论开发者个人怎么配置，企业级审查标准始终生效。

一个自定义智能体的定义（.claude/agents/xxx.md）本质上就是一段自然语言 + 一些配置字段：它能用哪些工具、禁用哪些工具、用什么模型、什么场景下触发（whenToUse）、是否省略 CLAUDE.md 上下文等。

三、四种内置智能体：探索、规划、执行、验证

Claude Code 的内置智能体覆盖了软件工程最常见的四种工作模式。理解它们的分工，你才能理解”委派”该怎么委派。

graph LR
    subgraph 只读层
        E["Explore（搜索）"]
        P["Plan（规划）"]
    end
    subgraph 读写层
        G["General（执行）"]
        V["Verification（验证）"]
    end

    E --> P --> G --> V

    style E fill:#3498db,stroke:#2471a3,color:#fff
    style P fill:#2ecc71,stroke:#27ae60,color:#fff
    style G fill:#f39c12,stroke:#d68910,color:#fff
    style V fill:#e74c3c,stroke:#c0392b,color:#fff

Explore Agent（只读探索） 是一个高速只读搜索智能体。它的设计有两个精彩的决策：

  1. 双重锁的只读约束。系统提示层面声明”不能创建/修改文件”（软约束），工具层面通过 disallowedTools 物理禁止 Edit、Write（硬约束）。即使模型”幻觉”想改文件，也会因工具不可用被物理阻止。
  2. 省略 CLAUDE.md。搜索任务不需要 commit/PR/lint 规则，省略它不仅省 token，更重要的是减少系统提示噪声，让模型聚焦搜索本身。据估算，这一优化每周可节省 5–15 Gtoken。

Plan Agent（结构化规划） 复用 Explore 的只读工具集，但角色是架构师。它输出结构化实现计划，以”关键文件列表”结尾，为后续实现提供指引。它同样省略 CLAUDE.md，但原因微妙不同——Explore 是”不需要”，Plan 是”不应该”：规划阶段应该关注”做什么”，而不该被”本项目用 camelCase”这类实现细节干扰。

General Purpose Agent（通用执行） 拥有全部工具权限（'*'），是实际动手改代码的执行者。它的哲学是”默认信任，边界后移”——不做工具层预设限制，靠全局权限系统兜底。（反模式提醒：不要用 General 做只读任务，那是 Explore 的活，用 General 会浪费权限和 token。）

Verification Agent（验证） 是对抗性验证者，负责检查前面几步产出的正确性。

这四个角色连起来就是一条流水线：Explore 侦查 → Plan 制定计划 → General 动手 → Verification 复核。这也是上手篇里提到的”用 haiku 规划、sonnet 执行、opus 复核”省 token 策略的底层原理。

四、Fork 模式：字节级的上下文继承

派子智能体最朴素的做法是同步执行——主线程等着子 Agent 跑完。但 Claude Code 还有一种更精巧的策略：Fork 模式。

Fork 的核心是缓存共享。当主智能体 Fork 出多个子智能体时，这些子智能体共享父级上下文的字节级前缀。为什么这很重要？因为 Anthropic API 的 prompt caching 是基于前缀匹配的——只要请求的前缀和之前缓存的一致，这部分就走缓存价格（便宜 90%）而非全价。

Fork 模式精心构建了”缓存安全的消息前缀”，让所有 Fork 出来的子智能体复用同一段已缓存的上下文。这意味着你可以并行跑 N 个子智能体，却几乎不为重复的上下文付费。这就是”真正的并行执行而不浪费 token”。

Fork 的特点是无中心的对等并行：所有子智能体平等，共享相同的上下文起点，各自独立探索。

五、协调器模式：有中心的企业级编排

当任务复杂到需要有人”统筹全局”时，Fork 的对等模式就不够了。Claude Code 提供了 Coordinator（协调器）模式——中心化的”协调者-工作者”架构。

类比建筑工地：项目经理（Coordinator）不砌砖、不布线，但他知道哪个工人擅长什么、哪些任务能并行、哪些有依赖、怎么协调共享资源。工人（Worker）只看到分配给自己的任务。

双重门控

协调器模式通过两道门控开启：

flowchart TD
    subgraph 编译时["编译时：Feature Gate"]
        CG["是否包含 Coordinator 功能？"]
        CG -->|否| CN["代码不编译进二进制"]
        CG -->|是| RT
    end
    subgraph 运行时["运行时：环境变量"]
        RT["CLAUDE_CODE_COORDINATOR_MODE 是否设置？"]
        RT -->|否| NN["普通模式（可能激活 Fork）"]
        RT -->|是| YY["Coordinator 模式激活"]
    end

    style YY fill:#2ecc71,stroke:#27ae60,color:#fff
    style NN fill:#bdc3c7,stroke:#7f8c8d,color:#333

“编译时排除 + 运行时显式启用”是企业软件的常见模式：不需要该功能的轻量部署可以完全排除代码、减小攻击面；即使编译进来了，也要显式开启才生效，符合最小权限原则。

当协调器和 Fork 同时满足条件时，协调器优先——它已经有自己的任务委派模型，不需要 Fork 的隐式并行。

权力边界：协调者只编排，不执行

协调器模式最关键的设计是权力分离：

graph LR
    subgraph Coordinator["协调者 — 管理权"]
        C1["Agent Tool 创建/分配任务"]
        C2["TaskStop 停止工作者"]
        C3["SendMessage 发消息"]
        C4["Structured Output"]
    end
    subgraph Worker["工作者 — 执行权"]
        W1["Read / Write"]
        W2["Edit / Bash"]
        W3["Grep / Glob"]
        W4["Skill / MCP"]
    end

    Coordinator -.管理 vs 执行.- Worker

    style C1 fill:#e74c3c,stroke:#c0392b,color:#fff
    style W1 fill:#3498db,stroke:#2471a3,color:#fff

协调者没有 Read/Write/Edit/Bash 这些执行工具——它不能直接碰代码，必须通过工作者间接完成所有实际工作。它的系统提示还明确禁止几件事：不能”用一个工作者去检查另一个工作者”、不能”用工作者简单报告文件内容”、不能”预测或编造智能体结果”。

为什么禁止”工作者检查工作者”？因为那会形成信息链式传递（B 完成 → A 读 B 的结果 → A 报告给协调者），带来两个问题:信息衰减（像传话游戏，每传一次丢一些细节）和调试困难（出错时要逐层追溯）。正确模式是协调者直接接收每个工作者的结果，自行理解后编写下一步指令。

Fork vs 协调器：怎么选

维度Fork 模式协调器模式
架构无中心，对等并行有中心，协调者-工作者
上下文共享父级字节级前缀工作者只看到自己的任务
适用同类任务的并行铺开有依赖、需统筹的复杂工程
成本极省 token（缓存复用）协调开销换取可控性

六、实战争议：自定义 SubAgent 该不该用

前面讲的都是机制。但在真实工作流里，要不要为特定任务定制 SubAgent 是个有争议的问题。sshh.io 那篇文章给出了一个反直觉但很有说服力的观点：自定义 SubAgent 常常是个脆弱的解决方案。

他的理由有两条：

  1. 它们把上下文”关起来”了。如果你创建了一个 PythonTests SubAgent，就等于把所有测试相关的上下文从主 Agent 那里隐藏了。主 Agent 再也无法对一个变更做整体思考——它被迫调用 SubAgent 才能知道怎么验证自己的代码。

  2. 它们强迫 Agent 遵循人类的工作流。定制 SubAgent 相当于你在指令它必须如何委派任务，而”如何委派”恰恰是你最希望 Agent 自己解决的问题。

他推荐的替代方案是：把所有关键上下文放进 CLAUDE.md，然后让主 Agent 自己用内置的 Task(...)/Explore(...) 功能，动态决定何时、如何把工作委派给自己的通用副本。他把这叫做”主-克隆”模式，认为它优于自定义 SubAgent 倡导的”主导-专家”模式——既享受了子智能体省上下文的好处，又避免了僵硬工作流的缺点。

这个观点值得辩证看待。对于个人项目和探索性工作，“主-克隆”确实更灵活。但对于企业级、需要强制规范的场景（比如前面说的强制安全审查），定制智能体的”僵硬”恰恰是优点——它保证了无论谁来用，标准都一致。这跟上手篇讲的斜杠命令哲学是同一个道理：能用自然语言 + 好的 CLAUDE.md 解决的，就别急着造一堆专用抽象。

小结

  • 子智能体的核心价值是上下文经济学：脏活外包给子进程，主会话只留结论。
  • 四种内置角色（Explore/Plan/General/Verification）构成”侦查→规划→执行→复核”流水线。
  • Fork 模式是无中心的对等并行，靠字节级缓存前缀实现”并行不加钱”。
  • 协调器模式是有中心的企业级编排，靠”协调者只编排不执行”的权力分离保证可控。
  • 实战中，优先用好 CLAUDE.md + 主 Agent 的动态委派，把定制 SubAgent 留给真正需要强制规范的场景。

下一篇进入工作流篇，讲 Plan 模式和”先想后做”的结构化工作流。

本篇主要参考：

  • 《御舆：解码 Agent Harness》第 9 章”子智能体与 Fork 模式”、第 10 章”协调器模式”（lintsinghua/claude-code-book，CC BY-NC-SA 4.0）
  • 《How I Use Every Claude Code Feature》（sshh.io，L 站译文）—— 关于自定义 SubAgent 的”主-克隆”模式观点
  • 《AI 编程新阶段 Claude Code 上手指南》（linux.do/t/topic/1798141）—— 子代理使用场景