<!-- title: 自定义Subagent三步成军 -->

# 自定义 Subagent 三步成军：把 Claude Code 训成你的专属专家团队

## 概述

本教程面向已经会用 Claude Code 基础交互、想让 AI 真正"分工协作"的开发者。你将学会在 `.claude/agents/` 下用一份 Markdown 文件定义一个"专家 Agent"——它拥有独立的上下文窗口、受限的工具集、专属的模型与记忆，能在主会话里被自动委派或显式召唤。学完后你能为仓库搭建一支各司其职的 Agent 团队，让主对话始终保持干净专注。

## 前置条件

- 已安装 Claude Code（本教程以 v2.1.x 为基准，文中特性标注了具体最低版本）
- 一个 Git 仓库作为演练场（用于演示 `worktree` 隔离与项目级 Agent）
- 了解 YAML frontmatter 基本语法
- 终端能正常运行 `claude` 命令

## 一、Subagent 到底解决了什么问题

先厘清一个常见误解：很多人把 Subagent 等同于"再开一个 Claude 窗口"。其实它的核心价值是**上下文隔离**与**能力收敛**。

当你在主会话里让 Claude"跑一遍测试套件并分析失败原因"，成百上千行日志会直接灌进主上下文，把后续的对话质量拖垮。Subagent 的做法是：把这类"高噪音、低复用"的任务甩给一个独立的工作者，它在自己干净的上下文里把活干完，只把**摘要**交回主会话。

更进一步，你可以为这个工作者设定：
- 只能读、不能写（`tools` 白名单）
- 用更便宜的模型（`model: haiku`）
- 记住跨会话的项目经验（`memory`）
- 套用一个专家人格（Markdown 正文即系统提示）

Claude Code 自带三个内置 Subagent，理解它们就理解了自定义的模板：

| 内置 Agent | 模型 | 工具 | 用途 |
| :-- | :-- | :-- | :-- |
| `Explore` | Haiku | 只读 | 快速搜索/理解代码库，**跳过** CLAUDE.md 与 git 状态，省时省钱 |
| `Plan` | 继承主会话 | 只读 | 计划模式下做代码库调研 |
| `general-purpose` | 继承主会话 | 全部工具 | 既要探索又要改动的复杂多步任务 |

关键细节：**`Explore` 和 `Plan` 是仅有的两个会跳过 `CLAUDE.md` 和 git 状态的 Agent**，目的是保持调研轻量。你自定义的 Agent 默认都会加载 CLAUDE.md 全层记忆——这是后面调优的要点。

## 二、第一份 Subagent：从手写到首次触发

### 2.1 选对作用域（Scope）

Subagent 是带 YAML frontmatter 的 Markdown 文件，放哪儿决定了它能被谁看到。优先级从高到低：

| 位置 | 作用域 | 优先级 |
| :-- | :-- | :-- |
| 托管设置（managed settings） | 全组织 | 1（最高） |
| `--agents` CLI 参数 | 仅本次会话 | 2 |
| `.claude/agents/` | 当前项目 | 3 |
| `~/.claude/agents/` | 你所有项目 | 4 |
| 插件的 `agents/` 目录 | 插件启用处 | 5（最低） |

实战建议：**项目专属 Agent 放 `.claude/agents/` 并提交到 Git**，团队共享；跨项目通用的私人 Agent 放 `~/.claude/agents/`。同名时高优先级覆盖低优先级；同一作用域内出现重名，Claude Code 会静默保留一个、丢弃另一个且不告警——所以务必保证 `name` 全树唯一。

### 2.2 手写第一个文件

在仓库根目录创建 `.claude/agents/bug-hunter.md`：

