<!-- title: 造专职子代理并行拆分任务 -->

## 概述

本教程带你掌握 Claude Code 的**子代理（Subagents）**机制：用一份份带 YAML frontmatter 的 Markdown 文件，定义一批"专职小工"——代码审查员、测试生成器、文档抽取器……主代理在需要时自动把活派给它们，每个子代理在**独立上下文窗口**里干活，只把结论回传。它的价值在于三件事：**保护主上下文**（海量搜索结果/日志不再污染对话）、**收紈权限**（只给它干活需要的工具）、**并行拆分**（多个独立子代理同时跑）。适合想让 Claude Code 从"单线程对话"升级为"小型调度中心"的进阶用户。

## 前置条件

- Claude Code **v2.1.196 及以上**（`/doctor` 可检测同名冲突；本文 frontmatter 字段对应 v2.1.198–v2.1.200 语法）。
- 一个 Git 仓库（要用到 `isolation: worktree` 字段时必须有）。
- 已会用基本交互命令与计划模式（本系列前几篇已覆盖）。
- 安装并登录好 Claude Code：`claude` 命令可正常启动会话。

## 正文

### 步骤一：先搞清楚"子代理"到底解决了什么

在理解语法前，先建立正确的心智模型。Claude Code 默认只有一条主线对话，所有读文件、跑测试、看日志的结果都堆进同一个上下文窗口，几轮下来窗口就满了。子代理的本质是**把"杂活"外包给一个独立窗口**：它在那边翻箱倒柜，最后只交回一份摘要。

官方把"并行/委派"能力分成四种形态，子代理只是其一：

| 形态 | 一句话 | 适用场景 |
|---|---|---|
| **Subagents（子代理）** | 同一会话内的委派工人，独立上下文，回传摘要 | 副任务会污染主对话 |
| **Agent view（`claude agents`）** | 一屏调度、监控多个后台会话 | 多个独立任务要轮流查看 |
| **Agent teams（实验性）** | 多会话共享任务清单、互发消息 | 要让工人彼此协作 |
| **Dynamic workflows** | 脚本批量调度子代理并交叉校验 | 代码库级审计、500 文件迁移 |

本篇聚焦**第一种：子代理**。其余三种在后续进阶篇展开。

**预期结果**：你能在心里画出"主代理 → 委派决策 → 子代理（独立上下文）→ 摘要回传"这条链路，这是后面所有配置的目标方向。

**常见问题**：
- *子代理和"在终端开多个 Claude 窗口"有什么区别？* 多窗口是多个**独立会话**，彼此不通气；子代理是**同一会话内**由主代理调度的工人，结果直接回灌到当前对话，你能无缝接着用。
- *子代理能不能改我的代码？* 默认能（若 `tools` 留空则继承全部工具），但你可以把它收紧成只读——这正是它的安全价值。

### 步骤二：创建第一个子代理文件

子代理就是一个 Markdown 文件 + YAML 头。两种放法：

- **项目级**：`<repo>/.claude/agents/code-reviewer.md`（进版本控制，团队共享）
- **用户级**：`~/.claude/agents/code-reviewer.md`（你所有项目可用）

直接写一个最简单的版本，保存为 `.claude/agents/code-reviewer.md`：

```markdown
---
name: code-reviewer
description: 审查代码质量与最佳实践。在代码被写入或修改后主动使用。
tools: Read, Glob, Grep
model: sonnet
---

你是一名资深代码审查员。被调用时，分析指定代码并给出具体、可执行的反馈，
覆盖质量、安全与最佳实践。每条问题要说明：问题在哪、当前写法、改进写法。
```

- **操作说明**：`frontmatter` 里只有 `name` 和 `description` 是必填；`tools` 留空则继承全部工具，这里显式只给三个**只读**工具，让它无法动文件。
- **预期结果**：保存后，Claude Code 的目录监视器**几秒内**检测到改动，下次委派自动用新定义，**无需重启**。
- **常见问题**：
  - *改了文件没生效？* 监视器只覆盖会话启动时**已存在**的目录。如果是该 scope 的**第一个**子代理文件（新建的 `agents/` 目录），需要**重启一次** Claude Code。
  - *名字怎么取？* `name` 只能用小写字母和连字符（如 `code-reviewer`）。同一 scope 内重名只加载一个；`/doctor`（v2.1.196+）会报告同名冲突并指出当前生效的定义。

### 步骤三：读懂 frontmatter，按需调参

