子代理（Subagents）使用指南

原文：Create custom subagents

一句话

创建专门的AI子代理处理特定任务，优化工作流程和上下文管理。

什么时候翻这页

1. 需要处理会产生大量输出的任务（如运行测试、搜索代码库）
2. 需要限制特定任务的工具访问权限
3. 需要在多个项目中重复使用特定配置
4. 需要为特定领域定制AI行为

核心概念

• 子代理（Subagents）：专门的AI助手，处理特定类型的任务，在独立上下文窗口中运行
• 上下文隔离：每个子代理拥有自己的上下文窗口（context window），不会污染主对话
• 工具限制：可以精确控制子代理能使用的工具，实现权限约束
• 作用域（Scope）：子代理可定义为组织级、会话级、项目级（.claude/agents/）或用户级（~/.claude/agents/）
• 内置子代理：Claude Code提供Explore、Plan和general-purpose等预定义子代理

怎么做

1. 使用 /agents 命令创建子代理

   • 运行 /agents 打开管理界面
   • 选择"Library" > "Create new agent" > "Personal"
   • 描述子代理功能，选择工具和模型
   • 配置记忆范围和颜色标识

2. 手动创建子代理文件

   • 创建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...
     

3. 调用子代理

   • 自然语言：在提示中命名子代理，Claude决定是否委托
   • @-mention：@"code-reviewer (agent)" 确保特定子代理运行
   • 会话范围：使用 --agent <name> 启动整个会话作为子代理

命令 / 配置速查

初学者易错点

1. 子代理不能创建其他子代理，避免无限嵌套
2. 子代理定义中的name值在整个作用域树中必须唯一
3. 修改子代理文件后需要重启会话才能生效（通过/agents创建的除外）
4. 子代理的上下文是隔离的，不会自动继承主会话的对话历史
5. 插件提供的子代理不支持hooks、mcpServers或permissionMode字段

相关词条

• context-window 上下文窗口管理
• agent-teams 代理团队协作
• skills 技能系统
• permissions 权限控制
• hooks 生命周期钩子
• worktrees Git工作区隔离