```markdown
---
name: bug-hunter
description: 只读的代码缺陷与安全隐患猎人。在写完或改动代码后立即使用（use proactively）。聚焦可读性、重复逻辑、错误处理、密钥泄露与输入校验。
tools: Read, Grep, Glob, Bash
model: inherit
---

你是一位资深代码审查者，确保高质量与安全。被调用时：

1. 运行 `git diff` 查看最近改动
2. 聚焦被修改的文件，立即开始审查
3. 按优先级给出反馈：致命问题（必须修）、警告（应当修）、建议（可改进）
4. 每条结论附上具体位置与最小修复示例

你只能读不能改。不要给出"已修复"之类的承诺。
```

只有 `name` 和 `description` 是必填项。`tools` 不写则继承主会话全部工具；这里显式收窄到四个只读工具，**天然禁止写文件**。

### 2.3 一个关键陷阱：改了磁盘文件不生效

Subagent 在**会话启动时**加载。如果你直接在磁盘上新建或修改了 `.md` 文件，必须**重启会话**才会被加载。只有通过 `/agents` 交互界面创建或编辑的，才会即时生效、无需重启。

### 2.4 三种触发方式（从弱到强）

```mermaid
flowchart LR
    A[你的任务] --> B{触发方式}
    B -->|自然语言| C[Claude 自行决定是否委派]
    B -->|@提及| D[强制指定该 Agent 跑一次]
    B -->|--agent 会话级| E[整场会话都用它的人格]
    C --> F[bug-hunter 独立上下文工作]
    D --> F
    E --> F
    F --> G[仅把摘要交回主会话]
```

**自然语言**：在描述里点出 Agent 名字即可，无特殊语法：

```
用 bug-hunter 审一下 auth 模块的最近改动
```

**@提及**：输入 `@` 从自动补全里挑出 `bug-hunter (agent)`，或手敲 `@agent-bug-hunter`。这保证指定的 Agent 一定跑，而非交给 Claude 自行判断。

**会话级**：用 `--agent` 启动，整场会话的主线程直接换上该 Agent 的人格、工具限制与模型：

```bash
claude --agent bug-hunter
```

此时它的系统提示**完全替换**默认的 Claude Code 系统提示（和 `--system-prompt` 同理），但 CLAUDE.md 与项目记忆照常加载。想把某个 Agent 设为项目默认，写入 `.claude/settings.json`：

```json
{ "agent": "bug-hunter" }
```

CLI 参数优先于该设置。

**预期结果**：触发后，主会话出现一个 Agent 面板，`bug-hunter` 在独立上下文里跑 `git diff`、读文件、分析，结束后只把按优先级整理的清单返回主对话——主上下文里看不到它读取的几千行代码。

## 三、配置项全景：把专家调到恰到好处

### 3.1 frontmatter 字段速查

| 字段 | 必填 | 作用 |
| :-- | :-- | :-- |
| `name` | 是 | 唯一标识，小写+连字符；Hooks 里以 `agent_type` 收到此值 |
| `description` | 是 | 告诉 Claude **何时**委派——写清楚触发场景 |
| `tools` | 否 | 工具白名单；省略则继承全部 |
| `disallowedTools` | 否 | 黑名单，**先于 `tools` 生效** |
| `model` | 否 | `sonnet`/`opus`/`haiku`/`fable`/完整 ID/`inherit`，默认 `inherit` |
| `permissionMode` | 否 | `default`/`acceptEdits`/`auto`/`dontAsk`/`bypassPermissions`/`plan` |
| `maxTurns` | 否 | 最大轮次上限，防失控 |
| `skills` | 否 | 启动时**预注入**完整 Skill 内容到上下文 |
| `mcpServers` | 否 | 给该 Agent 专属的 MCP 服务器 |
| `hooks` | 否 | 仅在该 Agent 活跃时触发的生命周期钩子 |
| `memory` | 否 | 持久记忆：`user`/`project`/`local` |
| `effort` | 否 | `low`/`medium`/`high`/`xhigh`/`max` |
| `isolation` | 否 | `worktree`——在临时 git worktree 里跑 |
| `background` | 否 | `true` 则总是后台运行 |
| `color` | 否 | 列表里的显示颜色 |
| `initialPrompt` | 否 | 作为主会话 Agent 时自动提交的首轮 |

