Subagent 是专门处理特定类型任务的 AI 助手，每个 Subagent 有自己的 Context 窗口、自定义系统提示、特定工具访问权限和独立权限设置。Claude 遇到匹配 Subagent 描述的任务时自动委托，Subagent 独立工作后返回结果。
Subagent 的四大价值
- 保留 Context：探索和实现在主对话之外进行
- 强制约束：限制 Subagent 能使用哪些工具
- 跨项目复用：用户级 Subagent 在所有项目可用
- 专项行为：针对特定领域的专注系统提示
- 控制成本：将任务路由到更快更便宜的 Haiku 模型
四大内置 Subagent
Explore（探索）
专为搜索和分析代码库优化的快速只读 Agent。
- 模型：Haiku（快速低延迟）
- 工具：只读工具（禁止 Write 和 Edit）
- 用途：文件发现、代码搜索、代码库探索
Claude 需要搜索或理解代码库但不做修改时自动委托给 Explore。探索结果不占用主对话 Context。
调用时 Claude 会指定探索深度：quick（快速定位）、medium（平衡探索）、very thorough（全面分析）。
Plan（规划）
Plan Mode 下在呈现计划前收集上下文的研究 Agent。
- 模型：继承主对话
- 工具：只读工具
- 用途：规划前的代码库研究
General-purpose（通用）
适合复杂多步骤任务（既需要探索又需要修改）的能力全面 Agent。
- 模型：继承主对话
- 工具：所有工具
- 用途：复杂研究、多步操作、代码修改
辅助 Agents
| Agent | 模型 | 自动调用时机 |
|---|---|---|
| Bash | 继承 | 在独立 Context 中运行终端命令 |
| statusline-setup | Sonnet | 运行 /statusline 配置状态栏时 |
| Claude Code Guide | Haiku | 询问 Claude Code 功能问题时 |
快速创建第一个 Subagent
方式一：/agents 交互界面（推荐）
/agents
→ Create new agent
→ User-level（保存到 ~/.claude/agents/，所有项目可用）
→ Generate with Claude
→ 描述你想要的 Subagent：
「一个代码改进 Agent，扫描文件并针对可读性、性能和最佳实践提出改进建议。
解释每个问题，展示当前代码，并提供改进版本。」
→ 选择工具（只读审查员：只选 Read-only tools）
→ 选择模型（Sonnet 适合代码分析）
→ 选择颜色（方便 UI 中识别）
→ Save
保存后立即可用，无需重启：
> 使用 code-improver agent 为这个项目提出改进建议
方式二：手动创建 Markdown 文件
markdown
---
name: code-reviewer
description: 专家代码审查员。Claude 完成代码修改时自动调用。分析代码质量、安全漏洞、测试覆盖率和性能问题。
model: sonnet
tools:
- Read
- Grep
- Glob
- Bash
permission_mode: plan
color: blue
---
你是一位资深代码审查员。关注：
1. 代码质量和可维护性
2. 安全漏洞（SQL 注入、XSS、未验证输入）
3. 测试覆盖率，尤其是边缘用例
4. 性能问题（N+1 查询、内存泄漏）
对每个发现给出严重程度（high/medium/low）。方式三：--agents CLI Flag（临时会话）
bash
claude --agents '{
"code-reviewer": {
"description": "代码审查员，代码修改后自动调用",
"prompt": "你是资深代码审查员，关注质量、安全、测试和性能。",
"tools": ["Read", "Grep", "Glob"],
"model": "sonnet"
}
}'作用域和优先级
| 位置 | 作用域 | 优先级 |
|---|---|---|
--agents CLI Flag | 当前会话 | 1（最高） |
.claude/agents/ | 当前项目 | 2 |
~/.claude/agents/ | 所有项目 | 3 |
Plugin agents/ 目录 | 插件启用的地方 | 4（最低） |
同名 Subagent 时，高优先级覆盖低优先级。
Frontmatter 配置字段
yaml
---
name: my-agent # Subagent 名称（必填）
description: "..." # Claude 决定何时委托的依据（必填，写清楚！）
model: sonnet # sonnet/opus/haiku/inherit（默认 inherit）
tools: # 允许的工具列表
- Read
- Edit
- Bash
disallowedTools: # 明确禁止的工具
- Write
permission_mode: plan # default/plan/acceptEdits/bypassPermissions
color: blue # UI 显示颜色
skills: # 预加载的 Skills
- my-skill
maxTurns: 10 # 最大 Agentic 轮次
env: # 额外环境变量
MY_VAR: value
---启用持久记忆
Subagent 可以有自己的 Auto Memory，跨会话保留学习内容：
yaml
---
name: database-expert
description: 数据库查询专家，了解项目 Schema 后自动记住
autoMemory: true
---工作模式
前台运行：Subagent 工作时主会话等待
后台运行（Ctrl+B）：Subagent 后台工作，你继续与主 Claude 对话，完成时自动汇报
常用模式
隔离高流量操作
> 用 Subagent 分析这个 1GB 的日志文件，只返回过去 24 小时的错误摘要
# 详细日志留在 Subagent Context，主对话只收到摘要
并行研究
> 并行调研三件事：
> 1. 现有认证实现的安全漏洞
> 2. 行业最佳实践
> 3. 我们的测试覆盖率缺口
链式 Subagent
> 用探索 Agent 分析代码库，然后用规划 Agent 制定重构计划
内置 Subagent 示例
yaml
# 代码审查员
---
name: code-reviewer
description: 专家级代码审查员。代码修改后主动调用。
model: sonnet
tools: [Read, Grep, Glob, Bash]
---
# 调试专家
---
name: debugger
description: 调试专家，处理错误和测试失败。
model: sonnet
tools: [Read, Edit, Bash]
---
# 数据科学家
---
name: data-scientist
description: 数据分析和可视化专家。
model: sonnet
tools: [Read, Bash, Write]
---原文：Create custom subagents | 来源：Anthropic 官方文档