<!-- title: 造子代理团队:让任务自动委派 -->

# 造子代理团队:让 Claude Code 自动派活

## 概述

本教程教你用 Claude Code 的**子代理(subagents)**机制,打造一支会自动接活的 AI 开发团队。读完你将掌握:子代理文件的写法、description 描述工程(如何让 Claude 在合适的时机**自动**把任务派给某个代理)、工具沙箱与权限隔离、三种调用方式的区别、并行与链式协作,以及持久记忆。适合已经用过 Claude Code、想从"一个人指挥一个 Claude"升级到"一个协调者调度一支代理团队"的开发者。

## 前置条件

- 已安装 Claude Code(v2.1.172 以上,以支持嵌套子代理;`/fork` 自 v2.1.161 起默认开启)
- 有一个 Git 仓库(本教程的实战项目以代码库为载体)
- 了解 `CLAUDE.md`、`/agents` 命令等基础概念
- 命令行基本操作

---

## 一、先搞懂:为什么是"自动委派"而不是"手动调用"

很多人的用法是:对着主对话一个 Claude 说到黑。这种"单代理"模式有三个天然瓶颈——**上下文会被搜索结果、测试日志、文件内容撑爆;Claude 开始遗忘;性能退化**。

子代理解决了这个问题。它是一个**跑在独立上下文窗口里**的专职 AI,有自己专属的系统提示、专属的工具白名单、专属的模型选择。它干完活,**只把结论摘要返回主对话**,那些冗长的中间过程留在它自己的上下文里,从不污染你的主会话。

Claude Code 自带三个内置子代理:

| 子代理 | 模型 | 工具 | 用途 |
| :--- | :--- | :--- | :--- |
| **Explore** | Haiku(快) | 只读,Write/Edit 被禁 | 代码搜索、文件发现、代码库探索 |
| **Plan** | 继承主对话 | 只读 | 计划模式里收集上下文 |
| **general-purpose** | 继承主对话 | 全部工具 | 复杂多步、需探索+修改的任务 |

关键的反直觉点来了:**Claude 会根据子代理的 `description` 字段,自动决定什么时候把活派给它**——你不需要每次手动喊"用 XX 代理"。这就是本教程的核心:把 description 写好,让一支代理团队在你的项目里**各司其职、自动接活**。

### 何时该用子代理,何时不该用

- **该用**:任务会产生大量你不需要留在主上下文的输出(跑测试、抓文档、分析日志);想强制工具限制;工作自包含、能返回摘要。
- **不该用**:需要频繁来回打磨;多个阶段共享大量上下文;只是个小改动;对延迟敏感(子代理从零开始,需要时间攒上下文)。

---

## 二、创建你的第一个子代理文件

子代理本质是**带 YAML frontmatter 的 Markdown 文件**。有两种创建方式。

### 方式 A:用 `/agents` 命令(推荐新手)

在 Claude Code 交互界面输入:

```text
/agents
```

切到 **Library** 标签 → **Create new agent** → 选 **Personal**(存到 `~/.claude/agents/`,所有项目可用)或 **Project**(存到 `.claude/agents/`,随仓库走、团队共享)。选 **Generate with Claude**,用一句话描述你要的代理,Claude 会帮你生成标识符、描述和系统提示。

### 方式 B:手写 Markdown 文件(推荐进阶)

这是本教程的主线,因为它最透明、最可控。在项目根目录创建 `.claude/agents/code-reviewer.md`:

```markdown
---
name: code-reviewer
description: Reviews code for quality and best practices
tools: Read, Glob, Grep, Bash
model: sonnet
---

You are a code reviewer. When invoked, analyze the code and provide specific,
actionable feedback on quality, security, and best practices.
```

frontmatter 定义元数据,Markdown 正文成为**系统提示**。子代理只会收到这个系统提示加基础环境信息(工作目录等),而**不是**完整的 Claude Code 系统提示——这是它上下文干净的根本原因。

**预期结果**:重启会话后(磁盘上直接改文件需要重启,`/agents` 界面创建则即时生效),在 `/agents` 的 Library 里能看到 `code-reviewer`。

**常见问题**:
- *文件改了不生效?* 直接编辑磁盘文件需重启会话;用 `/agents` 改则即时生效。
- *名字报重复?* `name` 必须全树唯一。v2.1.196 起,`/doctor` 会报告同作用域重名。

---

## 三、description 描述工程:让委派自动发生

这是本教程的**核心章节**。Claude 是否把任务自动派给某个子代理,主要看三样东西:**你这次请求里的任务描述、子代理的 `description` 字段、当前上下文**。

