Appearance
子代理：专业化 AI 助手
Claude Code 子代理（Subagents）是专业化 AI 助手，运行在独立上下文窗口中。每个子代理有自定义系统提示、专属工具权限和独立配置，Claude 遇到匹配任务时自动委托处理。内置子代理包括 Explore（只读搜索）、Plan（计划模式研究）和 general-purpose（全能工作）。自定义子代理放在 .claude/agents/（项目级）或 ~/.claude/agents/（用户级），Markdown 文件包含 frontmatter 配置和系统提示正文。
子代理是专业化的 AI 助手，负责处理特定类型的任务。每个子代理拥有独立的上下文窗口、自定义系统提示和专属工具权限，Claude 遇到匹配子代理描述的任务时会自动委托，子代理独立完成后返回摘要结果。
子代理的核心价值：
- 保护上下文：把探索和分析放在独立上下文，不污染主对话
- 强制约束：限制工具权限，让子代理只能做特定事
- 跨项目复用：用户级子代理在所有项目可用
- 专注领域：针对性系统提示让子代理更专业
- 控制成本：简单任务路由到 Haiku 等更便宜的模型
内置子代理
Claude Code 包含以下内置子代理，会在合适时自动使用：
Explore
快速只读代理，专为代码库搜索和分析优化。
- 模型：Haiku（快速低延迟）
- 工具：只读工具（禁用 Write 和 Edit）
- 用途：文件发现、代码搜索、代码库探索
调用时 Claude 会指定探索深度：quick（快速定向查找）、medium（均衡探索）或 very thorough（全面分析）。
Plan
计划模式下的研究代理。
- 模型：继承父会话
- 工具：只读工具
- 用途：计划模式下的代码库研究
在计划模式中，Claude 把代码库理解任务委托给 Plan 子代理，防止无限嵌套（子代理不能生成子代理）。
general-purpose
用于复杂多步骤任务的全能代理。
- 模型：继承父会话
- 工具：所有工具
- 用途：复杂研究、多步操作、代码修改
其他内置代理
| 代理 | 模型 | 使用时机 |
|---|---|---|
| statusline-setup | Sonnet | 运行 /statusline 配置状态栏 |
| Claude Code Guide | Haiku | 询问 Claude Code 功能问题 |
快速创建子代理
方式一：使用 /agents 命令（推荐）
- 运行
/agents - 选择 Library 标签 → "Create new agent"
- 选 "Personal"（保存到
~/.claude/agents/） - 选 "Generate with Claude"，描述需求
- 配置工具、模型、颜色
方式二：手动创建 Markdown 文件
在 .claude/agents/（项目级）或 ~/.claude/agents/（用户级）创建 .md 文件：
markdown
---
name: code-reviewer
description: 代码审查专家。代码修改后主动审查质量、安全性和可维护性。
tools: Read, Grep, Glob, Bash
model: sonnet
color: blue
---
你是高级代码审查员，确保代码质量和安全标准。
被调用时：
1. 运行 git diff 查看最近改动
2. 专注于被修改的文件
3. 立即开始审查
审查清单：
- 代码清晰可读
- 命名规范良好
- 没有重复代码
- 有适当的错误处理
- 没有暴露的 API key
- 测试覆盖充分
按优先级给出反馈：严重问题（必须修复）、警告（应该修复）、建议（可以改进）。方式三：通过 CLI 动态定义
传入 JSON 临时定义子代理，仅限本次会话，不写入磁盘：
bash
claude --agents '{
"code-reviewer": {
"description": "代码审查专家。代码修改后主动审查。",
"prompt": "你是高级代码审查员，专注代码质量、安全和最佳实践。",
"tools": ["Read", "Grep", "Glob", "Bash"],
"model": "sonnet"
}
}'子代理作用域和优先级
| 位置 | 作用域 | 优先级 |
|---|---|---|
| 托管设置 | 全组织 | 1（最高） |
--agents CLI 标志 | 当前会话 | 2 |
.claude/agents/ | 当前项目 | 3 |
~/.claude/agents/ | 所有项目 | 4 |
插件的 agents/ 目录 | 插件启用处 | 5（最低） |
同名子代理，高优先级覆盖低优先级。项目子代理适合提交到 git 与团队共享。用户子代理适合跨项目个人使用。
Frontmatter 完整字段参考
只有 name 和 description 是必填项：
| 字段 | 必填 | 说明 |
|---|---|---|
name | 是 | 唯一标识符，小写字母和连字符 |
description | 是 | Claude 何时应委托给此子代理 |
tools | 否 | 可用工具白名单。省略则继承所有工具 |
disallowedTools | 否 | 禁止使用的工具黑名单 |
model | 否 | 使用的模型：sonnet/opus/haiku/完整模型 ID/inherit。默认 inherit |
permissionMode | 否 | 权限模式：default/acceptEdits/auto/dontAsk/bypassPermissions/plan |
maxTurns | 否 | 最大代理回合数 |
skills | 否 | 预加载到子代理上下文的技能列表 |
mcpServers | 否 | 仅此子代理可用的 MCP 服务器 |
hooks | 否 | 子代理生命周期 hooks |
memory | 否 | 持久记忆范围：user/project/local |
background | 否 | true 则始终作为后台任务运行 |
effort | 否 | 思考深度：low/medium/high/max（Opus 4.6 专属） |
isolation | 否 | worktree 则在独立 git worktree 中运行 |
color | 否 | 任务列表中的显示颜色：red/blue/green/yellow/purple/orange/pink/cyan |
initialPrompt | 否 | 当此代理作为主会话代理运行时（通过 --agent 或 agent 设置），自动提交为第一条用户消息 |
模型选择
yaml
model: sonnet # Sonnet 4.6（均衡）
model: haiku # Haiku 4.5（快速省钱）
model: opus # Opus 4.6（最强能力）
model: claude-sonnet-4-6 # 完整模型 ID
model: inherit # 继承主会话（默认）Claude 调用子代理时模型解析顺序：
CLAUDE_CODE_SUBAGENT_MODEL环境变量- 调用时传入的
model参数 - 子代理 frontmatter 的
model - 主会话模型
工具控制
白名单（tools）
yaml
tools: Read, Grep, Glob, Bash只允许列出的工具，适合严格限制的场景（如只读研究代理）。
黑名单（disallowedTools）
yaml
disallowedTools: Write, Edit继承所有工具，但排除指定的。两者都设置时，先应用黑名单再解析白名单。
限制可生成的子代理
yaml
---
name: coordinator
description: 协调多个专业代理
tools: Agent(worker, researcher), Read, Bash
---Agent(worker, researcher) 是白名单，只能生成 worker 和 researcher 子代理。不含 Agent 则完全不能生成子代理。
权限模式
| 模式 | 行为 |
|---|---|
default | 标准权限检查和提示 |
acceptEdits | 自动接受工作目录内的文件编辑 |
auto | 后台分类器审查命令，自动判断是否允许 |
dontAsk | 自动拒绝权限提示（预批准工具仍可用） |
bypassPermissions | 跳过所有权限提示 |
plan | 计划模式（只读探索） |
若父会话使用
bypassPermissions或auto模式，子代理会继承且无法覆盖。
MCP 服务器作用域
给子代理配置主对话没有的 MCP 服务器：
yaml
---
name: browser-tester
description: 用真实浏览器测试功能
mcpServers:
# 内联定义：仅此子代理可用
- playwright:
type: stdio
command: npx
args: ["-y", "@playwright/mcp@latest"]
# 引用已配置的服务器名称
- github
---内联定义的 MCP 服务器仅对此子代理可用，不会出现在主对话中，不消耗主上下文的工具定义空间。
预加载技能
yaml
---
name: api-developer
description: 按团队约定实现 API 接口
skills:
- api-conventions
- error-handling-patterns
---技能内容在子代理启动时完整注入，而不是按需发现加载。子代理不继承父会话的技能，必须在此显式列出。
持久记忆
给子代理跨会话积累知识：
yaml
---
name: code-reviewer
description: 代码审查专家
memory: user
---| 范围 | 位置 | 使用场景 |
|---|---|---|
user | ~/.claude/agent-memory/<name>/ | 跨项目通用知识 |
project | .claude/agent-memory/<name>/ | 项目特定知识（可提交 git） |
local | .claude/agent-memory-local/<name>/ | 项目特定但不提交版本库 |
记忆目录的 MEMORY.md 前 200 行自动注入子代理上下文。
前台 vs 后台运行
前台子代理：阻塞主对话直到完成，权限提示会透传给你。
后台子代理：与主对话并行运行，启动前 Claude Code 会一次性申请所有需要的权限。
- 按 Ctrl+B 可将运行中的任务移到后台
- 设置
background: true让该子代理始终后台运行 - 设置
CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1禁用所有后台任务
隔离运行（git worktree）
yaml
isolation: worktree子代理在一个独立的 git worktree 中运行，对仓库的改动不影响主工作区。若子代理没有产生任何改动，worktree 自动清理；有改动时，路径和分支名会返回给你。
在会话中调用子代理
自动触发
Claude 根据 description 字段自动判断是否委托。描述中加入"主动使用"等字样可提高触发概率。
显式调用
使用 code-reviewer 子代理审查最近的改动
让 debugger 子代理分析这个失败的测试@提及
在输入框中输入 @，从自动补全选择子代理：
@"code-reviewer (agent)" 审查 auth 模块的改动整个会话作为子代理
bash
# 以指定子代理的身份运行主线程
claude --agent code-reviewer
# 项目默认（.claude/settings.json）
{
"agent": "code-reviewer"
}示例：常用子代理模板
调试器
markdown
---
name: debugger
description: 调试专家。遇到错误、测试失败时主动使用。
tools: Read, Edit, Bash, Grep, Glob
---
你是根因分析专家。
被调用时：
1. 捕获错误信息和调用栈
2. 确定复现步骤
3. 定位失败位置
4. 实现最小化修复
5. 验证解决方案
每个问题提供：根本原因、支持证据、具体修复方案、测试方法、预防建议。只读数据库查询
markdown
---
name: db-reader
description: 执行只读数据库查询，数据分析或报表生成时使用。
tools: Bash
---
你是数据库分析员，只有只读权限。
只执行 SELECT 查询，禁止 INSERT、UPDATE、DELETE 或修改 schema 的操作。何时使用子代理
适合子代理的任务：
- 会产生大量输出，不需要在主上下文中保留
- 需要严格的工具限制或权限
- 自包含，可以返回摘要
- 需要并行处理
留在主会话的任务：
- 需要频繁迭代
- 多阶段共享大量上下文
- 快速针对性修改
- 延迟敏感（子代理需要建立新上下文）
子代理不能生成其他子代理。需要链式委托时，在主对话中顺序调用多个子代理。
相关资源
- Skills：可复用工作流技能
- 权限配置：工具权限语法
- Hooks：生命周期钩子
- Agent Teams：多个并行独立会话的协作
常见问题
Q: 如何创建 Claude Code 子代理？
推荐用 /agents 命令交互式创建，选择 "Create new agent" 后描述需求并配置工具和模型。也可手动在 .claude/agents/ 或 ~/.claude/agents/ 下创建 .md 文件，frontmatter 写 name、description 等配置，正文写系统提示。
Q: 子代理和主会话有什么区别？
子代理有独立上下文，适合输出量大、需要工具限制或可并行的自包含任务。主会话适合频繁交互、共享复杂上下文的任务。子代理完成后只有摘要结果返回主会话。
Q: 子代理的模型可以和主会话不一样吗？
可以。在 frontmatter 中设置 model: haiku 可以让子代理使用更便宜的模型处理简单任务，显著降低成本。省略则默认继承主会话的模型。