课程大纲
课程大纲系列主页
学习进度已完成 0/7
03子代理：用隔离换干净，用 depth=1 换可控

子代理：用隔离换干净，用 depth=1 换可控

进阶进行中

子代理：用隔离换干净，用 depth=1 换可控

本文基于 Florian BRUNIAUX 的英文原版改编，原文地址：https://cc.bruniaux.com/guide/architecture 许可：CC BY-SA 4.0

这篇你能拿走什么

很多人对 Task 工具有两个误解：一是"它就是异步执行"，二是"既然能 spawn agent，那肯定可以无限嵌套"。两个都错。Task 真正的价值是上下文隔离——让一个不会污染主会话的子进程去做"读完几十个文件才能回答"的脏活，最后只把总结带回来。这一篇带你把它的边界搞清楚。

前置条件

  • 已完成本系列前面的章节
  • 至少用过一次 /explore 或 Task 工具

隔离模型：子代理拿到的不是你的上下文

可信度：100%（Tier 1 - 已文档化行为）

text
┌─────────────────────────────────────────────────────────────┐
│ MAIN AGENT                                                  │
│ Context: Full conversation + all file reads                 │
│                                                             │
│ Task("Explore authentication patterns")                     │
│   │                                                         │
│   ▼                                                         │
│ ┌─────────────────────────────────────────────────┐         │
│ │ SUB-AGENT (Spawned)                             │         │
│ │ • Own fresh context window                      │         │
│ │ • Receives: task description only               │         │
│ │ • Has access to: same tools (except Task)       │         │
│ │ • CANNOT spawn sub-sub-agents (depth = 1)       │         │
│ │ • Returns: summary text only                    │         │
│ └─────────────────────────────────────────────────┘         │
│   │                                                         │
│   ▼                                                         │
│ Result: "Found 3 auth patterns: JWT in..."                  │
│ (Only this text enters main context)                        │
└─────────────────────────────────────────────────────────────┘

要点：

  • 子代理拿到的只有任务描述，不是你的整个会话历史
  • 子代理可以用除 Task 之外的所有工具
  • 子代理读了多少文件、跑了多少命令，主上下文一概不知
  • 主代理收到的只有一段总结文本

这就是隔离的威力——你可以让子代理读 30 个文件，主上下文只多了 500 token 的总结。

为什么 depth = 1

子代理不能再生子代理。这个限制不是技术不到位，是有意设计：

  1. 递归爆炸 — agent-ception 会消耗无限资源
  2. 上下文污染 — 每多一层都会累积上下文
  3. 调试噩梦 — 多层 agent 链条几乎没法跟踪
  4. 不可预测成本 — 嵌套代理 = 不可预测的 token 使用量

如果你觉得"我需要嵌套"，几乎一定是任务还没拆够细。把它拆成主代理统一调度的多个并行 Task，比让一个子代理自己再 spawn 子代理要可控得多。

4 种子代理类型

Claude Code 通过 subagent_type 参数提供专门的子代理：

类型用途可用工具
Explore代码库探索所有只读工具
Plan架构规划除 Edit / Write 之外的所有工具
Bash命令执行仅 Bash
general-purpose复杂多步任务所有工具

选择规则：

  • 不确定 → general-purpose
  • 只是要找/读/搞清楚某事 → Explore
  • 要设计实现方案、不能改文件 → Plan
  • 要跑一系列脚本 → Bash

Explore 和 Plan 的关键好处是带类型保护：Explore 不会意外 Edit、Plan 不会意外 Write。如果你担心一段探索"手滑改了东西"，用这两种类型比 general-purpose 更安全。

什么时候用子代理

使用场景为什么子代理有帮助
搜索大型代码库保持主上下文干净
并行探索同时开几路搜索
有风险的探索错误不会污染主上下文
专门分析为不同任务用不同"心态"

判断口诀：如果探索过程会产生大量中间数据，但你只关心结论，就用子代理。

反过来，如果你需要 Claude 在主会话里保留这次探索的全部细节（比如"读完这些文件后我们要逐个改"），就别用子代理——总结一进主上下文，原始内容就丢了。

实战注解

我自己最常用的 Task 模式是"质疑探索"。比如要做一个看起来要改 10 个文件的需求，我先 spawn 一个 Explore 子代理：「找一下是否已经有现成的 utility 能复用，列出函数名 + 文件位置 + 一行说明」。等 30 秒拿回 200 字总结，再决定是真改 10 个文件，还是改 2 个文件。

并行版本更猛：同一条消息里同时 spawn 3 个 Task，一个查"现有实现"、一个查"测试覆盖"、一个查"已知 bug"。3 分钟后拿到 3 段总结，主上下文只多了 1500 tokens，但你已经有了一张完整的局势图。这是 depth=1 的合理用法——主代理负责调度，子代理负责挖掘。

可信度回顾

  • Tier 1（官方 100%）：隔离模型、depth=1 限制、4 种子代理类型、可用工具
  • Tier 2（70-90%）：本篇没有 Tier 2 内容
  • Tier 3（推断）：本篇没有 Tier 3 内容

子代理这一节是文档化最完整的部分之一，可以放心当行为契约用。

常见问题

Q：子代理失败会不会让主代理也失败？ A：不会。子代理的失败只表现为返回错误总结，主代理可以决定重试、换策略，或者完全放弃这条线。

Q：能给子代理传文件吗？ A：不能直接传文件。但你在 Task 描述里可以给路径或关键 grep 关键字，让子代理自己读取。子代理有完整的 Read / Grep 权限。

Q：子代理用什么模型？ A：默认跟主代理同模型，但有些版本支持 /model 在子代理里切换到便宜模型。详见会话持久化篇。

来源与许可

  • 原作者：Florian BRUNIAUX；Claude（Anthropic）参与贡献
  • 英文原版地址：https://cc.bruniaux.com/guide/architecture
  • 源文件：FlorianBruniaux/claude-code-ultimate-guide / guide/core/architecture.md
  • 本文基于 CC BY-SA 4.0 改编：保留署名、来源链接，衍生作品同样以 CC BY-SA 4.0 公开
  • 内容版本：原作 v1.1.0 / Claude Code v2.1.34（2026-02）
子代理：用隔离换干净，用 depth=1 换可控 | 资讯狗 | Zixungou