Claude Subagent 完全指南

从概念到实践掌握 Claude 子代理：理解独立上下文、使用内置代理、创建自定义 Subagent，提升 AI 编程效率

引言

A multi-agent system with Claude Opus 4 as the lead agent and Claude Sonnet 4 subagents outperformed single-agent Claude Opus 4 by 90.2% on an internal research eval.

AnthropicHow we built our multi-agent research system

前往

在使用 Claude Code 处理复杂任务时，你可能遇到过这样的困境：主对话的上下文越来越长，AI 开始"忘记"之前的重要信息，响应质量逐渐下降。

Subagent（子代理）就是为解决这个问题而生的。

如果说 Skills 是给 Claude 的"工作手册"，那么 Subagent 就是你雇佣的"专职员工"——它们有自己独立的工位（上下文），专注于特定类型的工作，完成后向你汇报结果。

理解 Subagent

想象你是一家公司的 CEO。当公司规模小的时候，你亲自处理所有事务。但随着业务扩展，你开始雇佣专职员工：会计负责财务、HR 负责招聘、工程师负责开发。每个员工在自己的工位上工作，处理完任务后向你汇报。

Subagent 在 Claude Code 中扮演的正是这样的角色。

从技术角度来说，Subagent 是专门化的 AI 助手，它们具有以下特点：

特性	说明
独立上下文	每个 Subagent 在自己的上下文窗口中运行
专门化能力	针对特定任务类型进行优化
可配置工具	只能访问指定的工具集
自定义提示	有专门的系统提示指导行为

为什么需要独立上下文

这是 Subagent 最核心的设计理念，值得深入理解。

在普通对话中，所有信息都堆积在同一个上下文里。当你让 Claude 搜索代码库、分析文件、然后进行修改时，所有这些中间过程都会占用上下文空间。随着对话深入，上下文越来越拥挤，Claude 可能开始"忘记"早期的重要信息。

Subagent 改变了这一点：

主对话（专注于高层目标）
│
├── 用户：帮我优化这个模块的性能
│
├── Claude：我来分析一下...
│   │
│   └── [调用 Explore Subagent]
│       │ 在独立上下文中：
│       ├── 搜索相关文件
│       ├── 分析代码结构
│       ├── 识别性能瓶颈
│       └── 返回：发现 3 个优化点...
│
└── Claude：根据分析，我发现 3 个优化点...

Subagent 的分析过程不会污染主对话。主对话只收到精炼的结果，保持了清晰和专注。

正如 Anthropic 在其最佳实践中建议的：

Tell Claude to use subagents to verify details or investigate particular questions it might have, especially early on in a conversation or task, tends to preserve context availability without much downside in terms of lost efficiency.

AnthropicClaude Code: Best practices for agentic coding

前往

内置 Subagent 类型

Claude Code 自带三个常用的内置 Subagent，开箱即用：

类型	模型	定位
Explore	Haiku	快速只读探索代码库
Plan	Sonnet	研究代码库，准备实施计划
General-purpose	Sonnet	处理复杂的多步任务

这些内置代理会根据任务类型自动调用。

我的理解与实践

仔细观察官方内置的三个 Subagent，你会发现一个共同点：它们都是调研和规划类的任务。Explore 负责探索代码库，Plan 负责制定计划，即使是 General-purpose 也主要用于研究和分析。没有一个是专门用来写代码的。

这印证了我对 Subagent 的理解：Subagent 的核心价值不是"干净的上下文"，而是让主 agent 能够专注做事。

分工模式

我的使用方式很简单：Subagent 负责调研、规划、review 这类"信息收集"的工作，主 agent 负责实际执行。

Subagent（调研员）          主 Agent（执行者）
     │                           │
     ├── 探索代码库结构            │
     ├── 分析依赖关系              │
     ├── 制定实施计划              │
     └── 返回精炼的上下文 ──────────→ 基于上下文执行任务
                                  │
                                  ├── 编写代码
                                  ├── 修改文件
                                  └── 运行测试

为什么不让 Subagent 写代码

有些人喜欢让主 agent 调度多个 subagent 去写代码，我觉得这不太靠谱。原因很简单：上下文严重缺失。

Subagent 的上下文是独立的，它不知道主对话中讨论过什么、做过什么决定、有什么约束。让它去写代码，就像让一个刚入职的员工在没有任何背景信息的情况下独立完成任务——产出的代码很可能和你的预期不符。

