子代理（Subagents）使用指南
一句话
创建专门的AI子代理处理特定任务，优化工作流程和上下文管理。
什么时候翻这页
- 需要处理会产生大量输出的任务（如运行测试、搜索代码库）
- 需要限制特定任务的工具访问权限
- 需要在多个项目中重复使用特定配置
- 需要为特定领域定制AI行为
核心概念
- 子代理（Subagents）：专门的AI助手，处理特定类型的任务，在独立上下文窗口中运行
- 上下文隔离：每个子代理拥有自己的上下文窗口（context window），不会污染主对话
- 工具限制：可以精确控制子代理能使用的工具，实现权限约束
- 作用域（Scope）：子代理可定义为组织级、会话级、项目级（
.claude/agents/）或用户级（~/.claude/agents/） - 内置子代理：Claude Code提供Explore、Plan和general-purpose等预定义子代理
怎么做
-
使用
/agents命令创建子代理- 运行
/agents打开管理界面 - 选择"Library" > "Create new agent" > "Personal"
- 描述子代理功能，选择工具和模型
- 配置记忆范围和颜色标识
- 运行
-
手动创建子代理文件
- 创建Markdown文件，包含YAML前置元数据和系统提示
- 必需字段：
name和description - 可选字段：
tools、model、memory等 - 示例：
--- name: code-reviewer description: Expert code review specialist tools: Read, Grep, Glob model: sonnet --- You are a senior code reviewer...
-
调用子代理
- 自然语言：在提示中命名子代理，Claude决定是否委托
- @-mention：
@"code-reviewer (agent)"确保特定子代理运行 - 会话范围：使用
--agent <name>启动整个会话作为子代理
命令 / 配置速查
| 命令/配置 | 说明 |
|---|---|
/agents | 打开子代理管理界面 |
--agents <json> | 通过CLI定义子代理 |
--agent <name> | 以特定子代理启动会话 |
name | 子代理唯一标识符（必需） |
description | 何时使用此子代理（必需） |
tools | 子代理可使用的工具列表 |
disallowedTools | 明确禁止使用的工具 |
model | 使用的AI模型（sonnet/opus/haiku/inherit） |
memory | 持久化记忆范围（user/project/local） |
background | 是否在后台运行（true/false） |
isolation | 隔离模式（worktree创建独立git工作区） |
初学者易错点
- 子代理不能创建其他子代理，避免无限嵌套
- 子代理定义中的
name值在整个作用域树中必须唯一 - 修改子代理文件后需要重启会话才能生效（通过
/agents创建的除外） - 子代理的上下文是隔离的，不会自动继承主会话的对话历史
- 插件提供的子代理不支持
hooks、mcpServers或permissionMode字段
相关词条
context-window上下文窗口管理agent-teams代理团队协作skills技能系统permissions权限控制hooks生命周期钩子worktreesGit工作区隔离