Subagent 是主对话临时召唤出来的独立 Claude 会话，从零开始工作，做完只返回一段结论。适合"上下文隔离"、“独立视角”、"并发处理"三类场景。

目录

• Subagent 是什么
• 和 Skill 的核心差异（图解）
• Subagent 的文件形态
• tools 白名单：能力隔离的落地
• 主对话怎么"召唤" subagent
• description 怎么写才准
• 五个典型应用场景
• 从零建一个 Subagent
• 五个常见坑
• 常见问题

---

Subagent 是什么

用一个非常通俗的例子说清楚：

Subagent 就像"外聘顾问"。

想象你是一家公司的 CEO（主 Claude），日常业务你自己拍板。但遇到需要专业意见时（比如"这份合同法律上有没有风险"），你不会自己啃法律书，而是请一个外聘律师：

• 律师是独立的人，不参与你的日常经营
• 律师从零看合同，不受你之前的商业决策思路影响
• 律师只需要给你一份意见书，不用汇报中间怎么读的、翻了哪些法条
• 你可以同时聘 3 个律师从不同角度看合同（合同法、劳动法、税法）

Subagent 就是这么用的：

• 主 Claude 派它去干专业活
• 它开一个全新的会话上下文，看不到主对话的历史
• 干完只返回一段总结报告
• 可以并发派多个

为什么需要 subagent：有些工作不适合在主对话里做：

1. 会污染主对话的上下文（读了几十个文件后 token 就爆了）
2. 需要"没被主流程带偏"的独立视角
3. 需要同时从多个角度并行处理

---

和 Skill 的核心差异（图解）

用两张流程图对比：

Skill 的执行流程

用户：帮我 review 代码
   ↓
主 Claude：判断匹配 review skill
   ↓
主 Claude：读 skill 说明书
   ↓
主 Claude：在【当前上下文】按步骤做
    - 用 Bash 跑 git diff
    - 用 Read 读几十个改动文件
    - 用 Grep 搜相关代码
    - 逐项检查
   ↓
【上下文里塞满了 diff、文件内容、检查过程】
   ↓
输出 review 结论给用户

之后用户接着说"帮我把这个 bug 修了"
   ↓
主 Claude 继续工作，但上下文里还有 review 时读过的所有东西
   → token 消耗大，且思路容易被 review 带偏

Subagent 的执行流程

用户：帮我 review 代码
   ↓
主 Claude：判断该派 subagent
   ↓
主 Claude：调用 Agent 工具
    传入：subagent_type = "code-reviewer"
         prompt = "review 当前 diff"
   ↓
─────────【新会话，独立上下文】─────────
    Subagent：从零开始
    - 用 Bash 跑 git diff
    - 用 Read 读几十个改动文件
    - 用 Grep 搜相关代码
    - 逐项检查
    - 生成 review 报告
─────────────【会话结束】──────────────
   ↓
主 Claude 收到：一段 review 报告（几百字）
   ↓
【主对话上下文只多了这段报告，几十个文件的原始内容被丢弃】

之后用户接着说"帮我把这个 bug 修了"
   ↓
主 Claude 继续工作，上下文干净，只保留了 review 结论
   → token 消耗小，思路清晰

关键差异：Skill 是"你亲自去做"，Subagent 是"你派人去做，只听汇报"。

---

Subagent 的文件形态

一个 subagent 就是一个 Markdown 文件，非常简单。

位置：

• 项目级：<项目根>/.claude/agents/xxx.md
• 用户级：~/.claude/agents/xxx.md

结构：

---
name: code-reviewer
description: 资深 code review 专家。主动审查代码质量、安全性与可维护性。在编写或修改代码后应立即使用。
tools: ["Read", "Grep", "Glob", "Bash"]
model: sonnet
---

你是资深 code reviewer，负责保证代码质量与安全达到高标准。

## 审查流程

被调用时：
1. 收集上下文 —— 运行 git diff --staged 与 git diff
2. 理解范围 —— 明确改了哪些文件、对应什么功能
3. 阅读周边代码 —— 不要孤立看 diff，读完整文件
4. 按 checklist 审查
5. 输出结论

## 输出格式
...

上半部分是元信息，下半部分是这个 subagent 的 system prompt（角色定位、工作流程、输出格式、约束）。

---

tools 白名单：能力隔离的落地

tools 字段决定这个 subagent 能用哪些工具。有三种写法：

写法 1：白名单（推荐）

