Sub-agents 是 Claude Code 里最被低估的功能之一。官方文档将其定位为"当侧边任务会用大量日志、搜索结果或文件内容淹没主会话时，把这个工作转移到独立上下文"的核心机制。本文是 Sub-agents 官方文档的完整整理。
Sub-agents 解决什么问题？
Claude Code 里有一个核心张力：主会话需要清晰的上下文，但调研和探索会产生大量"一次性"输出（搜索结果、日志、文件内容），这些内容用完就不需要了，却占据了上下文空间。
Sub-agent 让这些任务在独立的上下文窗口里完成，只把结果摘要返回给主会话。
Sub-agents 帮助你：
- 保护上下文：探索和调研不进入主对话
- 执行约束：限制 Sub-agent 可用的工具
- 跨项目复用：用户级 Sub-agent 在所有项目可用
- 专业化行为：针对特定领域的聚焦 system prompt
- 成本控制：把简单任务路由到更快更便宜的 Haiku 模型
内置 Sub-agents
Claude Code 内置三个自动使用的 Sub-agent：
Explore（探索）
- 模型：Haiku（快速低延迟）
- 工具：只读工具（拒绝 Write 和 Edit）
- 用途：文件发现、代码搜索、代码库探索
Claude 需要搜索或理解代码库但不需要做修改时，自动委托给 Explore。探索结果不会进入主对话的上下文。
当调用 Explore 时，Claude 会指定一个彻底程度：
- quick：目标性查找
- medium：平衡探索
- very thorough：全面分析
Plan（规划）
- 模型：继承自主会话
- 工具：只读工具
- 用途：在 Plan Mode 下为规划收集上下文
处于 Plan Mode 时，Claude 需要理解代码库时委托给 Plan Sub-agent。防止无限嵌套（Sub-agent 不能创建 Sub-agent），同时收集必要的上下文。
General-purpose（通用）
- 模型：继承自主会话
- 工具：所有工具
- 用途：需要探索和操作的复杂多步骤任务
需要同时探索和修改、复杂推理、多个依赖步骤时，Claude 委托给通用 Sub-agent。
创建自定义 Sub-agent：快速开始
方式一：/agents 交互界面（推荐）
bash
/agents界面分两个 Tab：
- Running Tab：查看正在运行的 Sub-agent，可以打开或停止
- Library Tab：查看/创建/编辑/删除 Sub-agent
创建步骤：
- Library Tab → Create new agent → Personal（保存到
~/.claude/agents/，所有项目可用） - Generate with Claude：描述你想要的 Agent，让 Claude 生成配置
- 选择工具、模型、颜色
- 配置持久内存（User scope 在
~/.claude/agent-memory/保留跨会话学习）
方式二：手动创建 Markdown 文件
markdown
---
name: code-improver
description: 扫描文件，针对可读性、性能和最佳实践提供改进建议
tools: Read # 只有只读工具
model: claude-sonnet-4-6
effort: high
color: cyan
memory: user # 跨会话持久内存
---
你是一名代码审查专家，专注于代码质量改进。
分析代码时，为每个发现提供：
1. 当前代码
2. 问题说明
3. 改进版本
优先级：可读性 > 性能 > 过早优化方式三：CLI 命令行
bash
# 列出所有配置的 Sub-agent
claude agents
# 使用指定 Agent 运行
claude --agent code-improverSub-agent 文件配置详解
完整 Frontmatter 字段
markdown
---
name: security-reviewer # 标识符（用于调用）
description: 安全漏洞检测专家 # Claude 用于决定何时委托的关键信息
tools: Read, Grep, Glob # 工具列表（逗号分隔）
disallowedTools: Write, Bash # 显式拒绝的工具
model: claude-opus-4-7 # 使用的模型
effort: xhigh # 努力等级
color: red # UI 颜色标识
memory: user # 持久内存范围（user/project/none）
permissionMode: readonly # 权限模式
skills: # 预加载的 Skills
- security-patterns
- owasp-checklist
context: fork # 上下文模式（fork = 独立上下文）
hooks: # Agent 专属 Hooks
PostToolUse:
- matcher: Read
hooks:
- type: command
command: echo "read file"
---模型选择策略
| 任务类型 | 推荐模型 |
|---|---|
| 简单代码搜索、文件查找 | claude-haiku-4-5（最快最省） |
| 代码审查、分析 | claude-sonnet-4-6（性价比最高） |
| 复杂架构分析、安全审计 | claude-opus-4-7（最强） |
| 长时间 Agent 任务 | claude-opus-4-7（1M 上下文） |
主会话用 Opus 4.7，探索类 Sub-agent 用 Haiku，可以大幅降低总成本。
Sub-agent 范围和优先级
| 位置 | 范围 | 优先级 |
|---|---|---|
| Managed settings | 组织全局 | 1（最高） |
--agents CLI 标志 | 当前会话 | 2 |
.claude/agents/ | 当前项目 | 3 |
~/.claude/agents/ | 所有项目 | 4 |
Plugin 的 agents/ 目录 | 插件启用处 | 5（最低） |
同名 Sub-agent 时，高优先级位置的定义覆盖低优先级。
控制 Sub-agent 的工具访问
可用工具类别
markdown
# 只读工具
tools: Read, Glob, Grep, LS
# 写入工具（谨慎）
tools: Write, Edit, MultiEdit
# 运行时工具
tools: Bash, Python
# MCP 工具（按服务器）
tools: mcp:postgres, mcp:github将 MCP 服务器限定到特定 Sub-agent
markdown
---
name: db-analyst
mcpServers:
postgres:
command: npx
args: ["-y", "@modelcontextprotocol/server-postgres"]
env:
DATABASE_URL: "${DATABASE_URL}"
---这个 MCP 服务器只在 db-analyst 运行时可用，不影响主会话或其他 Sub-agent。
Sub-agent 的工作模式
自动委托
Claude 根据 Sub-agent 的 description 字段判断是否委托：
markdown
---
description: 当需要分析 SQL 查询性能或数据库 Schema 时使用
---描述写得越精准，自动委托越准确。含糊的描述会导致误触发或漏触发。
显式调用
> 用 db-analyst agent 检查 orders 表的查询性能
> 让 security-reviewer 审查最近的 git 变更
> 启动一个 general-purpose 子任务，探索 src/api 的整体结构
前台 vs 后台运行
前台（默认）：当前对话暂停，等待 Sub-agent 完成后继续 后台：Sub-agent 并行运行，完成后自动报告结果
> 在后台运行完整测试套件，完成后告诉我结果。
与此同时，我们继续处理 API 端点的重构
常用模式
模式 1：隔离高容量操作
> 用 subagent 扫描整个 node_modules 目录，找出所有已知 CVE 漏洞
# 日志不会污染主会话
模式 2：并行调研
> 同时启动三个 subagent：
1. 分析 auth 模块的现有测试覆盖率
2. 检查 auth 模块的已知安全漏洞模式
3. 分析 auth 模块的性能瓶颈
各自完成后汇报
模式 3：链式 Sub-agent
> 先用 security-reviewer 审查代码，发现问题后，
用 fix-specialist agent 生成修复方案
模式 4：Fork 当前会话
bash
# 尝试一个不同方向，不破坏当前会话
claude -c --fork-sessionFork 出的会话继承当前完整上下文，可以在里面实验，主会话不受影响。
Fork vs 命名 Sub-agent：
- Fork：临时探索，共享父上下文
- 命名 Sub-agent：可复用配置，独立上下文
限制
- Sub-agent 不能创建 Sub-agent：防止无限递归
- 单次会话：Sub-agent 在会话内工作，跨会话协调用 Agent Teams
- 工具继承：Sub-agent 默认继承父会话的权限，但可以进一步限制（不能扩大）
官方示例 Sub-agent 配置
代码审查者（Code Reviewer）
markdown
---
name: code-reviewer
description: 当需要深入代码审查时使用。适合 PR 审查和代码质量评估
tools: Read, Glob, Grep
model: claude-sonnet-4-6
---
你是一名注重实用性的代码审查专家。
检查每个变更：
1. 是否有 Bug
2. 是否有安全漏洞
3. 是否符合 DRY 原则
4. 是否有可读性问题
每个发现包含：严重性（Critical/High/Medium/Low）、位置、说明、修复建议。
不要评论风格偏好，只关注实际问题。调试专家（Debugger）
markdown
---
name: debugger
description: 当需要追踪复杂 Bug 或分析错误日志时使用
tools: Read, Bash, Grep
model: claude-opus-4-7
effort: high
---
你是一名系统调试专家，擅长追踪复杂问题的根本原因。
分析方法：
1. 从错误表现回溯可能的原因链
2. 区分根本原因和派生错误
3. 建议最小化复现步骤
输出：根本原因 → 完整分析 → 修复方案 → 预防措施数据分析师（Data Scientist）
markdown
---
name: data-scientist
description: 当需要分析数据集、生成统计报告或数据可视化建议时使用
tools: Read, Bash
mcpServers:
postgres:
command: npx
args: ["-y", "@modelcontextprotocol/server-postgres"]
env:
DATABASE_URL: "${DATABASE_URL}"
---
你是一名数据分析专家，使用统计方法和可视化来发现洞察。
所有分析必须包含：样本量、置信区间、数据质量评估。来源：Claude Code 官方文档 - Create custom subagents | 整理：ClaudeEagle