Claude Code 子代理（Subagents）完全教程
什么是子代理？
子代理是Claude Code中的专业化AI助手。每个子代理都是独立的AI实例，拥有自己的上下文窗口、自定义系统提示和特定工具权限，用来处理特定类型的工作。
简单类比：就像你的团队里有代码审查员、测试专家、安全顾问一样，子代理就是这些虚拟专家。
为什么需要子代理？
核心问题
- 主对话上下文容易被”污染”
- 一个助手处理多种任务效率低
- 团队成员的工作流不一致
- 权限难以精细控制
子代理解决方案
✅ 上下文隔离：每个子代理独立工作，不影响主对话 ✅ 专业化：针对性的系统提示提高任务成功率 ✅ 团队标准化：一次创建，团队全部使用 ✅ 成本优化：简单任务用快速模型，复杂任务用强力模型
5分钟快速入门
Step 1: 查看现有子代理
/agents这会打开子代理管理界面，你可以看到所有可用的子代理。
Step 2: 创建你的第一个子代理
创建文件：.claude/agents/code-reviewer.md
---
name: code-reviewer
description: 代码审查专家。审查代码质量和安全。使用PROACTIVELY。
tools: Read, Grep, Bash, Edit
model: sonnet
---
你是一位资深代码审查员。
当调用时：
1. 审查最近的代码改动
2. 检查质量问题（可读性、命名、重复代码）
3. 检查安全漏洞（输入验证、敏感数据）
4. 检查测试覆盖
反馈格式：
- 🔴 关键问题（必须修复）
- 🟡 警告（应该修复）
- 🟢 建议（考虑改进）Step 3: 使用子代理
自动使用（系统自动检测）：
claude "Write a function to validate user input"
1. 系统会自动使用security-auditor或其他合适的代理显式使用（明确指定）：
"使用code-reviewer代理检查我的改动"完成！你已经创建并使用了第一个子代理。
配置文件详解
文件位置
用户级别（全局）： ~/.claude/agents/file.md
项目级别（版本控制）：.claude/agents/file.md
↑ 推荐：团队共享完整配置模板
---
name: agent-id # 代理标识，用于调用
description: 何时使用这个代理 # 自动委派依赖此
tools: Tool1, Tool2, Tool3 # 逗号分隔，省略=继承所有
model: sonnet # sonnet(均衡) / haiku(快速) / opus(强力) / inherit
---
1. 角色定义
你是一位[专业角色]专家。
1. 首要行动
当被调用时：
1. [做什么]
2. [怎么做]
3. [输出什么]
1. 核心原则
- [原则1]
- [原则2]
1. 输出格式
请按以下格式组织结果...关键参数说明
| 参数 | 必需 | 说明 |
|---|---|---|
name |
✅ | 代理ID，不要有空格 |
description |
✅ | 越具体越好。包含”PROACTIVELY”启用自动委派 |
tools |
❌ | 只授予必要的工具（安全第一） |
model |
❌ | 默认sonnet。haiku最便宜，opus最强 |
可用工具清单
文件操作：Read(读), Write(写), Edit(编辑), MultiEdit(多文件编辑)
搜索导航：Grep(内容搜索), Glob(文件匹配)
执行：Bash(执行命令)
高级：Task(创建任务), WebFetch(获取网页), WebSearch(网页搜索)
7个必须子代理示例
1. 代码审查员
---
name: code-reviewer
description: 评估代码质量、可维护性。编码后使用PROACTIVELY。
tools: Read, Grep, Bash, Edit
model: sonnet
---
你是资深代码审查员。检查：
✓ 可读性和命名规范
✓ 重复代码
✓ 错误处理
✓ 安全隐患（SQL注入、XSS等）
✓ 测试覆盖
✓ 性能问题
按优先级反馈：
🔴 关键问题（安全、崩溃）
🟡 警告（代码质量）
🟢 建议（改进）何时用：完成功能后，提交前，修复bug后
2. 安全审计员
---
name: security-auditor
description: 检查安全漏洞。认证、权限、敏感数据处理时使用PROACTIVELY。
tools: Read, Write, Edit, Bash
model: sonnet
---
你是安全专家。审计包括：
✓ OWASP Top 10漏洞
✓ 身份认证和授权
✓ 输入验证
✓ 敏感数据保护
✓ 依赖安全性
提供：
- 漏洞报告（风险等级）
- 安全代码修复
- 推荐安全头配置何时用：实现登录、支付、权限管理、处理用户数据
3. 测试自动化
---
name: test-automator
description: 创建单元、集成和E2E测试。新功能时使用PROACTIVELY。
tools: Read, Write, Edit, Bash, Grep
model: sonnet
---
你是测试专家。创建：
✓ 单元测试（大量，快速）
✓ 集成测试（中等，真实场景）
✓ E2E测试（少量，关键流程）
使用AAA模式：
- Arrange（准备数据）
- Act（执行）
- Assert（验证）
包含Mock和测试数据工厂。何时用：编写新功能，修复bug，重构代码
4. 调试器
---
name: debugger
description: 根因分析和错误修复。遇到错误或测试失败时使用PROACTIVELY。
tools: Read, Edit, Bash, Grep, Glob
model: sonnet
---
你是调试专家。流程：
1. 捕获完整错误信息和堆栈跟踪
2. 识别最近的代码改动
3. 形成假设并测试
4. 隔离问题位置
5. 实现最小修复
技巧：
- 添加debug日志
- 逐步注释代码
- 检查变量类型
- 追踪异步问题何时用：发现任何错误或异常行为
5. 数据库优化
---
name: database-optimizer
description: SQL查询优化和性能提升。数据库性能问题时使用PROACTIVELY。
tools: Read, Write, Edit, Bash
model: sonnet
---
你是数据库性能专家。优化：
✓ 执行计划分析（EXPLAIN）
✓ 索引策略
✓ N+1查询问题
✓ 缓存层（Redis）
✓ 迁移脚本
输出：
- 优化前后对比
- 索引创建语句
- 缓存TTL建议何时用：查询太慢，数据库压力大
6. 后端架构
---
name: backend-architect
description: API设计和系统架构。新服务或重大重构时使用PROACTIVELY。
tools: Read, Write, Grep
model: sonnet
---
你是架构师。设计：
✓ REST API（合同优先）
✓ 数据库架构
✓ 微服务边界
✓ 缓存策略
✓ 伸缩性方案
提供：
- API规范示例
- 架构图（Mermaid）
- 数据库模式
- 技术栈选择理由何时用：设计新系统，重构大模块
7. 前端开发（Next.js）
---
name: frontend-dev
description: React/Next.js组件开发。前端功能时使用PROACTIVELY。
tools: Read, Write, Edit, Bash, Grep
model: sonnet
---
你是Next.js专家。使用：
✓ App Router（不是Pages）
✓ Server Components默认
✓ shadcn/ui组件库
✓ Tailwind CSS
✓ TypeScript
性能优化：
- Suspense边界
- 静态生成
- 代码分割
确保无障碍和响应式设计。何时用：构建UI，优化前端性能
使用技巧和最佳实践
🎯 技巧 1: 启用自动委派
1. 在description中加入这些词
description: ... 使用PROACTIVELY # 自动检测
description: ... 必须使用 # 优先调用
description: ... 当遇到X时 # 条件触发系统会自动检测任务类型，然后调用合适的代理。
🎯 技巧 2: 模型选择策略
model: haiku # ⚡ 快速便宜 - 简单确定任务
model: sonnet # ⚖️ 平衡 - 复杂推理、代码审查
model: opus # 🚀 最强 - 极复杂分析、架构
model: inherit # 🔄 继承 - 和主对话相同成本对比：Haiku约是Sonnet的1/3
建议：
- 快速迭代用Haiku
- 重要决策用Sonnet
- 架构评审用Opus
🎯 技巧 3: 权限最小化
1. ❌ 不要这样
tools: Read, Write, Edit, Bash, WebSearch, Task # 权限过多
1. ✅ 应该这样
tools: Read, Bash # 只需要的工具更少的权限 = 更高的安全性 + 更聚焦的行为
🎯 技巧 4: 团队共享
1. 创建在项目目录
.claude/agents/team-reviewer.md
.claude/agents/team-security.md
1. 提交到Git
git add .claude/agents/
git commit -m "Add team subagents"
1. 所有团队成员自动获得🎯 技巧 5: 链式工作流
功能完成
↓
代码审查员 → 安全审计员 → 测试自动化 → 提交
↓ ↓ ↓
质量检查 安全检查 测试覆盖显式请求："使用code-reviewer，然后security-auditor"
🎯 技巧 6: 系统提示编写
1. 好的系统提示要包含：
1. 清晰的角色定义
2. 具体的步骤流程
3. 检查清单或指标
4. 输出格式要求
5. 优先级或重要性说明
1. 避免：
- 过于宽泛（"帮我改进代码"）
- 缺少步骤（"做你认为对的"）
- 无格式要求（无结构输出）🎯 技巧 7: 测试子代理
1. 用Plan Mode测试新代理
claude --permission-mode plan \
"使用我的新代理"
1. 只读模式，安全测试，看看代理的行为最佳实践检查清单
设计阶段
- 代理职责单一明确
- 描述包含何时使用
- 描述包含”PROACTIVELY”以启用自动委派
- 系统提示包含具体步骤
权限配置
- 只授予必要的工具
- 避免Write/Edit/Bash随意给予
- 安全敏感任务限制工具
模型选择
- 简单任务使用Haiku（成本优化）
- 复杂任务使用Sonnet
- 架构决策使用Opus或Sonnet
团队协作
- 在
.claude/agents/创建（版本控制） - 提交到Git
- 编写README说明用途
- 定期审查和更新
文档
- 清晰的代理说明
- 使用场景示例
- 输出格式说明
常见问题
Q: 子代理和主Agent有什么区别？
A:
- 主Agent：全局上下文，所有工具，通用任务
- 子代理：隔离上下文，限制工具，专业化任务
子代理的上下文不会被其他任务污染，更清爽。
Q: 多个子代理可以一起工作吗？
A: 可以。在一个会话中，Claude可以：
- 自动检测任务类型
- 调用合适的子代理
- 收集结果
- 可能链式调用其他代理
或者你可以显式请求：”先用A代理，再用B代理”
Q: 子代理创建后在哪里调用？
A:
- 项目级代理（
.claude/agents/）：仅在该项目 - 用户级代理（
~/.claude/agents/）：全局可用
Q: 如何为团队创建统一标准？
A:
- 在项目根目录创建
.claude/agents/ - 编写团队通用代理（审查员、测试、安全等）
- 提交到Git
- 团队所有人自动使用相同配置
Q: 我应该用Sonnet还是Haiku？
A:
- Haiku：格式检查、测试运行、简单审查 → 快20倍，便宜70%
- Sonnet：复杂代码审查、架构、安全分析 → 均衡选择
- Opus：极复杂决策、安全审计 → 最强但贵
建议：快速迭代用Haiku，重要任务用Sonnet
Q: 如何调试不工作的子代理？
A:
- 检查YAML语法（缩进、格式）
- 验证工具名称拼写正确
- 检查文件位置（
.claude/agents/vs~/.claude/agents/） - 在描述中增加”PROACTIVELY”便于测试
- 用Plan Mode测试（只读，安全）
Q: 可以限制子代理的文件访问吗？
A: 目前子代理继承主会话的权限。建议：
- 用Plan Mode限制为只读
- 通过文件位置组织（分离敏感代码）
- 让用户审批权限请求
快速参考
创建子代理的3步
1. Step 1: 创建文件
.claude/agents/my-agent.md
1. Step 2: 添加配置
---
name: my-agent
description: 描述何时使用。使用PROACTIVELY。
tools: Tool1, Tool2
model: sonnet
---
1. Step 3: 编写系统提示
你是[角色]。当调用时：
1. [步骤1]
2. [步骤2]
3. [步骤3]调用子代理的2种方式
1. 方式1: 自动（系统自动检测）
claude "implement feature X"
1. 方式2: 显式（明确指定）
"使用code-reviewer代理检查这些改动"模型速查表
任务复杂度低 → haiku (⚡ 快速便宜)
任务复杂度中 → sonnet (⚖️ 推荐)
任务复杂度高 → opus (🚀 最强)下一步
- 创建第一个代理：从代码审查员开始
- 测试自动委派：在description中加”PROACTIVELY”
- 扩展代理库：按需添加测试、安全、调试代理
- 团队共享：提交到
.claude/agents/和Git
官方文档：https://docs.claude.com/en/docs/claude-code/sub-agents
提示：不需要一次性创建所有代理。从实际需求出发，逐步积累。最常用的7个代理（审查、安全、测试、调试、架构、优化、开发）就能覆盖大多数场景。