tools: ["Read", "Grep", "Glob", "Bash"]

含义：只能用这四个工具。没有 Write / Edit，物理上就不能改文件。

它是"只读不改"的 reviewer，即使 prompt 说"你不许改代码"，用白名单更保险 —— 靠权限而不是靠自觉。

通俗理解：给外聘律师一间只能看合同不能改合同的办公室，比在合同上贴"请勿修改"的便签靠谱。

写法 2：允许写（有针对性）

tools: ["Read", "Write", "Edit", "Bash", "Grep", "Glob"]

含义：能读能写能跑命令。

它不仅要找出安全问题，还要能修，所以给了写权限。

通俗理解：外聘顾问不仅诊断问题，还能动手治病。

写法 3：省略（继承全部）

# 不写 tools 字段

含义：Subagent 能用主对话所有的工具（包括 MCP 工具）。

适合"这个 subagent 就是一个通用助手"的场景。

三种写法的选择

需求	写法
严格审查，不许改	白名单：Read / Grep / Glob / Bash
审查 + 修复	白名单加 Write / Edit
通用调研，不确定用啥工具	省略 tools 字段
只做外部调研，不接触代码	白名单：WebFetch / WebSearch / Read

核心心智：能不给的工具就不给。工具越少 subagent 越可控，也越不容易翻车。

---

主对话怎么"召唤" subagent

Subagent 不会自己冒出来，得由主 Claude 用 Agent 工具去召唤。有两种触发路径：

路径 A：Claude 自主判断（大多数场景）

流程：

1. 用户说"帮我 review 一下代码"
2. 主 Claude 扫描所有可用 subagent 的 description
3. code-reviewer 的 description 匹配上（“审查代码质量”）
4. 主 Claude 调 Agent 工具：subagent_type: "code-reviewer", prompt: "review 最近的 diff"
5. Subagent 开新会话，独立执行
6. 主 Claude 收到 subagent 的结论，转达给用户

关键点：主 Claude 靠什么判断调哪个？靠 description。所有可用 subagent 的 name + description 都会被塞进主 Claude 的 system prompt 里，主 Claude 根据用户说的话做匹配。

路径 B：用户显式指定

用户直接说"用 code-reviewer agent 检查这个"，或者绑一个 slash command /review 内部就是调这个 agent。这种情况主 Claude 不判断，直接执行。

---

description 怎么写才准

好的 description 决定 subagent 能不能被主 Claude 稳定召唤。

差 vs 好的对比

❌ 差写法：

description: 帮忙 review 代码

主 Claude 看到这句，只知道"这东西是审代码的"，但不知道什么时候该调它。用户随便说个"看看这段代码"可能都不匹配。

✅ 好写法（实际写法）：

description: 资深 code review 专家。主动审查代码质量、安全性与可维护性。在编写或修改代码后应立即使用。所有代码变更都必须经过本 agent。

分析这段为什么好：

• 说清做什么：“审查代码质量、安全性与可维护性”
• 说清用它的时机：“在编写或修改代码后应立即使用”
• 给出强触发信号：“所有代码变更都必须经过本 agent”

主 Claude 看到"用户刚改完代码"这个上下文，会主动想起"该调 code-reviewer 了"。

description 的三层结构

一个稳定的 description 通常包含三层：

{角色/能力} + {做什么} + {什么时候用}

举例：

安全漏洞发现与修复专家。（角色）
在处理用户输入、认证、API endpoint、敏感数据等代码编写后应主动使用。（时机）
可标出 secrets、SSRF、injection、不安全 crypto 及 OWASP Top 10 类问题。（能做什么）

三层都齐全，触发就稳定。

触发词的使用

想让 subagent 被主动调用，description 里加明确的时机信号词：

• “在 X 之后应立即使用”
• “主动使用于 Y 场景”
• “所有 Z 类变更都必须经过本 agent”

---

五个典型应用场景

场景 1：代码审查（最经典）

痛点：Claude 写完代码马上审自己写的，容易漏问题；且审查过程会读很多文件，污染上下文。

方案：建 code-reviewer subagent，只读权限，每次代码改动后主动召唤。

为什么用 subagent：

• 独立视角，不被"我刚写的"心理影响
• 上下文隔离，读完文件不留在主对话
• 只返回结论，主 Claude 拿到结论后继续写代码

场景 2：多角度并发分析