### 3.2 模型路由：把便宜留给杂活，把贵留给难题

模型解析优先级（从高到低）：

1. 环境变量 `CLAUDE_CODE_SUBAGENT_MODEL`
2. 单次调用传入的 `model` 参数
3. Agent 文件里的 `model` 字段
4. 主会话的模型

典型搭配：搜索/探索类 Agent 用 `haiku` 求快求省；深度安全审计、架构推理用 `opus`；写测试、补文档这类中等任务用 `sonnet`。

### 3.3 工具收窄的两种姿势

白名单（只给这几个）：

```yaml
tools: Read, Grep, Glob, Bash
```

黑名单（继承全部，只摘掉写操作）：

```yaml
disallowedTools: Write, Edit
```

两者同设时，**先扣黑名单、再用白名单从剩余池里筛**。MCP 工具支持通配：`mcp__github` 移除整个 github 服务的工具，`mcp__*` 移除所有 MCP 工具。

注意几个**永远不可用**的工具，即便写进 `tools` 也没用：`AskUserQuestion`、`EnterPlanMode`、`ScheduleWakeup`、`WaitForMcpServers`，以及非 plan 模式下的 `ExitPlanMode`——因为它们依赖主会话的交互态。

### 3.4 常见问题与对策

**Q：Agent 改完代码后我才发现它跑偏了，怎么挽回？**
设 `isolation: worktree`，让它在临时 worktree（默认从默认分支拉）里改，主工作区不受污染；不改文件还会自动清理。

**Q：Agent 总被委派，但我希望它只在特定场景出现。**
问题出在 `description` 太宽泛。改成带明确触发词与示例的描述（参考下文实战案例的写法），并去掉 `use proactively`。

**Q：怎么彻底关掉某个内置 Agent？**
在 settings 里禁用：`"permissions": { "deny": ["Agent(Explore)"] }`，或命令行 `claude --disallowedTools "Agent(Explore)"`。要禁用全部内置、只留自定义，设 `CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS=1`。

## 四、实战案例：为仓库组建「PR 质量三人组」

下面搭一支三个 Agent 的流水线：`bug-hunter`（只读查缺陷）→ `security-sentinel`（深度安全审计）→ `test-scaffolder`（补测试骨架）。三者都放进 `.claude/agents/` 并提交 Git。

### 4.1 1 号：bug-hunter（只读、继承模型）

即上文 2.2 的文件，此处略。

### 4.2 2 号：security-sentinel（opus、带项目级记忆）

`.claude/agents/security-sentinel.md`：

```markdown
---
name: security-sentinel
description: 深度安全审计专家。当任务涉及认证、加密、权限校验、外部输入处理，或怀疑存在注入/越权/密钥泄露时使用。优先用 opus 做推理密集型分析。
tools: Read, Grep, Glob, Bash
model: opus
memory: project
color: red
---

你是安全审计专家。被调用时：

1. 先查阅你的 agent memory（`.claude/agent-memory/` 下），核对历史踩过的坑
2. 审计输入校验、鉴权链路、密钥硬编码、SQL/命令注入、反序列化
3. 给出风险等级、可利用路径、最小修复方案
4. 审计结束把新发现的模式与高危位置写入 memory，沉淀为项目知识

绝不臆测 API 细节——拿不准就明确标注"需验证"。
```

`memory: project` 会在 `.claude/agent-memory/security-sentinel/` 下建持久目录，自动启用 Read/Write/Edit 并注入 `MEMORY.md` 前 200 行（或 25KB）。随用随记，团队通过 Git 共享审计经验。

### 4.3 3 号：test-scaffolder（sonnet、可写、加 PostToolUse 钩子）

`.claude/agents/test-scaffolder.md`：

