第 16 章 Sub-agents——分工协作
...
❓ 引导问题：如何让多个 Claude 实例并行工作？子代理与多代理有什么区别？如何创建和管理自定义子代理？
📖 16.1 什么是子代理
Sub-agent（子代理）是运行在独立上下文窗口中的专用 AI 代理，拥有独立的系统提示、模型、工具权限和权限模式。当 Claude 判断任务符合某个子代理的描述时，自动委托给它，完成后返回结果。
核心价值：隔离 + 专业化：
- 保护主对话上下文：大量探索、日志分析放到子代理中，主对话只接收结论摘要。三子代理并行分析 5 万行项目约 45 秒，串行需 3 分钟
- 强制执行约束：通过工具白名单/黑名单限制能力，如只读分析、禁止危险命令
- 行为专业化：为特定领域（代码审查、调试、数据分析）设计专用 AI
- 控制成本：简单任务用 Haiku，复杂分析用 Sonnet
📖 16.2 子代理 vs 多代理
| 对比项 | 子代理（Subagent） | 多代理（Multi-agent） |
|---|---|---|
| 运行范围 | 单个会话内启动，处理子任务后返回 | 多个会话并行/串行运行，通常由编排器管理 |
| 上下文 | 独立窗口，与主对话隔离 | 各会话上下文完全独立 |
| 嵌套 | 不能再创建子代理（需嵌套时用 Skills） | 可由编排器协调多层级任务 |
| 适用场景 | 聚焦子任务、大量输出隔离、专业分析 | 全功能开发流水线（设计→实现→测试→发布） |
📖 16.3 内置子代理
| 代理 | 说明 | 特点 |
|---|---|---|
| Explore | 只读搜索与分析代码库 | Haiku 模型，只开放只读工具，支持 quick/medium/very thorough 深度 |
| Plan | 在计划模式下收集代码库信息 | 只读工具，安全收集规划所需信息 |
| General-purpose | 复杂多步骤任务 | 开放全部工具，继承主对话模型，适合"看+改+推理" |
| Bash | 在独立上下文运行 Shell 命令 | — |
| statusline-setup | 配置终端状态栏 | — |
| Claude Code Guide | 解答 Claude Code 使用问题 | — |
📖 16.4 创建自定义子代理
步骤
1：执行 /agents 打开管理界面
2：选择 Create new agent → Project（.claude/agents/，团队共享）或 User（~/.claude/agents/，全局）
3：用自然语言描述代理职责，Claude 自动生成系统提示：
一个代码改进代理，扫描项目文件，针对可读性、性能和最佳实践提出建议，并给出改进示例。
4：配置工具权限和模型——只读代理勾选 Read/Grep/Glob；需要修改代码则保留 Edit/Write
5（可选）：选择记忆范围——User（跨项目积累经验）/ Project / None
配置文件结构
---
name: code-reviewer # 必填：唯一标识，小写字母+连字符
description: Reviews code for quality, best practices, and security issues.
Invoke when the user asks to review, audit, or check code quality.
# 必填：决定 Claude 何时自动调用，务必写清使用场景
tools: Read, Grep, Glob # 工具白名单
model: sonnet # haiku / sonnet / opus / inherit
permissionMode: default # 权限模式
memory: project # user / project / local
background: false # true = 始终后台运行
isolation: worktree # 可选：在临时 worktree 中隔离运行
---
You are a senior code reviewer.
Analyze code and provide actionable feedback organized by severity: Critical / Major / Minor.
Update your agent memory with recurring patterns, conventions, and known issues.
关键字段
| 字段 | 必填 | 说明 |
|---|---|---|
name | 必填 | 唯一标识，调用时使用 |
description | 必填 | 最重要字段——Claude 据此判断是否自动调用 |
tools | 可选 | 白名单，设置后 MCP 工具也被排除 |
disallowedTools | 可选 | 黑名单，继承全部工具但排除列出工具（保留 MCP） |
model | 可选 | haiku/sonnet/opus/完整 ID/inherit（默认） |
permissionMode | 可选 | default / acceptEdits / dontAsk / bypassPermissions / plan |
memory | 可选 | user（~/.claude/agent-memory/）/ project / local |
background | 可选 | true 始终后台运行，不阻塞主对话 |
isolation | 可选 | worktree 在临时 git worktree 中隔离运行 |
tools 与 disallowedTools 区别
| 配置 | 行为 | 典型场景 |
|---|---|---|
| 两者均不设 | 继承主对话全部工具，含 MCP | 通用代理 |
仅设 tools | 只能用白名单，MCP 被排除 | 严格只读分析 |
仅设 disallowedTools | 继承全部但排除黑名单，MCP 保留 | 保留 MCP 但禁止写操作 |
| 两者同时设 | 先应用 disallowedTools，再从剩余按 tools 筛选 | 精细控制 |
📖 16.5 三种作用范围
| 存放位置 | 作用范围 | 优先级 |
|---|---|---|
CLI --agents 标志 | 仅当前会话 | 最高 |
.claude/agents/ | 当前项目（可提交 Git 团队共享） | 高 |
~/.claude/agents/ | 所有项目（全局） | 中 |
| 插件 agents | 插件作用域 | 最低 |
📖 16.6 前台 vs 后台运行
| 方式 | 行为 | 限制 |
|---|---|---|
| 前台 | 阻塞主对话直到完成，权限提示实时传给用户 | 无 |
| 后台 | 并行执行不打断主对话，启动前预确认权限 | 无法使用 MCP、无法交互式澄清；权限不足时任务失败 |
Ctrl+B 将当前代理切换后台；Ctrl+F（按两次）终止所有后台代理；消息开头加 & 作为后台任务发送。
📖 16.7 典型使用模式
隔离高输出任务：
使用子代理运行所有测试，只返回失败的测试和根因分析
并行研究：
并行使用子代理分别分析认证模块、数据库模块和 API 模块，汇总后给出整体架构建议
串联流水线：pm-spec（产出规格）→ architect-review（验证设计）→ implementer-tester（实现测试）
并行审查：同时启动 style-checker、security-scanner、test-coverage 三个子代理并行审查
📖 16.8 何时用子代理 vs 主对话
| 适合子代理 | 适合主对话 |
|---|---|
| 任务自包含，输入输出明确 | 需要频繁来回调整，交互性强 |
| 输出量大会淹没主对话上下文 | 多阶段任务有强依赖，上下文需连续 |
| 需要强约束（只读、隔离 worktree） | 快速小改动，启动代理开销不值得 |
| 同类任务会重复出现 | 超过 3-4 个子代理，管理成本可能反超收益 |
📖 16.XX 要点总结
- 子代理 = 独立上下文 + 专用工具 + 专业角色，核心价值是隔离保护和并行提效
- description 字段最重要——Claude 完全据此判断何时自动调用，务必写清触发场景
- 内置三种核心代理：Explore（只读探索）、Plan（规划收集）、General-purpose（综合执行）
- tools（白名单）vs disallowedTools（黑名单）：白名单排除 MCP，黑名单保留 MCP
- worktree 隔离是探索性重构的安全网，修改不影响主分支；后台运行让子代理不阻塞主对话