这是子代理最强大的部分。下表覆盖全部字段（对照官方 v2.1.198–v2.1.200 语法）：

| 字段 | 必填 | 作用 |
|---|---|---|
| `name` | 是 | 唯一标识，小写+连字符；hooks 里作为 `agent_type` 收到 |
| `description` | 是 | **决定何时被委派**——写清楚触发条件，主代理据此判断 |
| `tools` | 否 | 允许的工具，逗号分隔；留空继承全部 |
| `disallowedTools` | 否 | 从继承列表里再剔除的工具（黑名单） |
| `model` | 否 | `sonnet`/`opus`/`haiku`/`fable`/完整模型ID/`inherit`；默认 `inherit` |
| `permissionMode` | 否 | `default`/`acceptEdits`/`auto`/`dontAsk`/`bypassPermissions`/`plan`/`manual`（插件子代理忽略） |
| `maxTurns` | 否 | 最大自主轮次上限，防失控 |
| `skills` | 否 | 启动时预加载的 Skill（注入完整内容，非仅描述） |
| `mcpServers` | 否 | 该子代理可用的 MCP 服务器（插件子代理忽略） |
| `hooks` | 否 | 仅作用于本子代理的生命周期钩子 |
| `memory` | 否 | 持久记忆 scope：`user`/`project`/`local` |
| `background` | 否 | `true` 则恒为后台任务；v2.1.198 起子代理**默认后台跑** |
| `effort` | 否 | 努力档：`low`/`medium`/`high`/`xhigh`/`max` |
| `isolation` | 否 | `worktree` 让子代理在临时 git worktree 里跑，独立副本 |
| `color` | 否 | 任务列表里的显示色：red/blue/green/yellow/purple/orange/pink/cyan |
| `initialPrompt` | 否 | 该代理作为主会话代理时（`--agent`）自动作为首轮输入 |

三个最常用的调参点：

1. **`description` 是触发器**。它越清晰，自动委派越准。别写"代码相关任务"，要写"**在代码被修改后**主动审查质量、安全与最佳实践"——主代理据此判断要不要派活。
2. **`model` 是省钱开关**。把"只读检索"类子代理设 `model: haiku`，把"需要复杂推理"的设 `sonnet`/`opus`，能在质量和成本间精准权衡。也可用环境变量 `CLAUDE_CODE_SUBAGENT_MODEL` 全局覆盖。
3. **`isolation: worktree` 解决并行写冲突**。多个会同时改文件的子代理，各跑各的临时 worktree（默认从你的默认分支拉），互不踩踏，结束后自动清理。

**常见问题**：
- *我想让子代理有 Bash 但不能 `rm`？* 用 `tools: Read, Grep, Glob, Bash` 给白名单，再用 `disallowedTools` 配合权限规则收紧，或在 `permissionMode` 上做文章。
- *完整模型 ID 怎么写？* 与 `--model` 同取值，如 `claude-opus-4-8`、`claude-sonnet-5`。

### 步骤四：自动委派 vs 显式调用

子代理有两条触发路径：

- **自动委派**：主代理读到你的请求后，对照各子代理的 `description`，自行决定派给谁。你只管描述任务，剩下交给调度。
- **显式调用**：在提示里点名，例如"用 `code-reviewer` 子代理审查 `src/auth.py`"。会话里也可用 `@` 提及选中某个子代理类型。

显式调用适合你**明确知道**该走哪个专家；自动委派适合你**只描述目标**，让 Claude 选人。两者可混用。

**操作说明**：在会话里输入：

```
请审查 src/auth.py 这个文件
```

**预期结果**：若 `code-reviewer` 的 description 匹配，Claude 会显示"委派给 code-reviewer 子代理"，子代理在独立上下文里读完文件、产出审查意见，主对话只保留**摘要**——你不会看到它逐行 grep 的过程。

**常见问题**：
- *没被自动委派？* 多半是 `description` 写得不够具体，或任务描述里没出现匹配信号。改 description，或直接显式 `@code-reviewer`。
- *想彻底关掉自动委派？* 在 `permissions.deny` 里 deny `Agent` 工具本身即可；只想去掉内置 Explore/Plan，设 `CLAUDE_CODE_DISABLE_EXPLORE_PLAN_AGENTS=1`。

### 步骤五：并行编排——把多个专家同时撒出去

