Sub-Agents 核心概念与应用价值
核心问题：上下文污染
与 Claude 协作常见痛点：
- 跑测 试 → 500 行日志
- 搜索代码 → 200 行 grep 结果
- 分析错误 → 一堆中间推理过程
这些信息对"当下执行"必要，但对"后续决策"是噪声。主对话线性追加，不会自动过期。
解决方案：子代理
子代理 = 专职小助手，带着自己的规则、工具权限、上下文窗口，完成某一类任务后只把"结果摘要"带回来
可以理解为是 把一个大脑拆成多个岗位角色，每个岗位只做一件事，并且有明确的权限边界。
核心价值（三件事）
| 价值 | 解决的问题 | 说明 |
|---|---|---|
| 隔离 | 上下文污染 | 执行完即丢弃，只把结论带回来 |
| 约束 | 行为不可控 | 工具权限边界，物理上做不到 |
| 复用 | 经验无法沉淀 | 放进版本控制，团队共享 |
隔离
是子代理最重要的价值。
主对话的上下文：
┌─────────────────────────────────────────┐
│ 用户：帮我分析一下这个 bug │
│ Claude：好的，让我看看... │
│ [子代理去执行，产生 500 行日志] │
│ [子代理返回：发现 3 个相关文件] │
│ Claude：我发现问题在这三个文件... │
└─────────────────────────────────────────┘
子代理的上下文（独立的，执行完就释放）：
┌─────────────────────────────────────────┐
│ 任务：查找 bug 相关 文件 │
│ [搜索输出 500 行日志] │
│ [分析过程...] │
│ 结论：3 个相关文件 │
└─────────────────────────────────────────┘
约束
子代理可以有精确的工具权限控制。
# 只读型子代理（代码审查）
tools: Read, Grep, Glob
# 它只能看，不能改任何东西
# 开发型子代理（bug 修复）
tools: Read, Write, Edit, Bash
# 它可以读写文件和执行命令
# 研究型子代理（技术调研）
tools: Read, WebFetch, WebSearch
# 它可以读本地文件和搜索网络
如果没有权限边界，Claude 可能在审查过程中顺手帮你“修”了一些它认为有问题的代码——这不是你想要的行为。有了子代理，你就可以创建一个 code-reviewer 角色，明确规定它只有 Read, Grep, Glob 权限。这样它再怎么想“插手”，也改不了任何东西。
复用、代理被定义成文件、放进版本控制后，好的使用方式就从一次性对话，变成了可共享、可迭代的工程资产。
子代理配置文件
---
name: code-reviewer
description: Review code for security issues and best practices.
tools: Read, Grep, Glob
model: sonnet
permissionMode: readOnly
skills:
- security-rules
---
# 系统提示词
你是一个代码审查专家...
关键字段
| 字段 | 必填 | 说明 |
|---|---|---|
name | ✅ | 角色标识 |
description | ✅ | 决定何时被调用（最重要设计点） |
tools | ❌ | 白名单：只能用这些工具 |
disallowedTools | ❌ | 黑名单：排除这些工具 |
model | ❌ | 模型选择 |
permissionMode | ❌ | 权限模式：readOnly / plan / auto |
skills | ❌ | 预加载的 Skill |
hooks | ❌ | 生命周期 Hook |
工具组合示例
# 只读型（审计/检查）
tools: [Read, Grep, Glob]
# 研究型（信息收集）
tools: [Read, Grep, Glob, WebFetch, WebSearch]
# 开发型（读写改）
tools: [Read, Write, Edit, Bash, Glob, Grep]
存放位置与优先级
项目级: ./claude/agents/*.md # 仅当前项目可用
用户级: ~/.claude/agents/*.md # 所有项目可用
优先级：项目级 > 用户级
什么时候用子代理？
✅ 适合用：
- 高噪声输出任务（测试、日志、搜索）
- 权限边界必须明确的任务（只读审查）
- 可以并行展开的研究型任务
- 可以拆成清晰阶段的流水线任务
❌ 不适合用：
- 需要频繁来回确认需求的任务
- 各阶段高度耦合的任务
- 非常简单的小任务
关键约束
子代理不能生成子代理（防止无限嵌套）
所有编排必须由主对话完成，调度中心只有一个：主对话本身
内置子代理
| 子代理 | 用途 | 模式 |
|---|---|---|
| Explore | 代码搜索 | quick / medium / very thorough |
| Plan | 规划模式 | 收集上下文，生成实施路径 |
| General-purpose | 全能型 | 处理复杂多步骤任务 |
创建子代理的三种方式
- 交互式：
/agents向导 - 手写配置：直接创建
.claude/agents/xxx.md - CLI 临时：
--agents参数（仅当前会话有效）
运行模式
- 前台：等待执行完成
- 后台：
Ctrl+B切换，适合长时间任务 - 恢复：
Resume继续之前的子代理，保留完整上下文
CLAUDE.md 继承优先级
子代理启动时加载：
- 全局
~/.claude/CLAUDE.md - 项目
./CLAUDE.md - 代理定义文件
优先级：代理定义文件 > 项目 CLAUDE.md > 全局 CLAUDE.md
最佳实践
- description 是最关键的设计点：决定何时被调用
- 遵循最小权限原则：能用 Read 就不给 Edit
- 子代理 Token 消耗增加 30-200%，但可用便宜模型省钱
本讲小结
子代理让 Claude "记得更少，但记得对"
- 隔离 → 主对话保持清洁
- 约束 → 工具权限边界
- 复用 → 可版本化的配置
- 并行 → 复杂任务同时推进
思考题
- 如果要设计一个"数据库查询分析器"子代理，你会配置哪些工具？
- 子代理配置放项目级 vs 用户级，各有什么优缺点？