痛点：一个复杂改动，想同时从性能、安全、可维护性三个角度看，主 Claude 串行做太慢。

方案：建 perf-reviewer、security-reviewer、quality-reviewer 三个 subagent，主 Claude 并发召唤三个，三份报告一起汇总。

为什么用 subagent：只有 subagent 支持并发，skill 是串行的。

场景 3：深度调研 / 情报收集

痛点：为了解决一个 bug，需要读几十个相关文件、翻 git log、看几个 issue，做完主对话里塞满了资料，之后写代码时干扰严重。

方案：建 investigator subagent，专职调研，输出一份"调研报告"给主 Claude。

为什么用 subagent：读的原始资料不需要保留，只要结论。

场景 4：需要"故意刁难"的对抗视角

痛点：主 Claude 有时太顺从，代码明明有问题也不敢说。

方案：建 critical-reviewer subagent，system prompt 里明确"以有罪推定挑刺，找不到问题算失职"。

为什么用 subagent：主 Claude 有默认的"友好合作"人格，一句"你要挑刺"的 prompt 敌不过整个会话的顺从惯性。开新会话从零建立"挑刺"人格更有效。

场景 5：文档生成 / 报告输出

痛点：让主 Claude 写文档时，它会边写边"回想"上下文里的所有内容，容易跑偏或加入无关信息。

方案：建 doc-writer subagent，只做文档生成，主 Claude 通过 prompt 把必要素材塞给它。

为什么用 subagent：subagent 只知道你塞给它的东西，输出会非常聚焦。

---

从零建一个 Subagent

举例：给我们的 algo_evaluator 项目建一个"数据库变更审查"的 subagent。

步骤 1：想清楚定位

• 做什么：审查 SQL DDL / DML 是否符合规范，是否会影响线上
• 触发时机：涉及 .sql 文件改动、或 prompt 里出现"建表/加字段/删字段/迁移"时
• 需不需要写权限：不需要，只审查不改
• 用什么模型：sonnet（性价比够用）

步骤 2：写文件

.claude/agents/db-change-reviewer.md：

---
name: db-change-reviewer
description: 数据库变更审查专家。审查 SQL DDL/DML 是否符合转转数据库规范，评估变更对线上影响。当涉及建表、加字段、删字段、索引变更、数据迁移等 SQL 相关代码改动后，或用户提到"改表结构"、"加字段"、"迁移数据"时主动使用。
tools: ["Read", "Grep", "Glob", "Bash"]
model: sonnet
---

你是数据库变更审查专家，专注于 MySQL 变更的规范合规性和线上安全。

## 审查流程

被调用时：

1. **收集变更**
   - 用 Bash 跑 `git diff` 看 SQL 文件变化
   - 或用 Grep 定位改动涉及的 SQL 文件

2. **规范检查**
   - 字段命名：snake_case，不能全大写
   - 主键：必须有 `id BIGINT UNSIGNED AUTO_INCREMENT`
   - 时间字段：`create_time` / `update_time` 必须有
   - 索引：区分度低的字段不建单列索引
   - 类型：不用 `TEXT`（用 VARCHAR），字符串默认 `utf8mb4`

3. **线上影响评估**
   - 大表加字段 → 提醒用 pt-online-schema-change
   - 加非空默认值 → 检查是否有历史数据兼容问题
   - 删字段/改类型 → 强 warning，可能导致线上不兼容
   - 大量数据迁移 → 提醒分批做，别一次性锁表

4. **输出报告**

## 输出格式

按严重程度分组：

### 🔴 CRITICAL（必改，否则会翻车）
- 文件:行号
- 问题描述
- 修复建议

### 🟡 WARNING（建议改）
- ...

### 🟢 SUGGESTION（可选优化）
- ...

## 边界

- 只审 SQL 变更，不评价业务逻辑
- 不改代码，只提建议
- 只报置信度 >80% 的真实问题
- 遇到不确定的情况，让主 Claude 找 DBA 确认

## 参考规范

- 转转数据库开发规范（内部 wiki）
- 项目 CLAUDE.md 里的数据库约定（如有）

步骤 3：验证

在 Claude Code 里说"审查一下我这次改的建表 SQL"，看主 Claude 会不会调它；或者直接说"用 db-change-reviewer 审这个"强制触发。

---

五个常见坑

坑 1：description 太宽泛，永远被或永远不被触发

症状：description 写"帮忙写代码"，主 Claude 每次都想调它；或者写"处理各种情况"，主 Claude 不知道什么时候该调。