真正的提速在这一步。当几个子任务**互相独立**时，主代理可以并行委派多个子代理，各自在独立上下文里跑，齐了再汇总。

三个编排要点：

- **独立上下文天然并行**：每个子代理有自己的窗口，主代理可在一条消息里同时派多个。
- **`background: true` / v2.1.198 默认后台**：子代理后台跑时，主代理不被阻塞，任务列表里实时看状态。
- **链条式编排**：A 子代理出结论喂给 B 子代理，串成流水线（如"审查 → 据审查意见生成测试"）。

**操作说明**：在会话里一次性描述三个独立子任务：

```
对当前这次改动做三件事并行处理：
1) 审查 src/ 下的代码质量
2) 为 src/ 下缺少测试的函数补单元测试
3) 从改动里抽取要写进 CHANGELOG 的条目
```

**预期结果**：Claude 同时委派三个子代理（reviewer / test-writer / doc-extractor），任务列表里三个色块并行滚动，完成后主对话只收到三份汇总。

**常见问题**：
- *三个子代理都要改文件，会互相覆盖吗？* 会。解法：给写文件的子代理加 `isolation: worktree`，各跑各的副本；或让写操作串行、只读操作并行。
- *并行会不会爆 token？* 会线性增长。官方明确：同时跑多个子代理 = token 用量翻倍。对大批量任务，考虑 `/batch` 技能（自动把一个大改动拆成 5–30 个 worktree 隔离子代理，各自开 PR）或 Dynamic workflows。

## 实战案例：三专家子代理处理一次功能分支变更

目标：造一个"提 PR 前自检流水线"，由三个专职子代理协同处理一次代码变更。

先建三个文件。`.claude/agents/qa-reviewer.md`（只读审查，贵模型）：

```markdown
---
name: qa-reviewer
description: 在代码修改后主动审查质量、安全与潜在 bug。只读，不改文件。
tools: Read, Glob, Grep
model: opus
color: yellow
---

你是资深审查员。聚焦：边界条件、空指针、注入风险、错误处理缺失。
每条问题给：文件:行号、风险描述、修复建议。读不到问题就明确说"无问题"，不要凑数。
```

`.claude/agents/test-writer.md`（可写，隔离 worktree 防冲突，中档模型）：

```markdown
---
name: test-writer
description: 为新增或修改的函数补齐单元测试。需要写文件。
tools: Read, Glob, Grep, Write, Edit, Bash
model: sonnet
isolation: worktree
color: green
---

你是测试工程师。先跑 `npm test` 确认现状，再为无覆盖的函数补 Jest 测试，
每加一个用例就重跑测试确保通过。只返回新增文件清单与最终通过/失败数。
```

`.claude/agents/doc-extractor.md`（只读抽取，便宜模型省钱）：

```markdown
---
name: doc-extractor
description: 从一次代码改动里抽取适合写进 CHANGELOG 的条目。只读。
tools: Bash, Read
model: haiku
color: cyan
---

你从 `git diff` 输出里提炼面向用户的变化条目，按 Keep a Changelog 格式
（Added/Changed/Fixed/Removed）输出，每条一行，去技术黑话。
```

接着两种用法各演示一次。

**用法 A——一句话触发并行编排**：

```
针对当前 feature 分支相对 main 的改动，并行：审查、补测试、抽 CHANGELOG。
```

主代理识别出三个子任务，**同时**委派三个子代理：`qa-reviewer`（opus，只读）跑审查；`test-writer`（sonnet，worktree 隔离）在副本里补测试并自跑；`doc-extractor`（haiku，最省）读 diff 出条目。三路并行，主对话只收三份摘要——你的主上下文**全程没被任何 grep、test log 污染**。

**用法 B——临时子代理，不落盘**（用 `--agents` 传 JSON，仅本次会话有效）：

```bash
claude --agents '{
  "qa-reviewer": {"description":"代码修改后主动审查，只读。","prompt":"你是审查员，给出文件:行号、风险、修复建议。","tools":["Read","Grep","Glob"],"model":"opus"},
  "doc-extractor":{"description":"从改动抽 CHANGELOG 条目，只读。","prompt":"按 Keep a Changelog 输出。","tools":["Bash","Read"],"model":"haiku"}
}'
```

适合写脚本/CI 里**临时**用一组子代理，不污染项目目录。注意 `--agents` 的 JSON 用 `prompt` 字段放系统提示（等价于文件版的 Markdown 正文），并支持 `disallowedTools`、`permissionMode`、`mcpServers`、`hooks`、`maxTurns`、`skills`、`effort`、`isolation` 等全部字段。

