Subagents 是在独立上下文窗口中运行的专用 AI 助手——拥有自定义系统提示词、特定工具访问权限和独立权限。Claude 根据任务匹配 Subagent 的描述自动委派。
内置 Subagent
Claude Code 包含 4 类内置 Subagent，自动按需使用：
Explore（代码库探索）
- 模型：Haiku（快速低延迟）
- 工具：只读（禁止 Write/Edit）
- 触发时机：Claude 需要搜索或理解代码库时自动委派，保持探索结果独立于主对话
- 调用时指定详细度：
quick（针对性查找）/medium（平衡）/very thorough（全面分析）
Plan（规划）
- 模型：继承主对话
- 工具：只读（禁止 Write/Edit）
- 触发时机：Plan 模式下 Claude 研究代码库准备计划时使用
General-purpose（通用）
- 模型：继承主对话
- 工具：全部工具
- 触发时机：需要探索+修改的复杂任务；多步骤依赖操作
其他内置 Helper Agent
| Agent | 模型 | 用途 |
|---|---|---|
| Bash | 继承 | 在独立上下文运行终端命令 |
| statusline-setup | Sonnet | 运行 /statusline 时配置状态栏 |
| Claude Code Guide | Haiku | 回答 Claude Code 功能问题 |
快速创建 Subagent（/agents 命令）
/agents
交互界面功能：
- 查���所有 Subagent（内置/用户/项目/插件）
- 向导式或让 Claude 生成创建新 Subagent
- 编辑配置和工具访问
- 删除自定义 Subagent
- 查看哪些 Subagent 被高优先级版本覆盖
7 步创建流程：/agents → 创建新 Agent → 选择 User-level → Generate with Claude → 描述 Agent → 选工具 → 选模型 → 选颜色 → 保存（无需重启即时可用）
四种存储位置
| 位置 | 作用范围 | 优先级 | 创建方式 |
|---|---|---|---|
--agents CLI 标志 | 当前会话 | 1（最高） | 启动时传入 JSON |
.claude/agents/ | 当前项目 | 2 | 交互式或手动 |
~/.claude/agents/ | 所有项目 | 3 | 交互式或手动 |
插件 agents/ 目录 | 插件启用的项目 | 4（最低） | 随插件安装 |
同名 Subagent 高优先级覆盖低优先级。
Subagent 文件格式
markdown
---
name: code-reviewer
description: 代码审查专家。代码修改后主动使用，关注质量、安全和性能。
model: sonnet
tools:
- Read
- Grep
- Glob
- Bash
permissionMode: default
---
你是高级代码审查员，专注：
## 审查重点
1. **代码质量**：命名、可读性、单一职责原则
2. **安全性**：SQL 注入、XSS、不安全的反序列化
3. **性能**：N+1 查询、不必要的计算、内存泄漏
4. **测试覆盖**：边界情况、错误处理
## 输出格式
每个问题：
- **位置**：文件和行号
- **问题**：具体描述
- **当前代码**：有问题的片段
- **改进建议**：更好的实现
- **严重性**：Critical / High / Medium / LowFrontmatter 完整字段参考
| 字段 | 类型 | 说明 |
|---|---|---|
name | string | Subagent 标识符（覆盖文件名） |
description | string | 最重要：Claude 根据此判断何时委派 |
model | string | haiku/sonnet/opus/inherit（默认 inherit） |
tools | list | 可用工具（省略则继承全部） |
disallowedTools | list | 明确禁止的工具 |
permissionMode | string | default/acceptEdits/plan/bypassPermissions |
skills | list | 预加载到 Subagent 上下文的 Skill 名称 |
mcpServers | object | Subagent 专用 MCP 服务器配置 |
hooks | object | 此 Subagent 的 Hooks（见下文） |
maxTurns | number | 最大 Agent 轮次 |
memory | bool/object | 持久记忆配置（见下文） |
allowedAgents | list | 可 spawn 的子 Subagent 名称列表 |
color | string | UI 颜色标识（如 purple） |
description 是关键
Claude 根据 description 决定是否委派任务给该 Subagent。写好 description 是让自定义 Subagent 被正确使用的最重要步骤：
yaml
# 好的 description
description: |
Expert code reviewer specializing in security and performance.
Use proactively after any code changes, when reviewing PRs,
or when asked about code quality issues.
# 不好的 description
description: Reviews code可用工具列表
| 工具组 | 包含工具 |
|---|---|
Read-only tools | Read、Glob、Grep、LS、WebFetch（只读） |
| 常用工具 | Bash、Edit、Write、Read、Glob、Grep、LS、WebFetch、TodoRead、TodoWrite |
| MCP 工具 | mcp__<server>__<tool> 格式 |
| Agent 工具 | Agent(<agent-name>) 格式 |
用 tools 指定白名单，用 disallowedTools 明确黑名单。两者可同时使用（黑名单优先）。
限制可 spawn 的 Subagent
yaml
---
allowedAgents:
- code-reviewer
- debugger
---不指定 allowedAgents 时，Subagent 可 spawn 任何 Subagent（但 Subagent 不能 spawn 另一个 Subagent 的 Subagent，最多一层嵌套）。
持久记忆（Persistent Memory）
启用后，Subagent 在会话间保留学习内容：
yaml
---
memory: true
---高级配置：
yaml
---
memory:
enabled: true
path: ~/.claude/memory/code-reviewer.md # 自定义存储路径
---记忆文件的前 200 行在每次会话开始时加载到 Subagent 上下文。
Hooks 配置
方式一：在 Frontmatter 中定义（Subagent 专属）
yaml
---
hooks:
PreToolUse:
- matcher: "Bash"
hooks:
- type: command
command: "echo 'Subagent running bash: ' $(jq -r .tool_input.command)"
---方式二：在 settings.json 中使用 SubagentStart/SubagentStop 事件
json
{
"hooks": {
"SubagentStart": [
{
"matcher": "code-reviewer",
"hooks": [{ "type": "command", "command": "echo 'Code reviewer started' >> /tmp/agents.log" }]
}
],
"SubagentStop": [
{
"matcher": "code-reviewer",
"hooks": [{ "type": "command", "command": "echo 'Code reviewer done' >> /tmp/agents.log" }]
}
]
}
}后台与前台运行
- 前台：Subagent 运行时，主会话显示进度（可中断）
- 后台（
Ctrl+B）：将当前 Subagent 移到后台，主会话立即可用；用/tasks或Ctrl+T查看后台 Subagent
4 个示例 Subagent（直接可用）
Code Reviewer：
yaml
---
name: code-reviewer
description: Expert code reviewer. Use proactively after code changes.
model: sonnet
tools: [Read, Grep, Glob, Bash]
---
你是高级代码审查员，专注代码质量、安全性和最佳实践...Debugger：
yaml
---
name: debugger
description: Debugging specialist for errors and test failures. Use when debugging issues.
model: sonnet
tools: [Read, Bash, Grep, Glob, Edit]
---
你是调试专家，分析错误日志、追踪根因并提供修复建议...Data Scientist：
yaml
---
name: data-scientist
description: Data analysis and visualization expert.
model: opus
tools: [Read, Bash, Write]
---
你是数据科学家，擅长数据分析、统计和可视化...Database Validator：
yaml
---
name: db-validator
description: Validates SQL queries for performance and security issues.
model: haiku
tools: [Read, Bash]
---
你是数据库专家，专注 SQL 查询性能优化和安全审计...原文：Create custom subagents - Claude Code Docs | 来源：Anthropic 官方文档