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、选择模型

推荐：Sonnet

  • 分析能力与速度平衡

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 生命周期钩子

权限模式（务必理解）

模式 行为
default 正常权限提示
acceptEdits 自动接受编辑
dontAsk 自动拒绝未授权操作
bypassPermissions 跳过所有权限检查（⚠️危险）
plan 只读规划模式

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

如何使用子代理

自动委托

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

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

前台 vs 后台

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

快捷键：

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

典型使用模式

1、隔离高输出任务

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

2、并行研究

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

3、串联子代理

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

子代理上下文与恢复

  • 每次调用 = 新子代理实例
  • 子代理上下文独立存储
  • 可恢复继续执行：
继续刚才的 code-reviewer 分析，重点看授权逻辑

存储位置示例：

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

什么时候该用子代理？

用主对话，当：

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

用子代理，当：

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

子代理不能再创建子代理
需要嵌套 → 用 技能（Skills）