Claude Code 子智能体：上下文隔离、编排者与审查者，以及何时不需要它们

什么是 Claude Code 子智能体

子智能体是主智能体为某个单独任务启动的另一个智能体实例。它有自己的上下文窗口、自己的系统提示和自己允许使用的工具列表。主智能体把任务描述交给它，子智能体独立工作——读取文件、运行命令——然后只把最终消息返回来。

关键词是隔离。子智能体途中读过的一切——几十个文件、冗长的测试输出、走不通的假设——都留在它自己的上下文中，不会进入主会话的上下文。主智能体看到的是一段简短的结果：“函数 X 中有错误，原因如下，受影响的有这三处”。

Claude Code 的子智能体是多智能体系统这一更宽泛思想的一个具体形式：不再是一个“思考、行动、检查”的单一循环，而是由若干节点组成的图，每个节点都有自己的角色和职责。

为什么需要上下文隔离

上下文窗口是智能体最主要的资源。CLAUDE.md 中的指令、对话历史、读过的代码以及命令输出都同时占据其中。当智能体花半小时寻找一个 bug 的原因时，上下文会被无关的文件和大量日志塞满，而其中真正有用的可能只有一行。

任何长时间使用智能体的人都熟悉其后果：模型开始更难记住项目规则，细节开始混淆，而自动压缩历史时，重要的内容也会丢失。子智能体从结构上解决了这个问题：脏活在独立的上下文中完成，答复之后即被丢弃。

• 搜索和调研。“找出所有调用支付函数的地方，并说明它们是如何组织的”——这是子智能体的典型任务。
• 嘈杂的检查。运行测试并分析失败的用例，交给子智能体，只拿回失败原因的列表。
• 阅读大型文档。一份几百页的规范只为了其中几个事实——让子智能体把它们提取出来。

如何配置子智能体：.claude/agents 目录

自定义子智能体用一个带 YAML 头部的 Markdown 文件描述。项目文件位于仓库的 .claude/agents/ 中，通过 git 对整个团队开放；个人文件位于 ~/.claude/agents/，在你所有的项目中都可用。也可以在 Claude Code 中用 /agents 命令交互式地创建和编辑子智能体。

---
name: code-reviewer
description: 检查代码改动中的错误和违反项目规则的情况。任务完成后、提交之前使用。
tools: Read, Grep, Glob, Bash
---
你是代码审查员。你不需要修改任何东西。

1. 查看改动：git diff。
2. 检查每处改动是否存在逻辑错误、错误处理缺陷、
   安全问题（SQL、输出转义、密钥）。
3. 对照 AGENTS.md 中的规则。
4. 返回问题列表：文件、行号、问题，以及为什么重要。
   如果没有问题，就明确写出来。

各字段的含义：

文件正文就是子智能体的系统提示。它看不到你与主智能体的对话历史，因此关于角色和回复格式的一切，都必须写在提示中，或者写在主智能体传递的任务中。

如何调用子智能体

如果任务符合其 description，主智能体可以自行选择子智能体。更可靠的做法是明确请求：“使用 code-reviewer 子智能体检查这些改动”。在描述中加入“主动使用”之类的字样，可以提高智能体在无人提醒时调用它的几率，但并不能保证。

只读的调研子智能体

几乎任何项目都值得配置的第二个文件，是只读的调研员。它回答关于代码的问题，但不做任何修改。

---
name: explorer
description: 在代码库中查找关于某事物位于何处、如何运作的答案。需要阅读大量文件以获得简短结论时使用。
tools: Read, Grep, Glob
---
你只调研代码，不做任何修改。
返回：对问题的简短回答，你所依据的文件及行号，
以及无法验证的部分。

这种子智能体在任务开始时特别有用：主智能体得到一张需要的位置地图，而不必把上下文耗在通读所有内容上，之后就可以直接处理具体的文件。

编排者与执行者模式

最常见的多智能体模式是：一个编排者智能体掌握计划和全局，把具体步骤分派给执行者。编排者不自己通读全部代码，而是提出任务、接收结果，并决定下一步做什么。