```markdown
---
name: test-scaffolder
description: 测试骨架生成器。为指定函数/模块生成可运行的单元测试骨架，遵循仓库现有测试风格。
tools: Read, Grep, Glob, Edit, Write, Bash
model: sonnet
hooks:
  PostToolUse:
    - matcher: "Edit|Write"
      hooks:
        - type: command
          command: "./scripts/run-linter.sh"
---

你专注写测试。被调用时：

1. 找到目标函数及其现有测试，复刻命名与断言风格
2. 覆盖正常路径、边界值、错误分支
3. 生成后运行 `npm test`（或等价命令）确认骨架可跑通
4. 失败就修到通过为止，只动测试文件
```

frontmatter 内的 `hooks` 只在该 Agent 活跃时触发；这里在每次写文件后自动跑 linter。注意：插件来源的 Agent 会忽略 `hooks`、`mcpServers`、`permissionMode` 三项——需要它们就放进 `.claude/agents/` 而非插件。

### 4.4 串联成一条流水线

主会话里一句话编排：

```
先用 bug-hunter 找出 auth 改动里的缺陷，再用 security-sentinel 做深度安全审计，
最后用 test-scaffolder 为新加的鉴权函数补测试骨架
```

每个 Agent 干完把摘要交回主会话，主会话再把相关上下文递给下一个。主上下文里只剩三段精炼结论，而不是三个 Agent 各自读取的成千上万行代码。

### 4.5 用 CLI JSON 做一次性临时 Agent

不想落盘、只想临时跑一次（比如 CI 脚本里），用 `--agents` 传 JSON：

```bash
claude --agents '{
  "log-triage": {
    "description": "日志分诊专家，从测试输出里提炼失败原因。",
    "prompt": "你是日志分诊专家。从给定的日志中提取失败的用例、错误类型、可疑堆栈，按优先级输出清单。",
    "tools": ["Read", "Grep", "Bash"],
    "model": "haiku"
  }
}'
```

`--agents` 支持的全部字段与文件版一致（`description`/`prompt`/`tools`/`disallowedTools`/`model`/`permissionMode`/`mcpServers`/`hooks`/`maxTurns`/`skills`/`initialPrompt`/`memory`/`effort`/`background`/`isolation`/`color`），其中 `prompt` 等价于文件版的 Markdown 正文。

## 五、进阶：记忆、嵌套、Fork 与后台

### 5.1 给 Agent 装上持久记忆

`memory` 三档：

| 作用域 | 位置 | 何时用 |
| :-- | :-- | :-- |
| `project` | `.claude/agent-memory/<name>/` | 默认推荐，可随 Git 团队共享 |
| `user` | `~/.claude/agent-memory/<name>/` | 跨项目通用经验 |
| `local` | `.claude/agent-memory-local/<name>/` | 项目专属但不入版本库 |

记忆要主动维护——在正文里写明"完成任务后把学到的写入 memory"。也可以在主对话里点名提示它："审查这个 PR 前先翻翻你 memory 里记过的模式。"

### 5.2 嵌套 Subagent（v2.1.172+）

一个 Subagent 可以再生子 Subagent。比如审查者发现 5 个隐患，可以为每个隐患各派一个验证者并行复核，中间产物全不进主会话，只有顶层摘要回流。深度上限固定为 5 层（深度 5 的 Agent 不再获得 Agent 工具，不可再嵌套）；不想让它生崽就从 `tools` 拿掉 `Agent` 或加入 `disallowedTools`。

### 5.3 Fork：复用主上下文的分支（v2.1.117+）

普通 Subagent 从零起步，Fork 则**继承当前整段对话**——系统提示、工具、模型、历史全和主会话一致，因此首轮可复用主会话的 prompt cache，比新开一个更省。适合"在当前基础上分头试两种方案"。`CLAUDE_CODE_FORK_SUBAGENT=1` 开启，开 `/fork 起草解析器的单测` 即可派生一个后台分支。Fork 不能再生 Fork。

### 5.4 前台 vs 后台

前台 Subagent 阻塞主对话，权限提示会透传给你；后台 Subagent 并发跑，用会话已授的权限，**遇提示则自动拒绝**。想让任务后台化：直接说"在后台跑这个"，或对运行中的任务按 `Ctrl+B`。`CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1` 可彻底关闭后台能力。

