name: Subagent System description: 为任务特定工作流创建和管理专门的Claude Code子代理。在委托工作给专门代理、配置代理权限或理解子代理架构和最佳实践时使用。
子代理系统
何时使用
- 为任务特定工作创建专门子代理
- 委托工作给预配置代理
- 管理子代理工具权限和范围
- 理解何时使用代理委托与直接工作
什么是子代理？
预配置的AI个性，Claude Code可以委托任务给它们。每个：
- 有特定目的和专长领域
- 使用单独的上下文窗口（防止污染）
- 可以配置特定工具
- 包括自定义系统提示
好处：
- 上下文保存 — 每个在自有上下文中操作，保持主对话专注
- 专门专长 — 针对特定领域的精细调优指令
- 可重用性 — 跨项目使用并与团队共享
- 灵活权限 — 每个代理的不同工具访问级别
创建子代理
文件位置
| 类型 | 位置 | 范围 |
|---|---|---|
| 项目子代理 | .claude/agents/ |
仅当前项目 |
| 用户子代理 | ~/.claude/agents/ |
所有项目 |
当名称冲突时，项目级子代理优先于用户级。
文件格式
每个子代理是一个带有YAML前言的Markdown文件：
---
name: your-sub-agent-name
description: 何时调用此子代理
tools: tool1, tool2, tool3 # 可选 - 如果省略则继承所有
model: sonnet # 可选 - 指定模型或'inherit'
---
您的子代理的系统提示放在这里。多个段落。
包括角色、能力、方法、最佳实践、约束。
配置字段
| 字段 | 必需 | 描述 |
|---|---|---|
name |
是 | 唯一标识符（小写+连字符） |
description |
是 | 自然语言目的描述 |
tools |
否 | 逗号分隔的工具（如果省略则继承所有） |
model |
否 | 模型别名（sonnet, opus, haiku）或'inherit' |
有效使用子代理
自动委托
Claude Code基于以下主动委托：
- 您请求中的任务描述
- 子代理配置中的
description字段 - 当前上下文和可用工具
为了鼓励主动使用，在描述中包含“use PROACTIVELY”或“MUST BE USED”。
显式调用
请求特定子代理：
> 使用test-runner子代理修复失败测试
> 让code-reviewer子代理查看我的最近更改
管理
使用/agents命令（推荐）
交互式菜单用于：
- 查看所有可用子代理
- 创建新子代理，带引导设置
- 编辑现有自定义子代理
- 删除自定义子代理
- 管理工具权限
直接文件管理
mkdir -p .claude/agents
cat > .claude/agents/test-runner.md << 'EOF'
---
name: test-runner
description: 主动使用以运行测试并修复失败
---
您是一个测试自动化专家。当您看到代码更改时，主动运行适当的测试。如果测试失败，分析失败并修复它们。
EOF
最佳实践
- 从Claude生成的代理开始，然后自定义
- 设计专注子代理，具有单一、明确责任
- 编写详细提示，带特定指令、示例、约束
- 限制工具访问到仅必要工具
- 版本控制项目子代理，用于团队协作
性能说明
- 上下文效率：代理保存主上下文，启用更长会话
- 延迟：子代理以干净状态开始，可能增加收集上下文的延迟