### 3.1 三种 description 写法,效果天差地别

写法一(平庸,几乎不会自动触发):

```yaml
description: Reviews code
```

写法二(合格):

```yaml
description: Expert code reviewer. Reviews code for quality and security.
```

写法三(精准,会主动接活):

```yaml
description: Expert code review specialist. Proactively reviews code for quality,
  security, and maintainability. Use immediately after writing or modifying code.
```

差别在第几处?**触发词和触发时机**。官方明确建议:为了鼓励主动委派,在 description 里加入 `"use proactively"`、`"use immediately after ..."` 这类短语。Claude 读到这些词,才会在合适的场景**主动**派活,而不是等你点名。

### 3.2 description 的四个黄金要素

1. **身份**:这个代理是什么专家(Expert code review specialist)
2. **职责**:它具体做什么(reviews code for quality, security, maintainability)
3. **触发时机**:什么时候该派给它(Use immediately after writing or modifying code)
4. **边界**:什么时候不该派给它(隐含在职责描述里)

### 3.3 多代理冲突:谁来接活?

当你有多个 description 重叠的代理时,Claude 会自己仲裁。但你可以用作用域优先级显式控制。Claude Code 扫描子代理有 **5 级优先级**(高到低):

| 位置 | 作用域 | 优先级 |
| :--- | :--- | :--- |
| Managed settings | 组织级 | 1(最高) |
| `--agents` CLI 参数 | 当前会话 | 2 |
| `.claude/agents/` | 当前项目 | 3 |
| `~/.claude/agents/` | 你的所有项目 | 4 |
| 插件的 `agents/` | 插件启用处 | 5(最低) |

同名时,**高优先级覆盖低优先级**。所以团队规范代理放 `.claude/agents/`(进版本库),个人偏好放 `~/.claude/agents/`,组织强制规则走 managed settings。

**常见问题**:
- *代理从不被自动触发?* 八成是 description 太笼统、缺触发词。补上 "use proactively" 和明确场景。
- *代理被误触发(抢了别的代理的活)?* 收窄职责描述,加边界;或调整作用域,用更高优先级的精确定义覆盖。

---

## 四、工具沙箱:给代理最小权限

子代理默认**继承主会话的所有内部工具和 MCP 工具**。但生产环境里,你绝不希望一个"只读审查"代理能改文件。有四道闸门。

### 4.1 白名单 `tools`(只给必要的)

```yaml
---
name: safe-researcher
description: Research agent with restricted capabilities
tools: Read, Grep, Glob, Bash
---
```

这个代理只能读、搜、跑命令,**不能 Edit/Write**。

### 4.2 黑名单 `disallowedTools`(继承全部,只禁某几个)

```yaml
---
name: no-writes
description: Inherits every tool except file writes
disallowedTools: Write, Edit
---
```

两者都设时,先应用 `disallowedTools`,再用 `tools` 在剩余池里收口。还能按 MCP 服务器批量收:`disallowedTools: mcp__github` 会干掉 github MCP 服务器的全部工具。

注意有些工具**子代理永远拿不到**,即使写进 `tools`:`AskUserQuestion`、`EnterPlanMode`、`ExitPlanMode`(除非 `permissionMode: plan`)、`ScheduleWakeup`、`WaitForMcpServers`——它们依赖主会话的 UI 或会话状态。

### 4.3 permissionMode:六种权限模式

`permissionMode` 控制子代理怎么处理权限提示:

| 模式 | 行为 |
| :--- | :--- |
| `default` | 标准提示 |
| `acceptEdits` | 自动接受工作目录内的文件编辑 |
| `auto` | 后台分类器审查命令和受保护目录写入 |
| `dontAsk` | 自动拒绝(显式放行的工具仍可用) |
| `bypassPermissions` | 跳过所有提示(慎用!) |
| `plan` | 计划模式,只读探索 |

注意:父会话若是 `bypassPermissions` 或 `acceptEdits`,**优先级更高,子代理无法覆盖**。

### 4.4 hooks 做条件验证(最细粒度)

当你需要"允许某个工具的某些操作、禁掉另一些"时,用 `PreToolUse` hook。下面这个代理能跑 Bash,但只允许只读 SQL:

```yaml
---
name: db-reader
description: Execute read-only database queries. Use when analyzing data or reports.
tools: Bash
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/validate-readonly-query.sh"
---
```

配套校验脚本(读取 stdin 的 JSON,发现写操作就 `exit 2` 阻断):

