13.Claude Code 子代理（Subagent）

在 Claude Code 中，你可以创建专门的 AI 子代理（Subagent），用于处理特定类型的任务，从而获得更好的上下文管理、更强的约束控制和更高的执行效率。

子代理是运行在独立上下文窗口中的专用 AI 助手。

每个子代理都可以拥有：

独立的系统提示（System Prompt）
独立的上下文（不污染主对话）
指定的模型（Sonnet / Haiku / Opus）
明确的工具访问权限
独立的权限模式
生命周期钩子（Hooks）

当 Claude 判断你的请求符合某个子代理的描述（description）时，就会自动将任务委托给该子代理，由它独立完成并返回结果。

为什么要使用子代理？

子代理的核心价值在于隔离 + 专业化。

它可以帮助你：

保留主对话上下文

把探索、扫描、日志分析等”重任务”放到子代理中

强制执行约束

例如：只读分析、禁止写文件、禁止执行危险命令

跨项目复用

用户级子代理一次配置，所有项目可用

行为专业化

为特定领域（代码审查、调试、数据分析）设计专用 AI

控制成本

将简单任务交给 Haiku，将复杂分析交给 Sonnet

一句话总结：

子代理 = 专门干某一类事的 AI 工具人

Claude Code 内置的子代理

Claude Code 已内置多种子代理，通常会自动使用，你不需要手动配置。

1、Explore（探索代理）

用途：只读搜索与分析代码库

模型：Haiku（速度快、延迟低）

工具：只读工具（不能 Edit / Write）

场景：

搜索文件
理解代码结构
查找定义和引用

Claude 会在需要看代码但不改代码时自动使用 Explore。

支持不同探索深度：quick / medium / very thorough。

2、Plan（规划代理）

用途：计划模式下的代码库研究

模型：继承主对话

工具：只读工具

场景：

在 Plan 模式中理解项目
为后续方案制定收集上下文

它的作用是：

在不产生嵌套代理的前提下，安全收集规划所需信息

3、General-purpose（通用代理）

用途：复杂、多步骤任务

模型：继承主对话

工具：全部工具

场景：

需要”看 + 改 + 推理”
多步骤代码修改
综合分析后给出结论

4、其他内部代理（无需手动使用）


代理	说明
Bash	在独立上下文中运行命令
statusline-setup	配置状态栏
Claude Code Guide	解答 Claude Code 使用问题

快速入门：创建你的第一个子代理

推荐方式：使用 /agents 命令

1、打开子代理管理界面

/agents

2、创建用户级子代理

选择 Create new agent
选择 User-level
保存位置：~/.claude/agents/（所有项目可用）

3、使用 Claude 自动生成

示例描述：

一个代码改进代理，扫描项目文件
针对可读性、性能和最佳实践提出建议
并给出改进示例。

Claude 会生成系统提示和初始配置，你可以按 e 手动编辑。

4、选择工具权限

只做代码审查 → 仅勾选只读工具
需要改代码 → 保留 Edit / Write

5、选择模型

6、保存并使用

使用 code-improver 子代理为此项目提出改进建议

子代理会独立运行并返回结果。

子代理的作用范围

子代理本质是带 YAML frontmatter 的 Markdown 文件，不同位置代表不同作用范围。


位置	范围	优先级
CLI —agents	当前会话	最高
.claude/agents/	当前项目	高
~/.claude/agents/	所有项目	中
插件 agents	插件作用域	最低

使用建议

项目子代理

跟代码一起提交
团队共享

用户子代理

个人习惯与工具

CLI 子代理

临时测试 / 自动化脚本

子代理配置文件结构

---
name: code-reviewer
description: Reviews code for quality and best practices 
tools: Read, Grep, Glob 
model: sonnet 
permissionMode: default 
--- 
 
You are a senior code reviewer. 
Analyze code and provide actionable feedback.

必填字段

name：唯一标识（小写 + 连字符）

description：非常重要，Claude 是否调用它主要靠这个

常用字段说明


字段	作用
tools	允许使用的工具
disallowedTools	明确禁止的工具
model	可选值：haiku / sonnet / opus / inherit
permissionMode	权限行为控制
skills	注入技能
hooks	生命周期钩子

⚠️ bypassPermissions 只适合完全可信的子代理

如何使用子代理

自动委托

Claude 会根据你的描述自动判断：

让 code-reviewer 子代理检查最近的改动

前台 vs 后台

前台：阻塞主对话，可交互后台：并行执行，不打断你（无 MCP、无交互）

快捷键：

Ctrl + B：将运行中的子代理放到后台

典型使用模式

1、隔离高输出任务

使用子代理运行测试，只返回失败的测试

2、并行研究

并行使用子代理分析认证、数据库和 API 模块

3、串联子代理

先用code-reviewer找问题,
再用 optimizer修复问题

子代理上下文与恢复

每次调用 = 新子代理
实例子代理
上下文独立存储

可恢复继续执行：

继续刚才的code-reviewer分析,重点看授权逻辑

存储位置示例：

~/.claude/projects/{project}/{sessionId}/subagerts

什么时候该用子代理？

用主对话，当：

需要频繁来回调整
多阶段强依赖
上下文快速、小改动

用子代理，当：

任务自包含
输出很大
需要强约束或复用

子代理不能再创建子代理

需要嵌套 → 用技能（Skills）

烧饼的分享站

Explorer