SubAgents（子代理）是 Claude Code 中一项强大的并行处理能力。子代理本质上是一个独立运行的 AI 会话，拥有自己完整的上下文窗口，可以在后台执行与主会话隔离的并行任务。这种设计打破了传统单线程对话的局限性——当主 Claude 正在处理一个复杂任务时，子代理可以同时处理其他完全独立的任务，从而大幅提升整体工作效率。
每个子代理都拥有独立的工具集，这意味着它们可以自主地读写文件、执行 shell 命令、搜索代码模式以及执行各种其他操作，而不会干扰主会话的工作状态。子代理与主会话之间是完全隔离的，彼此互不干扰，各自维护独立的对话历史和上下文状态。
子代理的核心价值在于并行化。在传统对话模式下，开发者必须等待每个任务依次完成。有了子代理，多个独立的任务可以同时推进，例如一个子代理在分析代码库结构，另一个子代理同时在编写文档，主会话则负责协调和决策。这种模式极大地提高了开发效率。
从架构角度看，子代理系统遵循主从模式：主会话作为协调者负责任务分发和结果整合，子代理作为执行者专注于具体任务。主会话可以创建多个子代理、监控它们的运行状态、接收它们的输出结果，甚至让它们之间互相通信。
子代理与普通的多轮对话有本质区别。在多轮对话中，所有操作都在同一个上下文中串行执行，每一步都必须等待上一步完成。而子代理是独立的会话进程，它们可以同时运行，互不阻塞，且每个子代理都有独立于主会话的上下文窗口，不会因为主会话的上下文增长而受到影响。
Claude Code 提供了四种不同类型的子代理，每种类型针对特定的使用场景进行了优化。选择合适的子代理类型是高效利用子代理系统的关键一步。不同类型的子代理拥有不同的权限级别、工具访问范围和预设行为模式。
通用代理是功能最完整的子代理类型，拥有所有工具的访问权限。它可以读写文件、执行命令、搜索代码、运行测试等，几乎可以完成任何主会话能够完成的任务。这是最常用的子代理类型，适用于代码编写、重构、测试、文档生成等大多数开发任务。
探索代理是一种只读模式的子代理，专门用于代码搜索和项目探索。它的工具集被限制为只读操作——可以搜索文件内容、浏览目录结构、读取文件，但不能创建、修改或删除任何文件。这种限制使其非常适合在不承担任何修改风险的情况下进行代码库分析、技术调研和依赖审查。
规划代理专注于架构规划和技术方案设计。它不能编写代码或修改文件，而是被设计用来进行高层设计、技术方案论证和架构决策。规划代理非常适合在开始大规模开发之前生成技术设计文档、评估不同实现方案的优劣、制定项目实施路线图。
指南代理是一个专门的知识型代理，用于回答关于 Claude Code 本身的使用问题。它包含了 Claude Code 的配置、命令、工作流程和最佳实践等知识。当你需要了解某个 Claude Code 功能如何使用、某个命令的详细参数或排查配置问题时，指南代理是理想的咨询对象。
| 类型 | 可用工具 | 适用场景 | 限制 |
|---|---|---|---|
| general-purpose | 所有工具（读写文件、执行命令、搜索等） | 代码编写、重构、测试、文档生成 | 无特殊限制 |
| Explore | 只读工具（搜索、读取文件、浏览目录） | 代码审查、技术调研、依赖分析、架构梳理 | 禁止写文件、禁止执行修改性命令 |
| Plan | 只读工具 + 分析工具 | 技术方案设计、架构规划、可行性分析 | 禁止编写和修改代码 |
| claude-code-guide | 知识检索、问题解答 | Claude Code 使用咨询、配置帮助 | 专注 Claude Code 相关知识领域 |
在大多数日常开发场景中，优先使用 general-purpose 类型即可。仅在需要纯分析或规划时切换到 Explore 或 Plan 类型以降低风险。指南代理则是一个随时可用的"内置帮助文档"，非常适合快速查询 Claude Code 的使用方法。
在 Claude Code 中创建子代理主要依赖 Agent 工具。这个工具提供了一套完整的参数体系，用于控制子代理的行为、特性和运行方式。正确理解每个参数的作用是有效使用子代理的前提。
创建子代理时需要指定三个核心参数：description（描述）用于概括子代理的任务目标，这有助于在主会话中识别和追踪不同的子代理；name（名称）为子代理分配一个唯一标识符，后续可以通过名称来寻址和通信；prompt（指令）是子代理接收的具体任务说明，类似于给子代理的系统提示词。
子代理可以以前台或后台两种方式启动。前台启动会等待子代理完成任务并返回结果，适合短小且需要即时结果的任务。后台启动则通过设置 run_in_background: true 让子代理在后台独立运行，主会话可以立即继续其他工作。
对于需要高安全隔离的场景，可以启用 worktree 隔离模式。设置 isolation: "worktree" 后，子代理将在独立的 git worktree 中运行，其所有文件修改都与主工作区完全隔离。这意味着即使子代理的操作出现问题，也不会影响主分支的代码状态。
子代理支持指定所使用的 Claude 模型。通过 model 参数可以选择不同的模型版本，例如 sonnet 或 opus。这使得在需要高速处理时选择更快的模型，在需要深度推理时选择更强的模型，灵活调配计算资源。
对于简单任务（如文件搜索、格式检查），使用默认的 sonnet 模型即可，速度快且 token 消耗低。仅对需要深度推理的复杂任务（如架构设计、复杂算法实现）指定 opus 模型。
当子代理在后台运行时，主会话需要一套完整的管理机制来监控和控制这些并行任务。Claude Code 为此提供了专门的任务管理工具和命令，让开发者能够像操作系统进程一样管理子代理的生命周期。
/tasks 命令可以列出当前所有运行中的后台子代理及其状态。这个命令提供每个子代理的名称、描述、运行时间和当前状态等关键信息，帮助开发者一目了然地掌握整个并行任务队列的情况。
TaskOutput 工具用于获取已完成或运行中的子代理的输出结果。通过设置 block: true 参数，可以让主会话阻塞等待直到子代理完成并返回结果。这在需要子代理处理结果才能继续下一步的场景中非常有用。
TaskStop 工具用于强制终止正在运行的后台子代理。当发现子代理执行方向错误、耗时过长或者不再需要其结果时，可以立即终止它以释放计算资源。
后台子代理有默认的最长运行时间限制为10分钟。超过这个时间限制，子代理将被自动终止以防止资源泄漏。当子代理完成任务或被终止时，系统会自动通知主会话，开发者无需手动轮询状态。这种异步通知机制使得后台任务管理更加高效和可靠。
子代理系统的一个强大特性是代理间的通信能力。子代理之间以及子代理与主会话之间可以通过 SendMessage 工具进行消息传递，实现协作式任务处理。这种通信机制使得多个子代理可以协同完成复杂的工作流，而不是各自为战。
SendMessage 工具允许向指定的子代理发送文本消息。通过 to 参数指定目标子代理的名称，message 参数传递消息内容。接收消息的子代理会在其上下文中看到这条消息，并可以基于消息内容继续工作或调整方向。
子代理生成的消息会自动投递给主会话，主会话无需主动轮询即可收到子代理的进度更新、请求和结果。这种机制确保了主会话始终掌握所有子代理的最新状态，就像一个项目经理随时接收团队成员的进展报告。
子代理间的通信支持结构化的协议响应。最常见的协议包括 shutdown_request（子代理请求关闭）和 plan_approval_request（请求批准执行计划）。这些协议为子代理提供了与主会话进行结构化交互的能力，使得协作更加规范和高效。
子代理通过创建时指定的 name 参数进行定位。这个名称在整个子代理系统中必须是唯一的，主会话和其他子代理都通过这个名称来寻址。良好的命名习惯（如使用功能前缀、清晰描述用途）可以大幅提升多代理协作场景下的可管理性。
在多代理协作场景中，建议使用统一的命名规范，例如 "task-功能名" 或 "module-模块名-操作"。这样在管理多个并发子代理时可以快速识别每个代理的职责，避免混淆。
充分发挥子代理系统效用的关键在于合理的任务编排策略。不同依赖关系的任务需要不同的并行执行模式。本节详细阐述四种核心并行策略，帮助开发者在实际项目中灵活运用子代理。
当多个任务之间没有任何依赖关系时，可以同时启动所有任务。这是最直接的并行策略，能够最大化利用并行资源。例如，同时重构三个互不依赖的模块、同时为多个 API 端点编写文档、同时分析多个代码库的子目录。这种策略的核心思想是不等待——所有子代理同时开始工作，主会话在最后统一收集结果。
当任务之间存在明确的先后依赖关系时，需要采用流水线式的执行策略。后一个子代理必须等待前一个完成并取用其结果后才能开始。典型的场景是：先分析代码结构（Explore 代理），再生成技术方案（Plan 代理），最后实施编码（general-purpose 代理）。这种串行但分阶段的方式依然比单线程处理更高效，因为每个阶段可以切换到最优的代理类型。
当多个子代理从不同角度并行处理后，需要将它们的输出结果进行汇总和整合。结果汇聚策略要求主会话在后台等待所有相关的子代理完成（使用 block: true），然后将各个子代理的输出融合为统一的成果。例如，多个子代理分别审查代码库的不同部分，主会话将审查结果合并为一份完整的代码质量报告。
对于更复杂的场景，可以使用 Team 和 TaskList 机制来协调多个子代理。Team 模式允许多个子代理围绕一个共同目标协同工作，它们的任务被组织在一个 TaskList 中，系统会自动管理任务依赖和执行顺序。这种模式适合大规模重构、多模块功能开发等复杂场景，相当于拥有一个自动化的 AI 开发团队。
任务编排的核心原则是"最大化并行，最小化等待"。将大任务拆分为尽可能多的小的独立任务，让它们并行执行。对于不可避免的串行依赖，尽量缩短关键路径上的任务数量，让非关键路径的任务填满等待时间。
Worktree 隔离模式是子代理系统的一项高级安全特性。当启用此模式时，子代理会在一个独立的 git worktree 中工作，其所有文件操作都与主工作区完全物理隔离。这种设计为高风险操作提供了安全沙箱。
当设置 isolation: "worktree" 后，Claude Code 会自动创建一个基于当前分支的 git worktree。子代理的所有写入操作都在这个 worktree 中进行，不会触及主工作区的任何文件。主工作区完全不受子代理操作的影响，即使子代理删除了整个目录，主工作区也毫发无损。
Worktree 隔离模式内置了智能清理机制。当子代理完成任务后，系统会自动评估其修改：如果 worktree 中没有产生任何文件变更，该 worktree 会被自动删除以节省磁盘空间；如果产生了有意义的变更，系统会返回 worktree 的路径和变更摘要，让开发者审查后决定是否合并到主分支。这种"先隔离、再审查、后合并"的流程确保了代码质量。
Worktree 隔离模式特别适合以下场景：执行有风险的大规模批量操作（如全局重命名、批量替换）；尝试不确定效果的重构方案；运行可能产生大量临时文件的实验性脚本；需要团队审查的敏感修改。在这些场景下，隔离模式提供了"安全网"，让开发者可以大胆尝试而不必担心影响现有工作。
在进行大规模变更之前，优先使用 Explore 代理做一次全面的"风险评估"——让探索代理先分析所有将要被影响的文件，评估变更范围和潜在风险。确认安全后再使用 worktree 隔离的 general-purpose 代理执行实际的修改操作。
虽然子代理系统功能强大，但在实际使用中需要注意一系列重要事项，才能充分发挥其优势而避免潜在问题。
每个子代理都拥有自己独立的上下文窗口，这意味着每个子代理都会独立消耗 token。启动过多的子代理会导致总体 token 消耗快速增加。在启动子代理之前，应当评估任务的复杂度和耗时，合理控制并发数量，避免不必要的资源浪费。
任务的拆分粒度直接影响子代理系统的效率。拆分过细会导致管理开销超过并行收益——每个子代理的创建、通信和结果收集都有固定成本。拆分过粗则无法充分利用并行能力。一个好的经验法则是：每个子代理的任务应该在 1-5 分钟内可以完成，并且应该有明确的、可验证的输出。
子代理的输出结果需要经过审查和验证。虽然 Claude Code 的子代理准确度很高，但作为异步执行的独立进程，其输出可能受到上下文限制、指令理解偏差等因素的影响。特别是在代码生成和文件修改的场景中，务必审查子代理的变更内容后再合并到主分支。
应避免同时启动过多的子代理。虽然系统对并发数量有一定的弹性，但过多的并发任务会导致系统资源（内存、CPU、磁盘 I/O）的竞争，反而降低整体效率。建议根据任务的复杂度将并发数量控制在 3-5 个以内，在简单任务场景下可以适当增加。
子代理继承主会话的权限设置。这意味着如果主会话有执行高危操作（如文件删除、git 强制推送）的权限，子代理也同样拥有这些权限。在需要限制子代理权限时，应当使用 Explore 或 Plan 等受限类型的代理，或者在 prompt 中明确限制子代理的行为范围。
子代理在运行过程中可能遇到各种错误：指令不清晰导致执行偏差、文件访问权限不足、超时被终止等。对于关键任务，应当设计重试或降级策略——当子代理失败时，可以重新启动并给予更明确的指令，或者将任务降级由主会话直接处理。