```bash
#!/bin/bash
# ./scripts/validate-readonly-query.sh
INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')
if echo "$COMMAND" | grep -iE '\b(INSERT|UPDATE|DELETE|DROP|CREATE|ALTER|TRUNCATE)\b' > /dev/null; then
  echo "Blocked: Only SELECT queries are allowed" >&2
  exit 2   # exit code 2 = 阻断并把 stderr 反馈给 Claude
fi
exit 0
```

记住:`chmod +x` 让脚本可执行。这套"白名单+黑名单+模式+hook"四件套,就是你造最小权限沙箱的全部武器。

---

## 五、三种调用方式:从自动到强制

自动委派是默认行为,但它"不强求"。当你想更确定时,有三档 escalation。

### 方式一:自然语言(最轻)

```text
Use the code-reviewer subagent to look at my recent changes
```

没有特殊语法,在 prompt 里点名即可。Claude **通常**会委派,但保留判断权。

### 方式二:@-mention(强制单次)

```text
@"code-reviewer (agent)" look at the auth changes
```

输入 `@` 从候选里挑,或在 v2.1.196+ 手敲 `@agent-code-reviewer`。**保证**那个代理一定为这个任务跑一次,选择权不交给 Claude。

### 方式三:`--agent`(整个会话级)

```bash
claude --agent code-reviewer
```

整个会话的主线程**直接变成**那个子代理:用它的系统提示(替换默认 Claude Code 系统提示)、它的工具限制、它的模型。想给项目设默认代理,写进 `.claude/settings.json`:

```json
{ "agent": "code-reviewer" }
```

CLI 参数会覆盖该设置。这是把一个项目彻底变成"专职审查工作台"的捷径。

---

## 六、并行与链式:让代理团队协作

### 6.1 并行研究(独立任务同时跑)

```text
Research the authentication, database, and API modules in parallel using separate subagents
```

Claude 为每个模块各派一个子代理,**同时**探索,各自独立上下文,最后由 Claude 综合结论。当研究路径互不依赖时效果最好。

### 6.2 链式协作(顺序流水线)

```text
Use the code-reviewer subagent to find performance issues,
then use the optimizer subagent to fix them
```

前一个的输出作为后一个的输入。每个代理完成后把结果交回 Claude,Claude 再把相关上下文传给下一个。

### 6.3 嵌套子代理(树形分工,v2.1.172+)

一个子代理**还能派自己的子代理**。典型场景:一个审查代理对每条发现各派一个验证代理,中间产物从不进入你的主对话,**只有顶层代理的摘要返回给你**。

约束:深度上限固定为 5 层——depth 5 的代理拿不到 `Agent` 工具,无法再派。要阻止某个代理派生,从它的 `tools` 里去掉 `Agent`,或加进 `disallowedTools`。

想限定某个作为主线程的代理(`claude --agent`)能派哪些子代理,用 `Agent(type1, type2)` 白名单语法:

```yaml
---
name: coordinator
description: Coordinates work across specialized agents
tools: Agent(worker, researcher), Read, Bash
---
```

### 6.4 前台 vs 后台

- **前台**:阻塞主对话直到完成,权限提示透传给你。
- **后台**:并发运行,你能继续干活。`Ctrl+B` 可把运行中的任务转后台。

v2.1.186 起,后台子代理遇到需权限的工具调用时,提示会浮到主会话、标明是哪个代理在问。设 `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1` 可彻底关闭后台功能。

---

## 七、持久记忆:让代理越用越聪明

给代理开 `memory`,它就有了跨会话的知识库,能积累代码库模式、调试经验、架构决策。

```yaml
---
name: code-reviewer
description: Reviews code for quality and best practices
memory: project
---
You are a code reviewer. As you review code, update your agent memory with
patterns, conventions, and recurring issues you discover.
```

三个作用域:

| 作用域 | 位置 | 适用 |
| :--- | :--- | :--- |
| `user` | `~/.claude/agent-memory/<name>/` | 跨所有项目积累 |
| `project` | `.claude/agent-memory/<name>/` | 项目专属、可随版本库共享(**推荐默认**) |
| `local` | `.claude/agent-memory-local/<name>/` | 项目专属但不入库 |

开启后,系统提示会自动注入记忆目录里 `MEMORY.md` 的前 200 行(或 25KB),且 Read/Write/Edit 会自动启用以便代理管理记忆文件。用法:让它开工前"查记忆"、收工后"存经验",日积月累就是机构知识库。

---

## 八、实战案例:代码质量守卫团队

把前面所有招式串起来。目标:为一个真实代码库搭一支 3 人代理团队,自动守卫代码质量。

### 步骤 1:创建三个代理文件

`.claude/agents/code-reviewer.md`(只读审查,写完代码自动接手):