规避：三层结构写全（角色 + 时机 + 场景），加触发信号词。

坑 2：tools 没给 Bash 却要跑 git 命令

症状：subagent 在 prompt 里写"跑 git diff"，但 tools 里没有 Bash，subagent 卡住说"没这个工具"。

规避：动手前列清楚这个 subagent 要做的动作，反推需要哪些工具。宁可给多不给少，但也不要图省事直接省略 tools 字段。

坑 3：主 Claude 读过的文件 subagent 看不到

症状：主 Claude 读了一堆文件后调 subagent，subagent 说"我看不到你说的那个文件"。

规避：Subagent 是独立上下文，看不到主对话历史。要么：

• 主 Claude 在 prompt 里把关键文件路径/内容带过去
• 让 subagent 自己重新读

坑 4：Subagent 里的 prompt 太模糊

症状：system prompt 只写"你是 reviewer"，subagent 每次审查风格都不一样，有时严有时松。

规避：system prompt 里写清：

• 具体流程步骤
• 检查清单（越具体越好）
• 输出格式模板
• 边界（不做什么）

坑 5：想用 subagent 做需要交互的事

症状：让 subagent 做"边审边问用户 XX 是不是有意为之"，结果 subagent 是一次性输入输出，问不到用户。

规避：需要交互的流程用 Skill，不用 subagent。Subagent 是"一次任务一份报告"，不能中途和用户互动。

---

常见问题

Q1：Subagent 会不会消耗更多 token？

短期看会（因为要重新读文件），长期看反而省（不污染主对话）。经验：

• 短任务（几百 token） → 用 skill
• 中大型调研/审查（几 k token） → 用 subagent 更划算

Q2：一个会话能调多少次 subagent？

没有硬限制。一个会话可能触发 5-10 次不同的 subagent。但每次调用有开销（模型启动、上下文注入），别为了用而用。

Q3：Subagent 能调用 Subagent 吗？

原则上可以（如果给它 Agent 工具），但强烈不推荐。层级嵌套会让调试极难，问题追溯变复杂。保持"主 Claude 调 subagent 一层"就够。

Q4：Subagent 用的是同一个模型吗？

看 frontmatter 里 model: 字段。可以让不同 subagent 用不同模型（比如 architect 用 opus，code-reviewer 用 sonnet）。省略则继承主对话的模型。

Q5：Subagent 的执行过程用户能看到吗？

能看到"进度指示"（比如"正在调用 code-reviewer subagent"），但具体每一步用了什么工具、读了什么文件默认不展开显示（这也是为什么它叫"独立会话"）。最终只能看到 subagent 返回的报告。

Q6：怎么强制主 Claude 调某个 subagent？

三个办法：

1. 用户显式说：“用 code-reviewer agent 检查”
2. 绑 slash command（在 skill 或用户级 command 里定死调用哪个 subagent）
3. description 用硬信号：“所有 X 都必须经过本 agent”

Q7：Subagent 和 MCP server 有什么关系？

不同层次的概念：

• MCP server 提供工具（像扩展一个 Claude 能用的能力，比如查数据库、查 Grafana）
• Subagent 是独立角色（用主 Claude 已有的工具集，或加上 MCP 提供的工具）

一个 subagent 可以用 MCP 工具（如果 tools 里配了），它们不冲突，一起用最强。

---

快速参考卡

┌───────────────────────────────────────────────────────┐
│  Subagent = 独立会话                                  │
│                                                       │
│  最小结构：                                           │
│    .claude/agents/xxx.md                              │
│    ├── frontmatter (name/description/tools/model)     │
│    └── system prompt (角色 + 流程 + 输出格式)         │
│                                                       │
│  三种 tools 写法：                                    │
│    白名单        tools: ["Read", "Grep"]              │
│    部分开放      tools: ["Read", "Edit", "Bash"]      │
│    继承全部      省略 tools 字段                      │
│                                                       │
│  两种触发路径：                                       │
│    主 Claude 判断（靠 description 匹配）              │
│    用户显式召唤（"用 X agent"）                       │
│                                                       │
│  什么时候用 subagent（不是 skill）：                  │
│    - 需要独立上下文（不污染主对话）                   │
│    - 需要独立视角（防止自审自查）                     │
│    - 需要并发（多角度同时看）                         │
│    - 只要结论不要过程                                 │
└───────────────────────────────────────────────────────┘