1. 编排者把任务拆分为独立的部分，并为每一部分写下独立完整的委托说明：目标、从哪里查找、什么算完成、以什么形式返回答复。
2. 执行者在各自的上下文中完成委托。
3. 编排者收集答复，检查各部分是否衔接，然后启动下一步，或回退到前一步。

这一模式的薄弱环节是任务的交接。子智能体只知道别人写给它的内容。“修一下我们讨论过的那个 bug”这样的委托对它毫无意义，因为它没有看过那段讨论。好的委托应当像写给一位第一次打开仓库的新同事的任务。

执行者应当返回什么

提前规定回复格式：文件列表、输出、找到的原因、未能验证的内容。简短的结构化回复可以节省编排者的上下文；“未验证的内容”这一项则能防止虚假的确定性——执行者和任何智能体一样，倾向于报告成功。

独立的审查者：为什么要把裁判与执行者分开

当同一个智能体既写代码又自己检查时，裁判和被告共用同一个脑袋。智能体记得自己想做什么，看到的是自己的设计意图，而不是代码实际写的内容。而且它有动机尽快结束任务，检查就很容易流于形式。

独立上下文中的审查者没有这些问题。它不了解决策历史，只看到差异和项目规则，并以新鲜的目光评估结果。这与真实团队的原则相同：作者不会自己批准自己的 pull request。

• 只给审查者读取和运行检查的工具，不给编辑文件的权限。这样它就不会“悄悄修复”，而是报告问题。
• 明确写出检查标准：什么算错误，哪些项目规则必须遵守。
• 对审查意见的处理决定留给编排者或人。审查者负责发现问题，执行者负责修复。

审查者不能替代机械化的检查。测试、linter 和类型检查是确定性的节点，比任何模型都可靠。审查者负责发现机械检查看不到的问题：错误的逻辑、违背约定、不必要的复杂性。

并行运行子智能体

Claude Code 能够同时运行多个子智能体。当任务的各部分确实相互独立时，这能加快速度：同时研究三个模块，从三个角度（安全、性能、测试）检查改动，从几个来源收集信息。

并行在读取任务上效果很好，在写入任务上则很糟糕。如果两个执行者同时修改同一批文件，它们会互相覆盖对方的改动，而且双方都不知道。用图中的术语来说，这就是缺少合并规则的共享状态。实用的规则是：

• 并行做调研、分析和审查。涉及相同文件的修改要顺序进行。
• 如果执行者确实要并行写入，就划分好区域：每个执行者只在自己的文件中工作，或在各自的仓库副本中工作（例如独立的 git worktree）。
• 结果由一个节点汇总——编排者，而不是执行者之间互相合并。

什么时候不需要子智能体

多智能体方案是有代价的：更多的 token，更多的时间，更多在传递中丢失信息的环节。子智能体并非总是划算。

在搭建智能体图之前，先回答几个简单的问题：谁对总目标负责，谁有权否决并回滚改动，成功用什么指标衡量。如果答不上来，多个智能体只会把一个人的混乱复制成更多份。

使用子智能体时的常见错误

描述含糊

“代码助手”这样的描述无法帮助主智能体判断何时调用它。应当写明触发条件：“修改 api/ 目录后，提交之前”。

委托缺少上下文

子智能体拿到的任务没有路径、没有完成标准、没有约束，于是花掉一半的工作量去猜测需要它做什么。解决办法是使用委托模板：目标、输入数据、约束、回复格式。

权限过大

调研员和审查者不需要编辑文件的权限。tools 字段是把角色变成机制、而不是提示中的一句请求的低成本方法。

不经验证就相信报告

子智能体回复中的“所有测试都通过”是一种断言，而不是事实。编排者应当依据可验证的内容：命令的输出、返回码、具体的行号。

总结

Claude Code 的子智能体用于三件事：保持主上下文干净，把验证与执行分开，并行处理相互独立的工作。它们通过 .claude/agents/ 中的简短 Markdown 文件来描述，其工作质量几乎完全取决于角色描述、工具集，以及委托说明是否足够自包含。当任务很小或与对话紧密相关时，单个智能体仍然更好。从单循环走向由节点、边和共享状态组成的系统，课程中结合实际项目有详细讲解。