```markdown
---
name: code-reviewer
description: Expert code review specialist. Proactively reviews code for quality,
  security, and maintainability. Use immediately after writing or modifying code.
tools: Read, Grep, Glob, Bash
model: inherit
memory: project
color: green
---

You are a senior code reviewer ensuring high standards. When invoked:
1. Run git diff to see recent changes
2. Focus on modified files
3. Begin review immediately
Review checklist: 命名清晰、无重复代码、错误处理到位、无泄露密钥、输入校验、测试覆盖。
按优先级输出:Critical(必修) / Warning(应修) / Suggestion(可选)。
每条问题给出具体修复示例。Review 后把发现的模式存入 agent memory。
```

`.claude/agents/optimizer.md`(可编辑,性能问题自动接手修复):

```markdown
---
name: optimizer
description: Performance optimization specialist. Use proactively when code review
  or profiling surfaces performance issues. Diagnoses and applies minimal fixes.
tools: Read, Edit, Bash, Grep, Glob
model: sonnet
color: orange
---

You are an expert in performance. When invoked:
1. 复现并量化性能问题(benchmark/profiler)
2. 定位瓶颈
3. 实施最小修复
4. 用 benchmark 验证改善
每次给出:根因、证据、改动、前后对比数据。
```

`.claude/agents/test-guard.md`(隔离测试噪音,后台友好):

```markdown
---
name: test-guard
description: Test runner that executes the suite and reports only failures with
  error messages. Use proactively after code changes to keep the build green.
tools: Bash, Read
model: haiku
background: true
color: blue
---

You run the project's test suite. When invoked:
1. 执行测试命令
2. 只报告失败的测试及其错误信息
3. 不把通过的测试细节带回来
保持主会话上下文干净。
```

### 步骤 2:观察自动委派

写完一段代码后,直接说:

```text
我刚改完了 auth 模块
```

你**不需要**点名 code-reviewer。因为它的 description 里有 "Use immediately after writing or modifying code",Claude 会自动把审查派给它。改完跑测试时,test-guard 因为 `background: true` 在后台跑,主会话不被阻塞。

### 步骤 3:链式 + 并行编排

```text
先用 code-reviewer 审查最近改动,把它发现的性能问题交给 optimizer 修复;
同时用 test-guard 跑一遍测试,只汇报失败项。
```

这条指令触发:**code-reviewer(前台)→ optimizer(链式接手)并行 test-guard(后台)**。三个代理各用各的模型(审查继承、优化用 sonnet、测试用便宜的 haiku)和工具集,互不污染主上下文。

### 步骤 4:会话级专职模式

想整场会话只做代码审查:

```bash
claude --agent code-reviewer
```

此后整个会话就是审查专家,系统提示、工具、模型全换成它的。

**预期效果**:主会话上下文长期保持清爽;代码质量、性能、测试三道防线各司其职;代理还能靠 `memory: project` 把审查经验沉淀进版本库,团队共享。

---

## 九、整体工作流程

```mermaid
flowchart TD
    U[用户发起任务] --> MAIN[主会话 / Claude 协调者]
    MAIN --> DEC{读取子代理 description<br/>决定委派}
    DEC -->|自动| SA1[code-reviewer<br/>只读·审查]
    DEC -->|自动| SA2[optimizer<br/>可编辑·修复]
    DEC -->|后台| SA3[test-guard<br/>跑测试·只报失败]
    SA1 -->|发现性能问题| SA2
    SA1 -.链式.-> SA2
    SA2 --> NEST[嵌套子代理<br/>逐项验证修复]
    SA1 --> MEM[(project memory<br/>积累审查经验)]
    SA2 --> MEM
    SA1 -->|仅返回摘要| MAIN
    SA2 -->|仅返回摘要| MAIN
    SA3 -->|仅返回失败项| MAIN
    MAIN --> R[综合结论交付用户]

    classDef agent fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px;
    classDef main fill:#fff3e0,stroke:#e65100,stroke-width:2px;
    classDef mem fill:#e3f2fd,stroke:#1565c0,stroke-width:2px;
    class SA1,SA2,SA3,NEST agent;
    class MAIN,R main;
    class MEM mem;
```

主会话只做协调与综合,所有重活(读 diff、改代码、跑测试)都在隔离的子代理上下文里发生,**只有摘要回流**,这是上下文经济学的核心。

---

## 十、常见问题速查