**预期结果**：一次 PR 自检从"人工切三个窗口、手动复制结果"变成"一句话、三专家并行、主对话只留结论"。审查走 opus 保质量，抽 changelog 走 haiku 保成本，写测试进 worktree 保不冲突——这正是子代理"专、紧、并行"三性的集中体现。

## 工作流程图

下图展示一次三专家并行编排的数据流（每个子代理独立上下文，只回传摘要）：

```mermaid
flowchart TD
    U[用户：审查+补测试+抽CHANGELOG] --> MAIN[主代理：解析任务]
    MAIN --> DEC{委派决策<br/>匹配 description}
    DEC -->|代码质量| A1[qa-reviewer<br/>opus 只读]
    DEC -->|缺测试| A2[test-writer<br/>sonnet worktree]
    DEC -->|改动提炼| A3[doc-extractor<br/>haiku 只读]
    A1 -.独立上下文.-> C1[审查报告摘要]
    A2 -.独立上下文.-> C2[新测试+通过数]
    A3 -.独立上下文.-> C3[CHANGELOG 条目]
    C1 --> MAIN
    C2 --> MAIN
    C3 --> MAIN
    MAIN --> R[主对话：仅保留三份摘要<br/>上下文未被污染]
    style MAIN fill:#fef3c7
    style R fill:#dcfce7
```

下面这张是主代理"是否委派"的决策链，帮你理解自动委派与显式调用的分叉：

```mermaid
flowchart LR
    TASK[新任务进入主对话] --> CHK{有匹配的子代理<br/>description 吗}
    CHK -->|有，且用户未指定| AUTO[自动委派<br/>选最匹配者]
    CHK -->|用户已 @点名| EXPL[显式调用<br/>指定子代理]
    CHK -->|无匹配/任务轻| SELF[主代理自己做]
    AUTO --> ISOL{需写文件且可能冲突}
    EXPL --> ISOL
    ISOL -->|是| WT[worktree 隔离<br/>独立副本]
    ISOL -->|否| DIR[直接在当前目录]
    WT --> SUM[子代理独立上下文<br/>干活+回传摘要]
    DIR --> SUM
    style AUTO fill:#dbeafe
    style EXPL fill:#ede9fe
    style SUM fill:#dcfce7
```

## 训练营适用性评估

- **适用类型**：进阶营（已掌握交互与计划模式的开发者）。不适合纯零基础营——需要先理解上下文窗口、工具权限等概念。
- **预计教学时长**：理论讲解 45 分钟 + 动手造三个子代理 60 分钟 + 并行编排演练 45 分钟，合计约 **2.5 小时**。
- **能力考核点**：能否独立写出"触发清晰的 description + 恰当的 tools/model/isolation 组合"，并能解释为何这样省 token、保安全、避写冲突。
- **延伸方向**：学完本篇可顺势接 Agent view（`claude agents`）、Agent teams、Dynamic workflows 与 `/batch`，向"调度中心"进阶。

## 延伸阅读

- 官方子代理主文档：`https://code.claude.com/docs/en/sub-agents`——frontmatter 全字段权威说明
- 官方并行总览：`https://code.claude.com/docs/en/agents`——四种并行形态对比
- 官方 Agent SDK 子代理：`https://code.claude.com/docs/en/agent-sdk/subagents`——编程式调用子代理

## 参考来源

1. [Create custom subagents — Claude Code Docs](https://code.claude.com/docs/en/sub-agents) — 子代理 frontmatter 全字段、scope 优先级、内置子代理与委派机制权威说明
2. [Run agents in parallel — Claude Code Docs](https://code.claude.com/docs/en/agents) — Subagents / agent view / agent teams / dynamic workflows 四种并行形态对比
3. [Subagents in Claude Code: Delegating without losing control](https://www.frr.dev/posts/subagents-claude-code-tutorial/) — 自动委派、显式调用与并行执行的实战教程
4. [Claude Code Subagents: The Complete Guide — ComputingForGeeks](https://computingforgeeks.com/claude-code-subagents-guide/) — 完整 frontmatter schema 与常用编排模式
5. [Claude Code Subagents Collection — GitHub (chusri)](https://github.com/chusri/claude-code-agents) — 75 个开箱即用专职子代理，可直接借鉴 frontmatter 写法

> [!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)