## 概述
当单一 Claude 会话同时承担架构设计、写测试、查安全、写文档时，上下文很快会被搜索结果、日志和文件内容淹没，主线任务被迫中断。本教程教你用 Claude Code 的**子代理（Subagents）**机制，在 `.claude/agents/` 下定义一组各司其职的"专家"，让主会话像项目经理一样把子任务委派出去，各自在独立上下文窗口里工作，只把结论交回来。学完你将掌握：子代理的创建、frontmatter 全字段配置、工具围栏、模型分级、并行委派，并能落地一个由架构师、测试、安全三位专家组成的"代码审查团队"。适合已跑通 Claude Code 基础用法、想从单兵作战升级到团队协作的开发者。
## 前置条件
- 已安装 Claude Code（v2.1.x 以上，本文以 2026 年的 `claude-opus-4-8` / `claude-sonnet-4-6` / `claude-haiku-4-5` 为模型示例）
- 有一个可交互的终端会话（子代理主要在交互会话中自动委派）
- 已有一个待审查的真实代码仓库（git 仓库最佳，便于使用 worktree 隔离）
- 对 YAML frontmatter 有基本认识
---
## 一、为什么单一 Agent 不够：子代理解决的三类痛点
主会话（main thread）是你和 Claude 对话的那个上下文窗口。它有一个硬约束：**容量有限**。一旦你让它在主线里跑 `grep` 全仓库、读十几个文件、跑测试看日志，这些中间产物就会挤占宝贵的上下文额度，把真正要解决的问题"挤出"记忆。
子代理正是为切断这种污染而设计。它有三个本质特征：
1. **独立上下文窗口**：子代理在自己独立的上下文里运行，搜索结果、日志、文件内容都留在它自己的窗口里，主会话只拿到它返回的摘要。
2. **受限工具集**：你可以规定某个子代理只能读不能写，或只能调用特定 MCP 服务器。
3. **专属系统提示**：子代理只接收你写的系统提示加上基本环境信息（工作目录等），不继承主会话的完整系统提示，因此可以高度专业化。
```mermaid
flowchart LR
User([你]) -->|对话| Main[主会话
项目经理]
Main -->|委派研究| Exp[Explore 子代理
Haiku·只读]
Main -->|委派审查| Arch[架构师 子代理
Opus]
Main -->|委派测试| Test[测试 子代理
Sonnet]
Main -->|委派安全| Sec[安全 子代理
Haiku]
Exp -.只返回摘要.-> Main
Arch -.只返回结论.-> Main
Test -.只返回报告.-> Main
Sec -.只返回清单.-> Main
style Main fill:#ffe9b3,stroke:#b8860b,stroke-width:2px
```
Claude Code 内置了几个开箱即用的子代理，理解它们是写好自定义子代理的前提：
| 内置子代理 | 模型 | 工具 | 用途 |
|:--|:--|:--|:--|
| **Explore** | Haiku（快、低延迟） | 只读（禁止 Write/Edit） | 代码搜索、文件发现、代码库探索 |
| **Plan** | 继承主会话 | 只读 | plan 模式下做研究、收集上下文 |
| **general-purpose** | 继承主会话 | 全部工具 | 需要既探索又修改的复杂多步任务 |
注意一个关键设计：Explore 和 Plan 会**跳过**你的 `CLAUDE.md` 和主会话的 git 状态，以保证研究既快又便宜；而其他自定义子代理都会加载这两者。这个差异在后面调优成本时很重要。
---
## 二、创建第一个子代理：两种姿势
### 姿势 A：用 `/agents` 命令（推荐新手）
在交互会话里输入：
```text
/agents
```
切到 **Library** 标签 → **Create new agent**。你可以选 **Generate with Claude**，用自然语言描述需求，例如：
> A code improvement agent that scans files and suggests improvements for readability, performance, and best practices.
Claude 会自动生成 `name`、`description` 和系统提示词。接着依次选择：工具（只读审查就只勾 Read-only tools）、模型（选 Sonnet 平衡能力与速度）、显示颜色、记忆范围（选 User scope 会让它在 `~/.claude/agent-memory/` 跨会话积累经验）。保存后立即生效，无需重启。
### 姿势 B：手写 Markdown 文件（推荐自动化、版本控制）
子代理就是一个带 YAML frontmatter 的 `.md` 文件。最简形态：
```markdown
---
name: code-reviewer
description: Reviews code for quality and best practices
tools: Read, Glob, Grep
model: sonnet
---
You are a code reviewer. When invoked, analyze the code and provide
specific, actionable feedback on quality, security, and best practices.
```
文件放哪决定了它的作用域，优先级从高到低：
| 位置 | 作用域 | 优先级 |
|:--|:--|:--|
| 托管设置（managed settings） | 组织级 | 1（最高） |
| `--agents` CLI 参数 | 仅本次会话 | 2 |
| `.claude/agents/`（项目内） | 当前项目 | 3 |
| `~/.claude/agents/`（用户级） | 你的所有项目 | 4 |
| 插件的 `agents/` 目录 | 插件启用处 | 5（最低） |
**实践建议**：与具体代码库绑定的专家（如"本项目的领域规则审查员"）放 `.claude/agents/` 并提交进 git，让全团队共享；与个人习惯绑定的（如"我的 commit message 润色员"）放 `~/.claude/agents/`。
一个重要细节：子代理在会话启动时加载。如果你直接在磁盘上新建/编辑了文件，需要**重启会话**才能识别；而通过 `/agents` 界面创建的则会立即生效。
还有一个命令行姿势，适合自动化脚本里临时定义、不留盘的子代理：
```bash
claude --agents '{
"code-reviewer": {
"description": "Expert code reviewer. Use proactively after code changes.",
"prompt": "You are a senior code reviewer. Focus on quality, security, and best practices.",
"tools": ["Read", "Grep", "Glob", "Bash"],
"model": "sonnet"
},
"debugger": {
"description": "Debugging specialist for errors and test failures.",
"prompt": "You are an expert debugger. Analyze errors, identify root causes, and provide fixes."
}
}'
```
注意 JSON 形态下用 `prompt`（对应文件形态的 Markdown 正文）承载系统提示词。
---
## 三、frontmatter 全字段解析：把专家调到最佳状态
这是本教程最硬核的一节。下表是官方支持的完整字段，只有 `name` 和 `description` 必填：
| 字段 | 作用 | 取值要点 |
|:--|:--|:--|
| `name` | 唯一标识，小写+连字符 | hooks 里以 `agent_type` 收到此值；文件名不必与之一致 |
| `description` | 决定 Claude **何时**委派给它 | 写清楚"什么时候该用我"，是自动触发准确性的命脉 |
| `tools` | 允许使用的工具（白名单） | 省略则继承主会话全部工具 |
| `disallowedTools` | 禁用的工具（黑名单） | 会先于 `tools` 生效 |
| `model` | 使用的模型 | `sonnet`/`opus`/`haiku`/`fable`/完整 ID（如 `claude-opus-4-8`）/`inherit` |
| `permissionMode` | 权限模式 | `default`/`acceptEdits`/`auto`/`dontAsk`/`bypassPermissions`/`plan` |
| `maxTurns` | 最大轮数 | 防止失控的兜底 |
| `skills` | 启动时预加载的 Skills | 完整内容注入，而非仅描述 |
| `mcpServers` | 该子代理专属的 MCP 服务器 | 内联定义或按名引用 |
| `hooks` | 该子代理作用域内的生命周期钩子 | |
| `memory` | 持久记忆范围 | `user`/`project`/`local` |
| `background` | 是否总以后台任务运行 | `true`/`false` |
| `effort` | 思考强度 | `low`/`medium`/`high`/`xhigh`/`max`，取决于模型 |
| `isolation` | 隔离模式 | 设为 `worktree` 则在临时 git worktree 中运行 |
| `color` | 显示颜色 | red/blue/green/yellow/purple/orange/pink/cyan |
| `initialPrompt` | 作为主线 agent 时的首条自动提交 | 经 `--agent` 或 `agent` 设置启动时 |
三个最容易被忽视、却极有价值的字段：
**`description` 是自动委派的灵魂。** Claude 完全靠它判断"这个任务该不该交给这个子代理"。写得越具体、越能触发，越不容易误派。对比：
```yaml
# ❌ 太模糊，容易和内置 Explore 抢活
description: Searches the codebase
# ✅ 具体、有边界，触发精准
description: Audits TypeScript code for missing error handling around async/await and Promise chains. Use after backend route handlers or API client code changes.
```
**`isolation: worktree` 让并行专家不互相踩脚。** 默认情况下子代理共享主会话的工作目录，多个专家同时改文件会冲突。设为 worktree 后，每个子代理拿到一份临时仓库副本（默认从你的 default branch 而非父会话 HEAD 分支），干完活若没改动会自动清理。
**`memory` 让专家越用越聪明。** 设为 `project` 后，子代理会在 `.claude/agent-memory/` 跨会话积累洞见——比如"这个仓库习惯用 Zod 做校验"、"用户偏好函数式写法"。
---
## 四、工具围栏：给专家划定安全作业半径
工具控制有两条独立轴线，可以单独或组合使用。
**白名单（`tools`）**——只给最少必要工具：
```yaml
---
name: safe-researcher
description: Research agent with restricted capabilities
tools: Read, Grep, Glob, Bash
---
```
这个研究员能读、能搜、能跑命令，但**不能写、不能改**。
**黑名单（`disallowedTools`）**——继承全部工具，只摘掉危险的：
```yaml
---
name: no-writes
description: Inherits every tool except file writes
disallowedTools: Write, Edit
---
```
两条都设时，先按 `disallowedTools` 摘除，再在剩余集合里按 `tools` 取交集；同时出现在两边的一律删除。
**MCP 工具也能按服务器粒度控制**，写法是 `mcp__` 或 `mcp____*`：
```yaml
---
name: local-only
description: Inherits every tool except those from the github MCP server
disallowedTools: mcp__github
---
```
黑名单里写 `mcp__*` 可以一次性摘掉所有 MCP 工具。
还有一类需要特别留意——有些工具**永远**不可用于子代理，即使你写进 `tools` 也没用：`AskUserQuestion`、`EnterPlanMode`、`ScheduleWakeup`、`WaitForMcpServers`，以及（除非子代理处于 plan 模式的）`ExitPlanMode`。原因都是这些工具依赖主会话的 UI 或会话状态。
最后一个高级技巧：当一个 agent 通过 `claude --agent` 当作主线运行时，可以用 `Agent(worker, researcher)` 这种语法限制它**只能再生成哪几种子代理**，实现"协调员-工人"的层级编排。
---
## 五、模型分级：能力与成本的精密天平
模型选择是子代理区别于普通提示词工程的最大杠杆——你终于可以**按任务难度给不同专家配不同档位的脑子**。模型解析顺序为：
1. 环境变量 `CLAUDE_CODE_SUBAGENT_MODEL`（若设置，全局覆盖）
2. 单次调用的 `model` 参数
3. 子代理定义里的 `model` 字段
4. 主会话模型
实务上的黄金分配：
| 专家角色 | 推荐模型 | 理由 |
|:--|:--|:--|
| 架构设计、复杂重构决策 | Opus（`opus` 或 `claude-opus-4-8`） | 需要最强推理 |
| 常规代码审查、写测试 | Sonnet（`sonnet`） | 能力与速度平衡 |
| 大范围搜索、模式匹配、格式校验 | Haiku（`haiku`） | 快、便宜，规模化扫库 |
一条经验法则：**让 80% 的"杂活"跑在 Haiku 上，把 Opus 留给真正需要深思的 20%。** 一个用 Haiku 扫全库找未捕获 Promise 的子代理，成本可能只有 Opus 版的十几分之一，而结果几乎一样好。
---
## 六、并行委派：让专家团队同时开工
子代理不是串行工具，Claude 会在一条消息里同时委派多个独立任务，让它们并发执行。这种"扇出（fan-out）"是把复杂工作切成可并行块的关键。
显式调用子代理有三种方式：
1. **自然语言委派**：`Use the code-reviewer agent to review src/api/`
2. **@-mention**：在消息里 `@code-reviewer` 直接点名
3. **作为主线启动**：`claude --agent code-reviewer`，此时它成为主会话，可配合 `initialPrompt` 自动执行首条指令
并行委派的典型场景：当你下达"帮我全面体检这个 PR"时，Claude 会判断出架构审查、测试覆盖、安全扫描三者相互独立，于是在一条消息里同时派出三个子代理：
```mermaid
sequenceDiagram
participant U as 你
participant M as 主会话(协调员)
participant A as 架构师 Opus
participant T as 测试 Sonnet
participant S as 安全 Haiku
U->>M: 全面体检 PR #42
M->>A: 审查模块边界与耦合
M->>T: 评估测试覆盖率
M->>S: 扫描注入与密钥泄漏
par 三个专家并发工作（各自独立上下文/worktree）
A-->>M: 架构报告
T-->>M: 覆盖率缺口清单
S-->>M: 安全风险清单
end
M->>U: 汇总三方结论 + 优先级建议
```
主会话收到的只是三条摘要，而不是三份完整的代码搜索结果——这就是上下文不被污染的全部魔法。
---
## 七、实战案例：落地一个"代码审查三专家团队"
下面我们把前面所有概念串起来，构建一个可直接用的项目级团队。在仓库根目录创建三个文件。
**文件 1：`.claude/agents/arch-reviewer.md`** —— 架构师，最强模型 + 写权限以便能给出可直接应用的补丁：
```markdown
---
name: arch-reviewer
description: Reviews module boundaries, coupling, and design patterns in TypeScript/Go backends. Use after changes that touch multiple files or service layers.
model: claude-opus-4-8
tools: Read, Grep, Glob, Bash
effort: high
color: purple
memory: project
---
You are a principal software architect. When invoked:
1. Map the affected modules and their dependencies.
2. Flag tight coupling, circular dependencies, and leaky abstractions.
3. Propose the minimal refactor that preserves behavior.
Return a prioritized list: each item has severity, location (file:line),
problem, and a concrete fix. Do not edit files unless explicitly asked.
```
**文件 2：`.claude/agents/test-auditor.md`** —— 测试审计员，中档模型，worktree 隔离以便它能安全地实际跑测试：
```markdown
---
name: test-auditor
description: Evaluates test coverage and quality for changed code. Runs the suite and reports gaps.
model: sonnet
tools: Read, Grep, Glob, Bash
disallowedTools: Edit
isolation: worktree
maxTurns: 25
color: green
---
You are a test engineer. When invoked:
1. Identify changed functions/classes from git diff.
2. Run the test suite (`npm test` or equivalent).
3. List untested branches and brittle tests.
Return a coverage gap report. Never commit changes.
```
**文件 3：`.claude/agents/security-scanner.md`** —— 安全扫描员，便宜模型扫全库 + 专属安全 MCP：
```markdown
---
name: security-scanner
description: Scans for injection, hardcoded secrets, and unsafe deserialization across the repo.
model: haiku
tools: Read, Grep, Glob
mcpServers:
- github
color: red
---
You are an application security analyst. Scan for:
- SQL/command injection and unsafe eval
- Hardcoded secrets and API keys
- Path traversal and unsafe deserialization
Return a risk list with file:line and remediation. Read-only.
```
三个文件就位后，重启会话让 Claude Code 加载它们。然后在主会话里下达：
```text
我刚合并了 feat/payment 的改动，请用 arch-reviewer、test-auditor、security-scanner
三个专家并行体检，最后给我一份按严重程度排序的整改清单。
```
预期结果：Claude 会判断这三项审查相互独立，于是一条消息里同时派出三位专家。架构师用 Opus 在共享目录做推理；测试审计员在独立 worktree 里实际 `npm test` 拿到真实覆盖率；安全扫描员用 Haiku 快速扫全库。约一两分钟后，你收到一份汇总清单，主会话上下文依然清爽。
把 `.claude/agents/` 提交进 git，全团队 `git pull` 后就能复用同一套专家，这是从"个人工具"升级到"团队资产"的关键一步。
---
## 八、常见问题与排坑
**子代理没被自动触发？** 九成是 `description` 写得太宽泛，和内置 Explore 撞车。把它改得足够具体——写明触发条件、限定语言/场景。
**多个专家改同一文件冲突？** 给会改文件的子代理加 `isolation: worktree`，各自在临时副本上工作。
**改动文件后子代理没更新？** 直接编辑磁盘文件需要重启会话才生效；用 `/agents` 界面改则即时生效。
**插件子代理的 hooks 不生效？** 出于安全，来自插件的子代理会忽略 `hooks`、`mcpServers`、`permissionMode` 三个字段。需要时把文件复制到 `.claude/agents/` 下。
**想完全屏蔽某个内置子代理？** 在 `permissions.deny` 里加 `Agent`（屏蔽所有）或具体类型，或设置环境变量 `CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS=1`。
**子代理成本失控？** 检查是否该用 Haiku 的搜索型任务误配了 Opus；用 `maxTurns` 给长任务兜底；用 `disallowedTools` 防止意外的 MCP 调用。
---
## 九、延伸阅读
- 官方《Create custom subagents》—— frontmatter 字段与权限的权威出处
- 官方《Run agents in parallel》—— subagent / agent view / agent teams 三种并行模式的对比
- 官方《Orchestrate teams of Claude Code sessions》—— Agent Teams，子代理之上的多会话协作（实验特性，需 `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS`）
- 官方《Context window visualization》—— 直观理解子代理如何省上下文
下一步进阶方向：把本教程的三专家团队与 hooks 结合，让 `PostToolUse` 在每次提交后自动触发这套审查流水线；或进一步探索 Agent Teams，让多个会话之间通过共享任务列表真正"对话"协作。
---
## 十、训练营适用性评估
- **适合的训练营类型**：进阶/高级班。学员需已掌握 Claude Code 基础交互、理解上下文窗口概念。
- **不适合**：零基础入门班——子代理的心智模型（独立上下文、委派、并行）对新手偏重。
- **预计教学时长**：理论讲解 + 跟做三专家案例，约 2.5～3 小时；若要求学员自行设计一个领域专属子代理（如 SQL 审计员、API 契约校验员）并演示，再加 1.5 小时实操。
- **核心教学点**：① 独立上下文的隔离价值 ② `description` 驱动自动委派 ③ 模型分级做成本控制 ④ worktree 并行隔离。建议用"改造前后上下文占用对比"作为最直观的 A/B 演示。
---
## 参考来源
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) — subagent / agent view / agent teams 三种并行机制对比
3. [Orchestrate teams of Claude Code sessions — Claude Code Docs](https://code.claude.com/docs/en/agent-teams) — Agent Teams 多会话协作编排（实验特性）
4. [Claude Code Subagents Guide 2026: Parallel Agents](https://baeseokjae.github.io/posts/claude-code-subagents-guide-2026/) — 子代理隔离上下文模型与并行实践详解
5. [Claude Code Subagents and Multi-Agent Orchestration Guide](https://hidekazu-konishi.com/entry/claude_code_subagents_and_orchestration_guide.html) — 多代理编排与委派模式的工程化经验
> [!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 等场景全覆盖。
