共计 7891 个字符，预计需要花费 20 分钟才能阅读完成。
目录
核心概念
什么是子代理？
子代理（Subagents） 是 Claude Code 中预配置的专业 AI 助手，它们可以被主对话委派去处理特定类型的任务。
核心特点：
┌─────────────────────────────────────────┐
│ 主对话（Main Agent）│
│ • 保持高层对话 │
│ • 协调任务分配 │
│ • 整合结果 │
└───────────┬─────────────────────────────┘
│
│ 委派任务
│
┌───────┴────────┬──────────────┐
│ │ │
┌───▼────┐ ┌────▼─────┐ ┌───▼────┐
│代码审查 │ │ 调试器 │ │数据分析 │
│子代理 │ │ 子代理 │ │子代理 │
│ │ │ │ │ │
│独立上下文│ │独立上下文 │ │独立上下文│
│专用工具 │ │专用工具 │ │专用工具 │
└────────┘ └──────────┘ └────────┘关键特性
| 特性 | 说明 | 好处 |
|---|---|---|
| 独立上下文 | 每个子代理有自己的对话窗口 | 防止主对话被细节污染 |
| 专业化 | 针对特定领域定制系统提示 | 提高任务成功率 |
| 工具限制 | 可为每个子代理指定可用工具 | 增强安全性和专注度 |
| 可重用 | 跨项目使用，团队共享 | 标准化工作流程 |
| 模型选择 | 可为不同子代理选择不同模型 | 优化性能和成本 |
为什么需要子代理
问题场景
场景 1：上下文污染
用户: 帮我审查代码
Claude: [执行 30 次文件搜索和读取操作]
[主对话被大量代码细节填满]
用户: 现在帮我写文档
Claude: [因为上下文充满代码审查细节而困惑]场景 2：专业化不足
用户: 调试这个复杂的并发问题
Claude: [使用通用方法，效果不佳]
# 缺少专门的调试策略和检查清单 使用子代理后
解决方案 1：保持上下文清晰
用户: 帮我审查代码
Claude: [委派给 code-reviewer 子代理]
[子代理在独立上下文中工作]
[返回简洁的审查结果]
用户: 现在帮我写文档
Claude: [主对话保持清晰，轻松切换任务]解决方案 2：专业化处理
用户: 调试这个并发问题
Claude: [委派给 debugger 子代理]
[子代理使用专门的调试清单]
[系统化地分析和解决问题]快速上手
步骤 1：创建第一个子代理
方式 A：使用交互式命令（推荐）
# 启动子代理管理界面
/agents
# 界面操作流程：# 1. 选择 "Create New Agent"
# 2. 选择范围（项目级或用户级）# 3. 让 Claude 帮你生成，然后自定义
# 4. 保存 方式 B：手动创建文件
# 创建项目级子代理
mkdir -p .claude/agents
cat > .claude/agents/test-runner.md << 'EOF'
---
name: test-runner
description: 测试自动化专家。在代码更改后主动运行测试。发现测试失败时，分析并修复。tools: Read, Edit, Bash, Grep
model: sonnet
---
你是测试自动化专家。当看到代码更改时：1. 立即识别相关测试
2. 运行适当的测试套件
3. 如果测试失败：- 分析失败原因
- 保持原始测试意图
- 修复代码或测试
- 验证修复
关注点：- 测试覆盖率
- 边界情况
- 回归预防
EOF手动创建的子代理配置文件 claudecode 没有热加载机制，需要重启
claude --continue # 这会继续之前的会话，不会丢失上下文 步骤 2：使用子代理
自动委派（推荐）
# Claude 会自动识别需要使用哪个子代理
claude
> 添加分类功能模块然后帮我测试下代码
# Claude 自动委派给 test-runner 子代理
# 子代理运行测试并报告结果 显式调用
使用中发现，显示调用命中率比较高，如果你的输入或者子代里描述不明确，则不会触发代理运行。
claude
> 使用 test-runner 子代理来运行所有单元测试
> 让 code-reviewer 子代理审查我的最新提交 配置详解
配置方式对比
| 方式 | 优先级 | 适用场景 | 持久性 |
|---|---|---|---|
CLI --agents |
中 | 临时测试、脚本自动化 | 会话级 |
项目 .claude/agents/ |
高 | 项目特定需求 | 永久 |
用户 ~/.claude/agents/ |
低 | 个人跨项目使用 | 永久 |
| 插件提供 | 中 | 复用第三方功能 | 取决于插件 |
文件结构详解
---
# ============ 必需字段 ============
name: my-agent # 唯一标识符（小写字母和连字符）description: 何时使用这个代理的描述 # 影响自动委派
# ============ 可选字段 ============
tools: Read, Edit, Bash # 可用工具（省略则继承所有工具）model: sonnet # 模型选择：sonnet/opus/haiku/inherit
permissionMode: default # 权限模式：default/acceptEdits/bypassPermissions/plan/ignore
skills: skill1, skill2 # 自动加载的技能
---
<!-- 系统提示：定义代理的行为 -->
你是一个专业的代码审查员...
## 审查流程
1. 检查代码质量
2. 验证安全性
3. 提供反馈
## 关注点
- 可读性
- 性能
- 安全性 字段详解
1. name（名称）
# ✅ 正确
name: code-reviewer
name: test-runner
name: api-debugger
# ❌ 错误
name: Code Reviewer # 不要用空格
name: test_runner # 用连字符而不是下划线
name: API-Debugger # 不要用大写 2. description（描述）
# 🎯 好的描述（明确且可执行）description: 代码审查专家。在代码修改后主动使用。检查质量、安全性和最佳实践。# 💡 触发词提示
description: 调试专家。遇到错误或测试失败时必须使用。分析根因并提供修复。# ❌ 差的描述（模糊）description: 帮助处理代码问题 关键词建议：
- 使用 "主动使用"（Use proactively）
- 使用 "必须使用"（MUST BE USED）
- 明确触发场景
3. tools（工具）
# 完全访问（默认）# tools: [省略此字段]
# 只读访问
tools: Read, Grep, Glob, Bash
# 开发相关
tools: Read, Edit, Write, Bash
# 数据分析
tools: Bash, Read, Write
# 包含 MCP 工具
tools: Read, mcp_search, mcp_analyze可用工具列表：
Read- 读取文件Edit- 编辑文件Write- 创建新文件Bash- 执行命令Grep- 内容搜索Glob- 文件模式匹配- MCP 服务器工具（如果已配置）
4. model（模型）
# 使用别名
model: sonnet # Claude Sonnet（平衡性能）model: opus # Claude Opus（最强能力）model: haiku # Claude Haiku（最快速度）# 继承主对话模型
model: inherit # 与主对话保持一致
# 省略则使用默认子代理模型
# [未设置] -> 使用配置的默认值（通常是 sonnet）| 选择指南： | 任务类型 | 推荐模型 | 原因 |
|---|---|---|---|
| 代码审查 | sonnet 或 inherit |
需要理解力和一致性 | |
| 快速搜索 | haiku |
速度优先 | |
| 复杂调试 | sonnet |
需要深度分析 | |
| 数据分析 | sonnet |
需要处理复杂查询 |
5. permissionMode（权限模式）
# 默认模式（询问权限）permissionMode: default
# 自动接受编辑
permissionMode: acceptEdits
# 跳过所有权限（危险！）permissionMode: bypassPermissions
# 仅规划模式
permissionMode: plan
# 忽略权限提示
permissionMode: ignore6.Skill (技能预加载)
skills: skill1, skill2 功能 ：自动加载 .claude/skills/ 下的可复用指令片段
文件结构：
.claude/
├── agents/
│ └── code-reviewer.md
└── skills/
├── python-best-practices.md # ← skill1
└── security-checklist.md # ← skill2技能文件示例：
<!-- .claude/skills/python-best-practices.md -->
---
name: python-best-practices
---
检查 Python 代码时，必须验证：- 类型注解完整性
- 异常处理覆盖
- 文档字符串规范
- 单元测试覆盖率 > 80%Agent 引用：
# .claude/agents/python-reviewer.md
---
name: python-reviewer
tools: Read, Search
skills: python-best-practices, security-checklist # 自动加载
---
审查 Python 代码的安全性和代码质量 效果 ：Agent 启动时会自动将这些技能的内容注入到系统提示词中
CLI 动态配置
# 单个子代理
claude --agents '{"reviewer": {"description":" 代码审查专家 ","prompt":" 你是资深审查员...","tools": ["Read","Grep"],"model":"sonnet"
}
}'
# 多个子代理
claude --agents '{"reviewer": {...},"debugger": {...},"optimizer": {...}
}'
# 与查询结合
claude --agents '{...}' -p "审查最近的更改"
- 立即可用
- 不写入文件
- 只存在内存中
- 会话结束就消失
实战示例
示例 1：代码审查子代理
---
name: code-reviewer
description: 专家级代码审查员。代码修改后主动使用。检查质量、安全性和可维护性。tools: Read, Grep, Glob, Bash
model: inherit
---
你是一位资深代码审查员，确保高标准的代码质量和安全性。## 被调用时的流程
1. 运行 `git diff` 查看最近的更改
2. 聚焦于修改的文件
3. 立即开始审查
## 审查清单
### 🔴 关键问题（必须修复）- [ ] 暴露的密钥或 API 凭证
- [ ] SQL 注入或 XSS 漏洞
- [ ] 未处理的错误可能导致崩溃
- [ ] 内存泄漏或资源泄漏
### 🟡 警告（应该修复）- [ ] 重复的代码
- [ ] 缺少输入验证
- [ ] 不当的错误处理
- [ ] 性能问题
### 🟢 建议（考虑改进）- [ ] 命名可以更清晰
- [ ] 可以添加注释
- [ ] 可以简化逻辑
- [ ] 可以改进测试覆盖率
## 输出格式
```markdown
## 代码审查结果
### 关键问题 🔴
1. **[文件: 行号]** 问题描述
- 影响：...
- 修复建议：```language
// 修复代码
### 警告 🟡
...
### 建议 🟢
...
### 总体评估
- 代码质量：⭐⭐⭐⭐
- 安全性：⭐⭐⭐⭐⭐
- 可维护性：⭐⭐⭐
## 审查原则
1. ** 安全第一 **：任何安全问题都是关键问题
2. ** 可读性优于简洁性 **：清晰比聪明更重要
3. ** 具体反馈 **：提供可执行的建议和代码示例
4. ** 优先级明确 **：区分必须修复和可选改进 内置子代理
1. 通用子代理（General-Purpose）
特性：
- 模型：Sonnet
- 工具：完全访问
- 能力：读写文件、执行命令、多步骤操作
使用场景：
# 复杂的多步骤任务
> 找到所有处理认证的地方，并更新为新的 token 格式
# 需要探索和修改的任务
> 重构数据库查询层，提高性能 工作流程：
1. 搜索相关代码 → 2. 分析多个文件
↓ ↓
3. 制定策略 ← 4. 执行修改
↓
5. 返回详细报告 2. 计划子代理（Plan）
特性：
- 模型：Sonnet
- 工具：Read, Glob, Grep, Bash（只读）
- 模式：仅在计划模式下使用
使用场景：
# 在计划模式下研究代码库
[计划模式] > 帮我重构认证模块
# Claude 自动使用计划子代理研究代码库
# 然后提供详细的重构计划 为什么需要：
- 防止代理无限嵌套
- 在计划模式下仍能研究代码库
- 收集上下文后返回计划
3. 探索子代理（Explore）
特性：
- 模型：Haiku（最快）
- 工具：Glob, Grep, Read, Bash（只读命令）
- 模式：严格只读
| 彻底程度级别： | 级别 | 搜索范围 | 使用场景 |
|---|---|---|---|
| Quick | 基本搜索 | 简单查找 | |
| Medium | 适度探索 | 一般分析 | |
| Very thorough | 全面分析 | 复杂查找 |
使用场景：
# 快速查找
> 错误处理在哪里？[Explore: Quick]
# 结构分析
> 代码库结构是什么样的？[Explore: Quick]
# 深度搜索
> 找到所有使用旧 API 的地方
[Explore: Very thorough]优势：
- 🚀 快速响应（Haiku 模型）
- 🧹 不污染主对话
- 📍 返回绝对文件路径
- 🔍 高效的代码库探索
最佳实践
1. 设计原则
✅ 单一职责
# 好的设计
name: test-runner # 只负责测试
name: code-reviewer # 只负责审查
name: performance-analyzer # 只负责性能
# 差的设计
name: do-everything # 试图做所有事情 ✅ 详细的系统提示
# 好的提示
---
你是测试自动化专家。## 工作流程
1. 识别被修改的模块
2. 运行相关测试套件
3. 分析失败原因
4. 修复代码或测试
## 关注点
- 测试覆盖率 > 80%
- 边界情况处理
- 错误消息清晰
## 输出格式
[具体的格式说明]
---
# 差的提示
你是测试专家。帮助运行测试。✅ 最小权限原则
# 代码审查（只读）tools: Read, Grep, Glob, Bash
# 调试器（读写）tools: Read, Edit, Bash
# 测试运行器（完全访问）tools: Read, Edit, Write, Bash2. 命名规范
# ✅ 好的命名
code-reviewer
test-runner
api-debugger
sql-optimizer
security-scanner
# ❌ 差的命名
reviewer # 太泛化
test_runner # 使用下划线
Code-Reviewer # 使用大写
review-code # 动词 - 名词顺序 3. 版本控制
# 项目级子代理应该进入版本控制
.claude/
agents/
code-reviewer.md # ✅ 提交到 git
test-runner.md # ✅ 提交到 git
team-standards.md # ✅ 提交到 git
# .gitignore 配置
# ❌ 不要忽略 .claude/agents/4. 团队协作
共享配置：
# 1. 创建团队标准子代理
.claude/agents/company-code-review.md
.claude/agents/company-test-standards.md
# 2. 文档化使用方法
docs/claude-subagents.md
# 3. 在 PR 模板中提及
## 检查清单
- [ ] 使用 code-reviewer 子代理审查
- [] 使用 test-runner 子代理验证 5. 迭代改进
## 改进循环
1. ** 创建初始版本 **
- 让 Claude 生成基础版本
- 测试基本功能
2. ** 收集反馈 **
- 哪些工作良好？- 哪些需要改进？- 缺少什么功能？3. ** 优化提示 **
- 添加具体示例
- 明确输出格式
- 改进指令清晰度
4. ** 调整工具集 **
- 添加必需工具
- 移除不用的工具
5. ** 重复测试 **
- 在真实场景中使用
- 持续改进 高级技巧
1. 链式调用
# 串行工作流
> 首先使用 code-analyzer 子代理找出性能问题，然后使用 optimizer 子代理修复它们
# 流程：代码分析 → 性能问题列表 → 优化修复 → 验证结果 2. 可恢复子代理
# 初次调用
> 使用 code-analyzer 子代理开始审查认证模块
[代理完成初始分析，返回 agentId: "abc123"]
# 恢复继续
> 恢复代理 abc123，现在分析授权逻辑
[代理继续，保持完整上下文]使用场景：
- 长期研究任务
- 迭代优化工作
- 多步骤工作流
编程用法：
{
"description": "继续分析",
"prompt": "现在检查错误处理模式",
"subagent_type": "code-analyzer",
"resume": "abc123"
}3. 动态子代理选择
优化描述字段：
# 🎯 高度特定的触发
description: |
安全审查专家。必须用于：- 认证 / 授权代码
- 密码处理
- API 密钥管理
- 数据加密
主动在这些场景使用！# 📋 清单式触发
description: |
前端性能专家。使用当：✓ 页面加载缓慢
✓ 渲染性能问题
✓ 需要优化打包大小
✓ 需要分析 Core Web Vitals4. 条件化工具访问
# 根据安全级别配置工具
---
name: production-deployer
description: 生产部署专家
tools: Read, Bash # 不允许 Edit（生产环境）permissionMode: plan # 只能计划，不能执行
---5. 技能组合
---
name: fullstack-reviewer
description: 全栈代码审查
tools: Read, Grep, Glob, Bash
skills: frontend-patterns, backend-security, database-best-practices
---
# 技能会自动加载到子代理上下文中 常见问题
Q1: 子代理会增加延迟吗？
A: 是的，子代理从干净的上下文开始，需要时间收集必要的上下文。
权衡：
- ➕ 保持主对话清晰
- ➕ 专业化处理提高质量
- ➖ 初始启动有延迟
优化策略：
- 为快速任务使用
haiku模型 - 预先提供必要的文件路径
- 使用可恢复子代理继续长任务
Q2: 何时使用子代理 vs 主对话？
| 使用子代理 | 使用主对话 |
|---|---|
| 需要专业化处理 | 简单快速的任务 |
| 会产生大量输出 | 对话式交互 |
| 需要独立上下文 | 需要记住之前的对话 |
| 可重复的工作流 | 一次性的探索 |
Q3: 子代理可以嵌套吗？
A: 不可以。子代理不能调用其他子代理，这是为了防止无限嵌套。
设计意图：
主对话
├─ 子代理 A（✅ 可以）├─ 子代理 B（✅ 可以）└─ 子代理 C
└─ 子代理 D（❌ 不允许）Q4: 如何调试子代理？
# 1. 启用详细模式
claude --verbose
# 2. 检查子代理文件
cat .claude/agents/my-agent.md
# 3. 使用 /agents 命令检查
/agents
# 选择 "View Agent Details"
# 4. 显式调用测试
> 使用 my-agent 子代理处理这个简单任务 Q5: 子代理能访问 MCP 工具吗？
A: 可以！
# 方式 1：继承所有工具（包括 MCP）# tools: [省略字段]
# 方式 2：显式指定 MCP 工具
tools: Read, mcp_search, mcp_analyzeQ6: 如何共享子代理？
方式 1：版本控制
# 提交到 git
git add .claude/agents/
git commit -m "添加团队子代理"
git push方式 2：导出配置
# 复制文件
cp ~/.claude/agents/my-agent.md ./shared/
# 或使用 CLI 格式分享
claude --agents '{"name": {...}}' # 复制此命令 Q7: 子代理的成本如何？
成本因素：
- 使用的模型（Haiku < Sonnet < Opus）
- 上下文长度
- 执行时长
优化成本：
# 对于简单任务使用 Haiku
model: haiku
# 限制工具访问
tools: Read, Grep # 只读，减少操作
# 使用 inherit 与主对话保持一致
model: inherit资源链接
官方文档
总结
核心要点
- 子代理 = 专业化 AI 助手
- 独立上下文
- 定制化行为
- 工具限制
- 何时使用
- 任务需要专业化
- 会产生大量输出
- 需要可重复工作流
- 最佳实践
- 单一职责
- 详细提示
- 最小权限
- 版本控制
- 高级特性
- 链式调用
- 可恢复执行
- 动态选择
- MCP 集成
正文完
发表至： ai
2025-12-23
