Subagents

• 分组：一、官方文档
• 原始链接：https://code.claude.com/docs/en/subagents
• 抓取来源：http://code.claude.com/docs/en/subagents
• 原始文件：/Users/yuanruiqin/Desktop/知识库/ClaudeCode-系统化知识库/01-官方文档/11-subagents.md
• 精读版生成时间：2026-04-05 13:50:44

中文精读版（去噪）

子代理是处理特定类型任务的专门人工智能助手。每个子代理都在自己的上下文窗口中运行，并具有自定义系统提示、特定工具访问权限和独立权限。当 Claude 遇到与子代理的描述相匹配的任务时，它会委托给该子代理，该子代理独立工作并返回结果。为了查看实践中的上下文节省，上下文窗口可视化 会遍历一个会话，其中子代理在其自己的单独窗口中处理研究。

子代理可以帮助您：

通过将探索和实施排除在主要对话之外来保留上下文 通过限制子代理可以使用哪些工具来强制约束 通过用户级子代理跨项目重用配置 通过针对特定领域的集中系统提示来实现专业化行为 通过将任务路由到更快、更便宜的模型（例如 Haiku）来控制成本

克劳德使用每个子代理的描述来决定何时委派任务。创建子代理时，请编写清晰的描述，以便 Claude 知道何时使用它。Claude Code 包含几个内置子代理，例如 探索、计划 和 通用。您还可以创建自定义子代理来处理特定任务。本页介绍了内置子代理、如何创建自己的子代理、完整配置选项、使用模式子代理 和示例子代理。

内置子代理

Claude Code 包含 Claude 在适当时自动使用的内置子代理。每个对话都继承父对话的权限，并具有附加的工具限制。

探索

计划

通用

其他

模型：俳句（快速、低延迟） 工具：只读工具（拒绝访问写入和编辑工具）

在计划模式期间使用的研究代理，用于在提出计划之前收集背景信息。

模型：继承自主对话 工具：只读工具（拒绝访问写入和编辑工具） 目的：用于规划的代码库研究

当您处于计划模式并且 Claude 需要了解您的代码库时，它将研究委托给计划子代理。这可以防止无限嵌套（子代理无法生成其他子代理），同时仍然收集必要的上下文。

一个能够执行需要探索和行动的复杂、多步骤任务的代理。

模型：继承自主对话 工具：所有工具 目的：复杂研究、多步骤操作、代码修改

当任务需要探索和修改、复杂的推理来解释结果或多个相关步骤时，Claude 会委托通用任务。

Claude Code 包括用于特定任务的附加帮助代理。这些通常会自动调用，因此您不需要直接使用它们。

除了这些内置子代理之外，您还可以使用自定义提示、工具限制、权限模式、挂钩和技能来创建自己的子代理。以下部分展示如何开始和自定义子代理。

快速入门：创建您的第一个子代理

子代理在带有 YAML frontmatter 的 Markdown 文件中定义。您可以手动创建 或使用“/agents”命令。本演练将指导您使用“/agents”命令创建用户级子代理。子代理审查代码并提出代码库的改进建议。

现在，您有了一个可以在计算机上的任何项目中使用的子代理来分析代码库并提出改进建议。您还可以将子代理手动创建为 Markdown 文件，通过 CLI 标志定义它们，或通过插件分发它们。以下部分涵盖所有配置选项。

配置子代理

使用 /agents 命令

“/agents”命令提供了用于管理子代理的交互界面。运行“/agents”以：

这是创建和管理子代理的推荐方法。对于手动创建或自动化，您还可以直接添加子代理文件。要从命令行列出所有配置的子代理而不启动交互式会话，请运行“claudeagents”。这显示了按源分组的代理，并指示哪些代理被更高优先级的定义覆盖。

选择子代理范围

子代理是带有 YAML frontmatter 的 Markdown 文件。根据范围将它们存储在不同的位置。当多个子代理共享相同名称时，优先级较高的位置获胜。

项目子代理 (.claude/agents/) 是特定于代码库的子代理的理想选择。将它们签入版本控制，以便您的团队可以协作使用和改进它们。项目子代理是通过从当前工作目录向上查找来发现的。使用“--add-dir”添加的目录仅授予文件访问权限，并且不会扫描子代理。要跨项目共享子代理，请使用“/.claude/agents/”或插件。用户子代理（“/.claude/agents/”）是所有项目中可用的个人子代理。CLI 定义的子代理在启动 Claude Code 时以 JSON 形式传递。它们仅在该会话中存在，不会保存到磁盘，这使得它们对于快速测试或自动化脚本非常有用。您可以在单个“--agents”调用中定义多个子代理：

克劳德--特工'{ “代码审查者”：{ "description": "专家代码审查者。代码更改后主动使用。", "prompt": "您是高级代码审查员。关注代码质量、安全性和最佳实践。", “工具”：[“读取”，“Grep”，“Glob”，“Bash”]， “模型”：“十四行诗” }, “调试器”：{ "description": "错误和测试失败的调试专家。", "prompt": "您是一位调试专家。分析错误、找出根本原因并提供修复。" }'

--agents 标志接受具有相同 frontmatter 字段的 JSON 作为基于文件的子代理：description、prompt、tools、disallowedTools、model、permissionMode、mcpServers、hooks、maxTurns、skills、 “初始提示”、“记忆”、“努力”、“背景”、“隔离”和“颜色”。使用“prompt”作为系统提示符，相当于基于文件的子代理中的 markdown 正文。托管子代理由组织管理员部署。将 markdown 文件放置在 托管设置目录 内的 .claude/agents/ 中，使用与项目和用户子代理相同的 frontmatter 格式。托管定义优先于同名的项目和用户子代理。插件子代理来自您已安装的插件。它们与您的自定义子代理一起出现在“/agents”中。有关创建插件子代理的详细信息，请参阅插件组件参考。

来自任何这些范围的子代理定义也可用于代理团队：生成队友时，您可以引用子代理类型，并且队友使用其“工具”和“模型”，并将定义的正文附加到队友的系统提示符中作为附加说明。请参阅 代理团队 了解哪些 frontmatter 字段适用于该路径。

写入子代理文件

子代理文件使用 YAML frontmatter 进行配置，后面是 Markdown 中的系统提示符：

姓名：代码审查员 描述：审查代码的质量和最佳实践 工具：Read、Glob、Grep 型号: 十四行诗

您是代码审查员。调用时，分析代码并提供 关于质量、安全性和最佳实践的具体、可操作的反馈。

frontmatter 定义了子代理的元数据和配置。主体成为指导子代理行为的系统提示。子代理仅接收此系统提示符（加上工作目录等基本环境详细信息），而不是完整的 Claude Code 系统提示符。

支持的 frontmatter 字段

以下字段可以在 YAML frontmatter 中使用。仅需要“名称”和“描述”。