Subagent 是专门处理特定类型任务的 AI 助手。每个 Subagent 在独立的上下文窗口中运行，拥有自定义系统 Prompt、特定工具访问权限和独立的权限体系。当 Claude 遇到与某个 Subagent 描述匹配的任务时，会自动委托给它，Subagent 独立工作后返回结果。
Subagent 的核心价值
- 保护上下文：将探索和实现工作隔离在主对话之外
- 强制约束：限制 Subagent 能使用哪些工具
- 跨项目复用：用户级 Subagent 在所有项目中可用
- 专业化行为：为特定领域定制聚焦的系统 Prompt
- 控制成本：将任务路由到更快、更便宜的模型（如 Haiku）
内置 Subagent
Claude Code 包含以下内置 Subagent：
Explore（探索）
- 模型：Haiku（快速、低延迟）
- 工具：仅只读工具
- 用途：文件发现、代码搜索、代码库探索
- Claude 在需要搜索或理解代码库而不做修改时自动调用
Plan（计划）
- 模型：继承主对话
- 工具：仅只读工具
- 用途：在 Plan Mode 下收集上下文用于规划
General-purpose（通用）
- 模型：继承主对话
- 工具：所有工具
- 用途：需要探索和修改的复杂多步骤任务
快速创建第一个 Subagent
方法一：使用 /agents 命令（推荐）
bash
/agents选择「创建新 Agent」→「用户级别」→「用 Claude 生成」，描述你想要的 Agent：
一个代码改进 Agent，扫描文件并针对可读性、性能和最佳实践提出改进建议。
它应该解释每个问题，展示当前代码，并提供改进后的版本。
Claude 自动生成系统 Prompt 和配置，立即可用。
方法二：手动创建 Markdown 文件
markdown
---
name: code-reviewer
description: 审查代码质量和最佳实践
tools: Read, Glob, Grep
model: sonnet
---
你是一个代码审查员。被调用时，分析代码并对质量、安全性和最佳实践提供具体可操作的反馈。将此文件保存到：
.claude/agents/code-reviewer.md（项目级）~/.claude/agents/code-reviewer.md（用户级，所有项目可用）
作用域与优先级
| 位置 | 作用域 | 优先级 |
|---|---|---|
--agents CLI 参数 | 当前会话 | 1（最高） |
.claude/agents/ | 当前项目 | 2 |
~/.claude/agents/ | 所有项目 | 3 |
Plugin 的 agents/ 目录 | Plugin 启用时 | 4（最低） |
同名 Subagent 时，高优先级覆盖低优先级。
Subagent Frontmatter 字段
| 字段 | 必填 | 说明 |
|---|---|---|
name | 是 | 使用小写字母和连字符的唯一标识符 |
description | 是 | Claude 何时应委托给此 Subagent |
tools | 否 | 可用工具，省略则继承所有工具 |
disallowedTools | 否 | 要拒绝的工具 |
model | 否 | sonnet、opus、haiku 或 inherit（默认） |
permissionMode | 否 | default、acceptEdits、dontAsk、bypassPermissions、plan |
maxTurns | 否 | 最大轮次限制 |
skills | 否 | 在 Subagent 上下文中预加载的 Skills |
mcpServers | 否 | 此 Subagent 可用的 MCP 服务器 |
hooks | 否 | 此 Subagent 的生命周期 Hook |
memory | 否 | 持久记忆作用域：user、project 或 local |
background | 否 | 设为 true 始终作为后台任务运行 |
isolation | 否 | 设为 worktree 在隔离的 Git Worktree 中运行 |
实用 Subagent 示例
安全审查员
markdown
---
name: security-reviewer
description: 审查代码中的安全漏洞
tools: Read, Grep, Glob, Bash
model: opus
---
你是一名高级安全工程师。审查代码时关注：
- 注入漏洞（SQL、XSS、命令注入）
- 认证和授权缺陷
- 代码中的密钥或凭证
- 不安全的数据处理
提供具体的行号引用和修改建议。数据库查询验证器
markdown
---
name: db-validator
description: 验证 SQL 查询的性能和正确性
tools: Read, Bash
model: haiku
---
你是数据库专家。当被要求时：
1. 分析 SQL 查询是否存在 N+1 问题
2. 检查缺少索引
3. 验证事务的正确性
4. 提出性能优化建议CLI 定义的临时 Subagent
bash
claude --agents '{
"code-reviewer": {
"description": "Expert code reviewer. Use proactively after code changes.",
"prompt": "You are a senior code reviewer. Focus on code quality, security, and best practices.",
"tools": ["Read", "Grep", "Glob", "Bash"],
"model": "sonnet"
}
}'常见使用模式
隔离高容量操作
使用 subagent 检查所有 TypeScript 文件中未使用的导入，
生成一个报告，不要修改任何文件。
并行研究
同时用三个 subagent 分别研究：
1. 我们的认证流程
2. 数据库连接池配置
3. 错误处理模式
汇总后给我一个整体评估。
链式 Subagent
先用 security-reviewer subagent 审查这个实现，
然后将发现传给 general-purpose subagent 来修复问题。
管理 Subagent 列表
bash
# 交互式管理界面
/agents
# 命令行列出所有 Subagent
claude agents输出显示按来源分组的 Agent，并标注哪些被高优先级定义覆盖。
原文：Create custom subagents - Claude Code Docs | 来源：Claude Code 官方文档