相反，把 Subagent 定位为"调研员"就合理多了：

调研任务本身就不需要太多上下文
返回的是信息而不是代码，主 agent 可以基于完整上下文来使用这些信息
即使调研结果有偏差，主 agent 也能纠正

我的日常用法

开始新任务前：让 Explore 代理快速了解相关代码的结构
复杂任务规划：让 Plan 代理分析需求并制定实施步骤
代码审查：让 Review 代理检查代码质量和安全问题
实际编码：主 agent 基于收集到的上下文来写代码

这是我目前使用的 agent 列表：

我的 Subagent 列表

这样做的好处是：主 agent 的上下文窗口保持干净，只有"我需要知道的信息"，而不是"Subagent 搜索过程中产生的一堆中间结果"。

如何使用 Subagent

查看可用代理

使用 /agents 命令可以查看当前环境中所有可用的 Subagent：

/agents

这会列出内置代理和你配置的自定义代理。

自动委托

大多数情况下，你不需要手动指定使用哪个 Subagent。Claude 会根据任务类型自动选择合适的代理：

代码探索任务 → Explore Subagent
需要制定计划 → Plan Subagent
复杂多步任务 → General-purpose Subagent

显式调用

如果你想明确使用某个代理，可以在提示中直接说明：

使用 Explore 代理搜索所有包含 authentication 的文件

或者：

启动一个子代理来分析这个模块的依赖关系

Claude Plugin Hub - 插件市场，可以找到各种 agent 和插件：

前往

创建自定义 Subagent

除了使用内置代理和社区资源，你还可以创建自己的 Subagent。

配置文件位置

位置	路径	作用域
用户级	`~/.claude/agents/`	全局，跨所有项目
项目级	`.claude/agents/`	仅当前项目（优先级更高）

配置格式

每个 Subagent 是一个 Markdown 文件，包含 YAML frontmatter 和系统提示词：

---
name: code-reviewer
description: Reviews code for security and style issues. Use PROACTIVELY after code changes.
tools: Read, Grep, Glob
model: sonnet
---

You are a senior code reviewer focusing on:
- Security vulnerability detection
- Code style and best practices
- Performance optimization

## Review Output
1. **Critical Issues**: Security, correctness
2. **Warnings**: Style, performance
3. **Suggestions**: Refactoring opportunities

字段说明

字段	必填	说明
`name`	是	代理名称，用于调用
`description`	是	触发条件描述，决定自动调用时机
`tools`	否	允许的工具列表，省略则继承所有（包括 MCP 工具）
`model`	否	`sonnet`、`opus`、`haiku` 或 `inherit`
`permissionMode`	否	`default`、`acceptEdits` 或 `plan`

工具权限

根据代理角色配置最小必要权限：

角色类型	工具配置
只读分析（审查、审计）	`Read, Grep, Glob`
研究调研（需要网络）	`Read, Grep, Glob, WebFetch, WebSearch`
开发实现（需要写入）	`Read, Write, Edit, Bash, Grep, Glob`

高级能力

Subagent 作为独立个体，可以访问主 agent 的大部分能力：

MCP 工具访问

省略 tools 字段会自动继承所有 MCP 工具。如需显式指定，格式为：

tools: Read, Grep, mcp__github__create_issue, mcp__linear__list_issues

Skills 知识

如需 Subagent 使用特定 Skill 的知识，在系统提示正文中说明：

---
name: code-reviewer
description: Reviews code for quality issues
tools: Read, Grep, Glob
---

You are a code reviewer. Follow the guidelines in the code-standards skill.

When reviewing:
- Apply project coding standards
- Check for security issues

这样 Subagent 会在执行时参考相关 Skill 的指导。

权限模式

模式	行为
`default`	读取自动批准，修改需确认
`acceptEdits`	自动批准文件编辑
`plan`	只读模式，禁止任何修改

限制

不能调用其他 Subagent（防止无限递归）
不支持分步计划

最佳实践

单一职责：每个代理专注一个明确目标
最小权限：只授予必要的工具
清晰描述：description 决定自动调用的质量，写清楚"什么时候用"
版本控制：项目级配置提交到 Git，便于团队共享

写在最后

Subagent 的核心价值是让主 agent 专注做事。把 Subagent 定位为调研员而不是执行者，你会发现 Claude Code 的效率大幅提升。

如果你还不熟悉 Claude Code 的基础使用，建议先阅读《我的 Claude Code 最佳实践》了解核心命令和工作流程。

引言