| 问题 | 原因 | 解决 |
| :--- | :--- | :--- |
| 代理从不自动触发 | description 太笼统、缺触发词 | 加 "use proactively" + 明确场景 |
| 磁盘改文件不生效 | 需重启会话 | 用 `/agents` 改,即时生效;或重启 |
| 同名代理冲突 | 多作用域重名 | `/doctor` 查重;用高优先级作用域覆盖 |
| 后台代理权限总被拒 | v2.1.186 前后台自动拒提示 | 升级版本;提示会浮到主会话 |
| Explore/Plan 不能续跑 | 一次性代理,无 agent ID | 改用 general-purpose 或自定义代理 |
| 想恢复之前的子代理 | 新调用是新实例 | 用 SendMessage 按 agent ID 续跑 |
| 嵌套到第 5 层派不动 | 深度硬上限 | 拆分任务,减少嵌套层数 |

恢复子代理的细节:每次调用是全新实例。要续跑,直接对 Claude 说 "continue that code review",它用 `SendMessage` 按代理 ID 续跑并保留完整历史。转录文件在 `~/.claude/projects/{project}/{sessionId}/subagents/agent-{agentId}.jsonl`。

---

## 延伸阅读

- **官方子代理文档**:`code.claude.com/docs/en/sub-agents`(frontmatter 字段、作用域、示例最权威来源)
- **并行运行代理对比**:`code.claude.com/docs/en/agents`(子代理 vs agent view vs agent teams vs dynamic workflows)
- **Agent SDK 概览**:`code.claude.com/docs/en/agent-sdk/overview`(编程式调度子代理,接 CI/CD)
- **Context Window 可视化**:`code.claude.com/docs/en/context-window`(直观感受子代理如何省上下文)
- **权限模式详解**:`code.claude.com/docs/en/permission-modes`(六种 permissionMode 的完整语义)

---

## 训练营适用性评估

- **适合的训练营类型**:中高级开发者训练营、AI 工程实战营、企业级 Claude Code 落地培训。不适合零基础(需先掌握基础交互与 `CLAUDE.md`)。
- **前置课程**:建议先完成"Claude Code 入门""CLAUDE.md 项目记忆""Hooks 护栏"三节。
- **预计教学时长**:讲解 60 分钟 + 动手实验 90 分钟(搭一支 3 人代理团队并跑通自动委派)+ 排错答疑 30 分钟,合计约 3 小时。
- **考核点**:能否写出会自动触发的 description;能否用四件套造最小权限沙箱;能否区分三种调用方式并说出何时用哪种。
- **延伸挑战**:给代理挂 MCP 服务器做浏览器测试;用 `isolation: worktree` 让代理在隔离副本里改代码;开启 `memory: project` 让团队共享代理经验。

## 参考来源

1. [Create custom subagents — Claude Code Docs](https://code.claude.com/docs/en/sub-agents) — 官方子代理权威文档,涵盖 frontmatter 全字段、作用域优先级、内置代理、示例
2. [Run agents in parallel — Claude Code Docs](https://code.claude.com/docs/en/agents) — 子代理/agent view/agent teams/dynamic workflows 四种并行方式的官方对比
3. [Claude Code Subagents and Multi-Agent Orchestration Guide](https://hidekazu-konishi.com/entry/claude_code_subagents_and_orchestration_guide.html) — 上下文隔离与多代理编排的深度实践指南
4. [Subagents in Claude Code: Delegating without losing control](https://www.frr.dev/posts/subagents-claude-code-tutorial/) — 委派模式与控制力平衡的实战教程
5. [Claude Code Subagents: Parallelize Development with Custom AI Agents](https://aiforanything.io/blog/claude-code-subagents-parallel-development-guide-2026) — 用自定义子代理并行化开发的工作流案例

> [!tip] 51学通信知识星球
> **星主：爱卫生**（微信：gprshome201101）——公众号「51学通信」创办者，19 年通信行业运维与讲师经验，著有《GPRS网络信令实例详解》《EPC原理与实践》《5G核心网原理与实践》三本纸质书（各大电商平台有售）。
> **星球定位**：深耕 5G 核心网、IMS、NFV/AI、云原生等 ICT 领域，主打运维岗位与信令分析。
> **当前规模**：5200 篇主题 / 990 个回答，198 元/年。
> **加入福利**：加入星球后请加爱卫生微信，拉您进知识星球年度陪伴与答疑群——不限量回复您的各种问题，另有群内分享。
> **AI 加持**：51学通信知识星球已作为 skill 接入 WorkBuddy，使用 deepseek-4-flash 在海量星球帖子中精准找贴、找视频、找 FAQ 和案例，做总结、找文档和 PPT 等场景全覆盖。

![51学通信知识星球海报-扫码加入](https://wiki.500nian.com/images/zhixingqiu_qrcode.png)