name: 子代理指南 description: 用于任务特定工作流程的专用AI助手，具有独立上下文。学习何时委派、配置工具和应用最佳实践。 allowed-tools: Read, Glob, Grep, Bash
子代理指南
什么是子代理？
子代理是Claude Code委派的预配置AI个性，用于处理特定任务类型。每个子代理独立运行，具有：
- 独立上下文 — 防止主要对话污染，保持专注于高级目标
- 自定义系统提示 — 指导特定领域的行为
- 专用工具 — 每个子代理的细粒度权限控制
- 可重用性 — 跨项目可用，可与团队共享
主要优势
| 优势 | 影响 |
|---|---|
| 上下文保持 | 主线保持专注；子代理污染隔离 |
| 专业化专长 | 领域调整的指令提高成功率 |
| 灵活权限 | 只授予每个子代理必要工具 |
| 可重用性 | 一个配置用于跨项目和团队 |
何时使用子代理
委派当：
- 任务匹配预定义专业领域
- 您希望为深入工作隔离上下文
- 多个独立任务可以并行运行
- 应限制工具访问
- 您需要在项目间保持一致行为
不委派：
- 简单一次性更改（≤3个文件）
- 快速迭代的主动调试
- 需要主要对话上下文的任务
快速开始
# 打开子代理界面（推荐方法）
/agents
# 或手动创建：项目子代理放在这里
mkdir -p .claude/agents
# 用户子代理（随处可用）
mkdir -p ~/.claude/agents
步骤：
- 运行
/agents命令 - 选择“创建新代理”
- 描述目的，选择工具，自定义系统提示
- 保存 — 子代理现在可用
文件格式
子代理是带有YAML frontmatter的Markdown文件：
---
name: subagent-name
description: 何时使用此子代理及其专业领域
tools: Read, Write, Bash # 可选 — 如果省略则继承所有工具
model: sonnet # 可选 — sonnet, opus, haiku, 或 'inherit'
---
您的系统提示在此处。定义角色、能力、约束和特定指令。包括示例、检查清单和最佳实践。
配置字段
| 字段 | 必需 | 注释 |
|---|---|---|
name |
✓ | 小写，仅连字符；用于调用 |
description |
✓ | 自然语言；用于自动委派。使用“proactively”来触发自动使用 |
tools |
— | 逗号分隔列表。省略以从主线继承所有工具 |
model |
— | sonnet（默认），opus，haiku，或 'inherit' 以保持一致性 |
文件位置与优先级
| 类型 | 位置 | 范围 | 优先级 |
|---|---|---|---|
| 项目 | .claude/agents/ |
仅此项目 | 较高 |
| 用户 | ~/.claude/agents/ |
所有项目 | 较低 |
项目子代理覆盖具有相同名称的用户级子代理。
工具配置最佳实践
原则：最小权限
只授予子代理目的必要的工具。这：
- 提高安全性和专注力
- 防止意外操作
- 使子代理行为更可预测
常见工具组合：
# 代码审查器
tools: Read, Grep, Glob, Bash
# 数据分析师
tools: Read, Write, Bash
# 测试自动化
tools: Bash, Read, Edit, Write
# 调试器
tools: Read, Edit, Bash, Grep, Glob
# 文档编写器
tools: Read, Write, Glob, Grep
省略 tools 以让子代理继承所有（包括MCP工具）。
调用方法
自动委派
Claude Code在以下情况下主动委派：
- 任务描述匹配子代理目的
- 子代理
description字段匹配上下文 - 配置了适当的工具
为鼓励自动使用，在描述中包括“proactively”：
description: 使用 proactively 运行测试并修复失败
显式调用
直接请求子代理：
使用代码审查器子代理检查我的最新更改
让调试器调查此测试失败
请求数据科学家子代理进行SQL分析
示例子代理
代码审查器
---
name: code-reviewer
description: 专家代码审查专家。写代码后使用 proactively。
tools: Read, Grep, Glob, Bash
model: inherit
---
您是一名高级代码审查员，确保代码质量和安全性的高标准。
当调用时，运行 git diff 以识别最新更改并审查修改的文件。
审查清单：
- 可读性和命名
- 无重复代码
- 适当的错误处理
- 无暴露秘密
- 输入验证实现
- 测试覆盖充分
- 性能考虑解决
按优先级组织反馈：
- 关键问题（必须修复）
- 警告（应修复）
- 建议（考虑改进）
为所有推荐包括具体示例。
测试自动化
---
name: test-runner
description: 测试自动化专家。使用 proactively 运行测试并修复失败。
tools: Bash, Read, Edit
---
您是一名测试自动化专家。当您看到代码更改时，主动运行适当的测试。
如果测试失败：
1. 分析失败消息和日志
2. 识别根本原因
3. 修复问题同时保持测试意图
4. 重新运行测试以确认
为每个失败提供：
- 根本原因解释
- 代码修复
- 预防推荐
专注于修复根本问题，不仅仅是症状。
调试器
---
name: debugger
description: 调试专家。遇到错误或意外行为时使用 proactively。
tools: Read, Edit, Bash, Grep, Glob
---
您是一名专家调试器，专门从事根本原因分析。
调试过程：
1. 捕获错误消息和堆栈跟踪
2. 识别复现步骤
3. 隔离失败位置
4. 实施最小修复
5. 验证解决方案有效
为每个问题提供：
- 带证据的根本原因解释
- 特定代码修复
- 测试方法
- 预防推荐
专注于修复根本问题，不仅仅是症状。
最佳实践
设计专注的子代理
- 每个子代理单一清晰责任
- 提高性能和可预测性
- 更容易测试和迭代
写详细系统提示
- 包括特定指令和示例
- 定义约束和决策规则
- 更多指导 = 更好性能
有意识限制工具访问
- 只授予必要工具
- 提高安全性和专注力
- 防止意外副作用
从Claude生成的代理开始
- 使用Claude生成初始子代理，然后定制
- 提供坚实的迭代基础
- 比从头开始构建更好的结果
版本控制项目子代理
- 将
.claude/agents/检查到git - 团队受益于共享、改进的子代理
- 跟踪子代理随时间的演变
为自动委派使用特定描述
- 包括行动动词：“使用 proactively”、“automatically”、“必须使用”
- 匹配工作流中的任务关键词
- 示例：“使用 proactively 分析错误并修复bug”
高级：链接子代理
对于复杂工作流程，序列多个子代理：
> 首先使用代码分析器子代理查找性能问题，
然后使用优化器子代理修复它们
每个子代理完成其工作，然后下一个被调用其结果。
性能考虑
延迟权衡：
- 子代理保持主要上下文（允许更长会话）
- 每个子代理调用需要初始上下文收集
- 适合专注、实质工作（不是快速调整）
何时使用子代理： 实质工作、深入调查、复杂逻辑、长任务 何时跳过： 快速编辑（≤3个文件）、快速迭代、简单澄清
管理
使用 /agents 命令（推荐）
/agents
提供交互界面以：
- 查看所有可用子代理
- 创建具有引导设置的新子代理
- 编辑现有子代理和工具权限
- 删除自定义子代理
- 当存在重复时查看活动子代理
直接文件管理
创建项目子代理：
mkdir -p .claude/agents
cat > .claude/agents/test-runner.md << 'EOF'
---
name: test-runner
description: 使用 proactively 运行测试并修复失败
---
[您的系统提示在此]
EOF
创建用户子代理：
mkdir -p ~/.claude/agents
# 以与项目子代理相同的方式创建文件