Subagents in Claude Code

概述

Subagents（子智能体）是 Claude Code 中的独立代理实例，拥有自己的上下文窗口。主代理可以派遣子智能体处理独立任务，子智能体完成后仅返回相关结果。子智能体如同 Claude Code 会话中的浏览器标签页，允许探索旁支思路而不中断主线。

关键内容

什么是子智能体

核心特性： - 独立性：每个子智能体是独立的 Claude 实例，有自己的上下文窗口 - 隔离性：不受对话历史或已调用技能的影响 - 并行性：多个子智能体可并行运行 - 权限控制：每个子智能体可有不同的权限（只读/完全编辑）

内置子智能体类型： 1. 通用型智能体：适用于复杂的多步骤任务 2. 规划智能体：先研究代码库，再提出实施策略 3. 探索型智能体：专为快速的只读代码搜索而优化

使用子智能体的场景

1. 研究类任务 - 信号：收集背景信息需要阅读数十个文件 - 好处：核心对话保持简洁，呈现整合后的结论而非原始内容 - 示例：探索代码库中的身份验证工作原理

2. 多个独立任务 - 信号：子任务之间没有依赖关系 - 好处：三个子智能体同时工作通常能在更短的时间内完成任务 - 示例：并行修复多个包中的 TypeScript 错误

3. 需要全新视角 - 信号：需要在不将对话历史纳入分析的情况下进行验证 - 好处：更清晰、更客观的反馈 - 示例：对实现进行客观评估，不受实施过程影响

4. 提交前验证 - 信号：提交代码前需要征求第二种意见 - 好处：能发现因对代码过于熟悉而可能被忽略的问题 - 示例：验证实现不会过度拟合测试用例或遗漏边界情况

5. 流水线工作流 - 信号：存在具有明确交接的连续阶段 - 好处：每个子智能体专注于自身阶段，不会因其他阶段的上下文产生干扰 - 示例：设计→实施→测试的三阶段流水线

专业提示：当任务需要浏览 10+ 文件，或涉及 3+ 独立工作内容时，是引导 Claude 使用子智能体的强烈信号。

调用子智能体的方法

1. 对话式调用（最灵活） - 适用于所有 Claude Code 界面（终端/VS Code/JetBrains/网页/桌面） - 自然语言模式示例： - "使用子代理探索此代码库中的身份验证工作原理" - "让一个独立的智能体检查这段代码是否存在安全问题" - "同步开展这项研究。同时检查 API 路由、数据库模型和前端组件"

高效提示词结构：

使用子代理并行探索此代码库：

1. 查找所有 API 端点并总结其用途
2. 识别数据库模式和关系
3. 映射身份验证流程

返回每项的摘要，而非完整文件内容。

2. 自定义子代理 - 定义位置： - 项目级：.claude/agents/（与团队共享） - 用户级：~/.claude/agents/（所有项目可用） - 配置内容：系统提示词、工具权限、可选专属模型 - 自动委派：当任务与描述匹配时，Claude 自动委派 - 创建方式：/agents 命令交互式创建，或手动编写

示例：安全审查子代理

---
name: security-reviewer
description: 在提交前审查代码中的安全问题。
  在涉及身份验证、支付或用户数据的提交前主动使用。
tools: Read, Grep, Glob
model: sonnet
---

你是专注于安全的代码审查员。分析提供的更改：
- SQL 注入、XSS 和命令注入风险
- 身份验证和授权漏洞
- 日志、错误或响应中的敏感数据
- 不安全的依赖项或配置

返回按优先级排序的问题列表，包含文件：行引用和推荐修复方案。

3. CLAUDE.md 指令 - 适用场景： - 代码审查应始终使用只读子代理 - 项目有特定的研究模式需要 Claude 遵循 - 团队成员和会话之间需要保持一致的行为 - 优势：Claude 在每次对话开始时读取，行为保持一致

4. 技能（Skills） - 适用场景： - 某些操作会被定期执行 - 不同团队成员需要访问同一个复杂操作 - 在团队中统一部分任务的执行方式至关重要 - 与 CLAUDE.md 的区别：技能按需加载，CLAUDE.md 始终加载

5. 钩子（Hooks） - 适用场景： - 每次提交都应在创建前自动进行审核 - 安全检查应在无人提醒的情况下自动执行 - 类 CI 的质量门禁应纳入本地开发流程 - 最自动化：基于事件自动触发子智能体工作流

实用模式

模式 1：实施前调研

在实施用户通知功能之前，使用子代理调研：
- 当前代码库中如何发送电子邮件？
- 已存在哪些通知模式？
- 根据当前架构，新的通知逻辑应该放在哪里？

总结发现，然后我们一起规划实施。

模式 2：并行修改

使用并行子代理更新以下文件中的错误处理：
- src/api/users.ts
- src/api/orders.ts
- src/api/products.ts

每个都应遵循 src/api/auth.ts 中建立的模式。
同时处理所有三个文件。

模式 3：独立审查

使用一个具有只读权限的全新子代理审查我的支付流程实现。
它不应看到我们之前的讨论。我想要一个客观的审查。

检查：安全漏洞、未处理的边界情况、错误处理漏洞。严格审查。

模式 4：流水线工作流

让我们以流水线方式构建此功能：

1. 第一个子代理：设计 API 合约并写入 docs/api-spec.md
2. 第二个子代理：根据该规范实施后端端点
3. 第三个子代理：为实施编写集成测试

每个阶段应在下一个阶段开始之前完成。
使用输出文件作为阶段之间的交接机制。

何时不应使用子智能体

1. 顺序化的依赖型工作 - 当第二步需要第一步的完整输出，第三步需要前两者的结果时 - 单个会话处理整个流程通常更简洁

2. 同文件编辑 - 两个子代理并行编辑同一个文件极易引发冲突 - 需将紧密耦合的修改放在同一个上下文窗口中

3. 小任务 - 快速解决问题或解答某个具体问题 - 委托的额外成本会超过其带来的好处

4. 专业智能体过多 - 为所有事物都定义自定义子智能体会降低自动委托的可靠性 - 大多数团队最终选择少数几个范围明确的智能体

5. 需要智能体相互协作的工作 - 子智能体向主对话汇报，但彼此之间无法交流 - 应使用 Agent-Teams（智能体团队），子智能体在不同会话间协调

最佳实践

对话式调用技巧： - 明确任务范围："探索支付系统的运作方式"比"探索所有事物"更好 - 显式请求并行化："这些可以并行运行"或"同时处理全部三个" - 指定输出格式：摘要、具体发现或建议 - 获取新的上下文：在需要客观分析时使用

专业提示： - 当子代理需要较长时间时，按 Ctrl+B 可将其转入后台运行 - /tasks 命令可查看所有后台运行的任务 - 从对话式调用开始，随着模式清晰再构建自动化

来源

raw/articles/ai-engineering/claude-blog/How and when to use subagents in Claude Code.md — Anthropic 官方指南