## 六、整体工作流架构

```mermaid
flowchart TB
    subgraph 主会话["主会话（保持干净）"]
      U[你的指令]
    end

    U --> D{委派决策}
    D -->|自动/自然语言| A1
    D -->|@提及/必跑| A2
    D -->|--agent 整场| A3

    subgraph Agents["独立上下文 Agent 团队"]
      A1[bug-hunter<br/>只读·继承]
      A2[security-sentinel<br/>opus·memory:project]
      A3[test-scaffolder<br/>sonnet·可写·PostToolUse钩子]
    end

    A2 -.沉淀经验.-> MEM[(agent-memory)]
    A1 --> R1[缺陷清单]
    A2 --> R2[风险报告]
    A3 --> R3[测试骨架]
    R1 & R2 & R3 -->|仅摘要回流| U
```

## 七、Subagent vs Skill vs CLAUDE.md：别用错

| 工具 | 跑在哪 | 何时选 |
| :-- | :-- | :-- |
| **CLAUDE.md** | 主会话，启动常驻 | 短小、恒真的项目规约（如"提交前跑 lint"） |
| **Skill** | 主会话内，按需注入 | 可复用的富工作流（常带参考文件/脚本） |
| **Subagent** | **独立上下文窗口** | 高噪音任务、需工具/权限收窄、需专属模型 |

一句话决策：任务会产出大量日志/搜索结果且你之后不再引用 → Subagent；想每次都让 Claude 自动套用某套规范 → CLAUDE.md 或 Skill。

## 延伸阅读

- **Anthropic 官方文档** — 订阅 `https://code.claude.com/docs/llms.txt` 获取完整文档索引，Subagent、Hooks、Plugins、Agent SDK 各成一页
- **Background agents 与 Agent teams** — 当你需要并行多会话或让 Agent 互相通信时，Subagent 已不够用，转向上游文档
- **`/agents` 命令的 Running/Library 双标签** — 可视化管理、查看正在运行的 Agent 树、`(+N)` 后代计数
- **`CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`** — 开启后可用 `SendMessage` 凭 agent ID 续跑已停止的 Subagent（内置 Explore/Plan 是一次性的，无 ID，不可续）

## 训练营适用性评估

- **适合类型**：企业研发效能训练营、DevOps 自动化训练营、AI 编程进阶营。学员需先掌握 Claude Code 基础交互与 CLAUDE.md 配置
- **教学时长**：建议 3 课时。第 1 课时讲透"上下文隔离"动机与三大内置 Agent；第 2 课时手搓三人组并跑通触发链路；第 3 课时进阶记忆、Fork、嵌套与 CI 临时 Agent
- **可验收产出**：每个学员/小组为自己的真实仓库提交一组 `.claude/agents/*.md`，并在 PR 流程里演示"主会话一句话、三人组自动接力、主上下文保持干净"的完整闭环

## 参考来源

1. [Create custom subagents — Claude Code Docs](https://code.claude.com/docs/en/sub-agents) — 官方权威文档，覆盖 frontmatter 全字段、作用域优先级、内置 Agent、记忆、Fork、嵌套等全部特性
2. [Claude Code Customization Guide (2026): CLAUDE.md vs Skills vs Subagents — alexop.dev](https://alexop.dev/posts/claude-code-customization-guide-claudemd-skills-subagents/) — 用同一问题对比四种定制方式，给出清晰决策矩阵
3. [Build a Claude Code Custom Subagent: Step-by-Step Guide — Digital Applied](https://www.digitalapplied.com/blog/build-claude-code-custom-subagent-step-by-step-2026) — 从 `.claude/agents/` Markdown 到首次触发的可复制实战示例
4. [Claude Code Subagents: A 2026 Practical Guide — Tembo](https://www.tembo.io/blog/claude-code-subagents) — 委派、隔离、摘要回流机制与并行研究的工程实践

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