2026-08-18·技能与命令

Claude Code Subagents 2026 实战——五个 scope 优先级（managed / CLI flag / / 用户 / plugin）、完整 frontmatter 字段、built-in agent 选型、background vs foreground 调度、上下文隔离与 SendMessage 复用、嵌套深度与并发限制，以及 worktree + background 组合的 2026 新坑。

Claude Code Subagents 全攻略：并行研究、定向工具、子任务三层嵌套（2026）

Q: subagent 与普通 Bash 调用的区别是什么？

Bash 调用是同 context 内的一次工具使用——主 agent 直接看到结果，token 计入主会话。Subagent 是独立 context 的另一个 Claude——有自己的 system prompt、可配独立工具集、有自己的 maxTurns 限制。区别一句话：Bash 是「让 Claude 跑命令」；subagent 是「让另一个 Claude 跑任务」。

Q: 应该把 subagent 放项目级还是用户级？

团队共享放项目级（.claude/agents/*.md，提交到 git）；个人跨项目放用户级（~/.claude/agents/）。关键判断——如果团队成员都用该 subagent，把它放项目级；如果只你用，放用户级避免噪音。MDM 层由公司 IT 配置，个人无法绕过。

Q: 子任务能嵌套到第几层？

默认 3 层（CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH=3）。设大了 token 会爆炸（每层都加载独立 context）——除非你明确需要 subagent 内部再 spawn subagent，否则用默认。深嵌套调试也极难（需要 trace 多层 SendMessage 调用栈）。

Q: Background subagent 跑挂了怎么拿结果？

三种方式：1) claude --debug 启动时打印 SendMessage 状态；2) 用 Task 工具显式 resume agent_id 看历史；3) subagent 自己的 isError 返回值会写到日志。最稳的方式：在 initialPrompt 里让 subagent 把关键中间结果写到 scratch 文件，主会话事后从文件读——不依赖 SendMessage。

Q: subagent 的 description 字段怎么写才容易被主 agent 选中？

description 是主 agent 决定「要不要委派给这个 subagent」的唯一路由依据。写法要点：包含触发场景与例句（如 triggers on "review my changes"）、点明工具/视角差异（read-only 调研 vs 可写修改）、写清何时不该用。避免 "helps with tasks" 这类放之四海皆准的描述——主 agent 读不出路由信号，subagent 就形同虚设。

Q: 多个 subagent 之间怎么共享状态？

默认互相不可见——上下文隔离是设计。推荐的共享层是文件：每个 subagent 把结论写到 scratch/ 下的独立文件，主 agent 读文件、提炼要点、再编进下一个 subagent 的 initialPrompt。SendMessage 适合点对点传消息，不适合当共享存储用。把编排逻辑放在主 agent，把隔离留给 subagent，是多 agent 协作的稳定结构。

Claude Code 的 subagent（子代理） 机制是 2025-Q4 推出、2026 年全面成熟的核心能力——让你在主会话之外启动独立 context window的 agent，每个都有自己的 system prompt、工具白名单、可调用父 agent。subagent 不是简单函数调用，而是「让 Claude 在隔离环境里跑完一个子任务、把结果回传」的设计。本文基于 Claude Code Subagents 官方文档，讲清楚：5 个 scope 优先级、完整 frontmatter 字段、built-in agents 差异、background vs foreground 模式、上下文隔离与 SendMessage 复用、嵌套深度限制，以及 2026 年最常见的踩坑。

TL;DR

Subagent = 独立 context window 的小 Claude，可定向工具、可被父 agent 调用

五个 scope 优先级：managed (MDM) > --agents flag > .claude/agents/ (项目) > ~/.claude/agents/ (用户) > plugin

Skills 字段在 subagent 启动时把 SK SKILL.md 全文注入到子上下文（不仅 description）

嵌套深度上限：CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH（默认 3）+ 并发上限 20

SendMessage resume 可复用同一 agent ID 保留完整历史

2026 年新坑：isolation: worktree + background: true 组合的实际语义

五个 scope 优先级：subagent 从哪里加载

Claude Code Subagents 文档定义了五个 scope，按优先级排序：

| Scope | 路径 | 用途 | 优先级 | |---|---|---|---| | managed | MDM 推送 / 组织 settings | 公司强制 subagent 模板 | 最高 | | CLI flag | claude --agents '{"name": {...}}' | 一次性 / 临时 subagent | 高 | | 项目级 | <project>/.claude/agents/*.md | 团队 subagent 模板，提交到 git | 中 | | 用户级 | ~/.claude/agents/*.md | 个人跨项目 subagent | 低 | | plugin | 插件贡献的 subagent | 第三方包提供 | 中 |

合并规则：与 CLAUDE.md 记忆、.mcp.json 一致——高优先级覆盖低优先级。同一 name 出现多次时取最高层。这意味着一支团队的 subagent 模板可以由公司 MDM 强制——个人无法绕过。

实战选择：

个人实验 / 临时探索 → CLI flag 或用户级
团队共享（PR reviewer、文档维护者）→ 项目级 .claude/agents/
跨多个项目可复用 → 用户级
公司强制 → managed (MDM)

完整 frontmatter：subagent 的全部字段

subagent 本质是 .md 文件带 YAML frontmatter。下面是 Subagents 规范的全部字段：

---
name: pr-reviewer
description: Reviews pull requests for the team — triggers on "review my changes" or auto-loads when a PR URL is mentioned.
tools: Read, Grep, Bash(git diff:*), Bash(gh pr diff:*)
disallowedTools: Edit, Write, NotebookEdit
model: claude-sonnet-4-5
permissionMode: bypassPermissions
maxTurns: 20
skills:
  - code-review
  - security-checklist
mcpServers:
  - github
isolation: worktree
background: true
effort: medium
color: cyan
initialPrompt: "Review the staged changes against references/checklist.md."
---

# PR Reviewer

You are a meticulous reviewer. Always check the security checklist first.
When you find a blocker, escalate to the parent agent via SendMessage.

关键字段释义：

tools / disallowedTools：工具白名单 / 黑名单——比 allowed-tools（skill 维度）更细
model：指定 subagent 用的模型——sonnet、haiku、具体 ID 都可
permissionMode：四个值 default / acceptEdits / plan / bypassPermissions，与主 Claude Code 一致
maxTurns：最大工具调用轮数——超过会被强制结束（防 runaway）
skills：要 preload 的 SKILL.md 列表（全文注入，不是仅 description）
mcpServers：subagent 能调的 MCP server 列表
isolation: worktree：在独立 git worktree 跑（隔离文件系统修改）
background: true：启动后立即返回 agent ID，主会话不阻塞
effort：模型推理 effort（low / medium / high）
color / initialPrompt：UI 颜色与首句 prompt

Built-in agents 差异：不要重复造轮子

Claude Code 自带几个 built-in subagent。理解它们的差异才能选对：

| Built-in | 工具范围 | 何时自动触发 | 何时手动调用 | |---|---|---|---| | Explore | Read, Grep, Glob（只读） | 用户说「find files / / search for / /」 look up | Task 工具 + subagent_type: Explore | | Plan | Read, Grep + Bash(read-only) | 用户说「plan / / 计划 / / design」 | Task 工具 + subagent_type: Plan | | General-purpose | 全部工具（无限制） | 通用回退 | Task 工具 + subagent_type: general-purpose | | statusline-setup | Edit（项目内） | 用户说「statusline / / status bar」 | 自动 | | Explore (Explore subagent_type) | Read, Grep, Glob | 用户说「explore / / explore codebase」 | 自动 |

易错点：写 general-purpose 比 Explore 多消耗 token——前者加载全工具进上下文，后者只加载 Read/Grep/Glob。只在 Explore 无法满足时再用 general-purpose。

Background vs Foreground：调度哲学

Claude Code v2.1.198 起 subagent 默认 background: true——启动后立即返回 agent ID，主会话不阻塞。两种模式的实际行为：

Foreground (background: false)：主会话阻塞，等 subagent 完成才继续。结果同步可见，但期间主 agent 不能干别的。
Background (background: true)：subagent 在后台跑，主会话继续。通过 SendMessage 拿结果——可以在 subagent 跑期间让主 agent 处理其他任务。

实战模式：

单步调研（找文件、读模块）→ Foreground，因为结果要立刻用
长时间任务（PR 评审、批量分析）→ Background，让主 agent 同时干别的
多 subagent 并行 → 多个 Background 同时跑，主 agent 编排

Ctrl+B（toggle background）可以临时切换——见 Claude Code 状态栏。

上下文隔离与 SendMessage 复用

subagent 跑在独立 context：它看不到主会话历史，看不到其它 subagent 上下文。/compact 主会话不会压缩 subagent 的，反之亦然。这意味着：

subagent 默认拿不到主 agent 的会话历史——它看到的只是 initialPrompt + 自己的工具结果
forks skill 借用指定 agent 的 system prompt，让 subagent 看到一致的角色定义
SendMessage 在多 subagent 之间通信——传数据 + 协调决策

SendMessage resume 复用：传同一 agent_id，subagent 保留完整历史继续对话。适用场景：多轮协作（subagent 探索代码 → 你 review → subagent 改）+ 长跑任务的持续推进。

嵌套深度与并发限制

Claude Code Subagents 文档定义：

CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH：嵌套深度上限，默认 3（subagent 自己可以再 spawn subagent，最多 3 层）
单个主会话内 subagent 并发上限：20 个同时活跃

坑 1：嵌套过深。Agent A spawn B、B spawn C、C spawn D——D 看到的上下文是 D 自己的 + C 传过来的，已经丢掉主会话信息。实战：尽量让 subagent 是「叶子」（不递归 spawn），复杂协作由主 agent 编排。

坑 2：并发超 20。超出后新的 Task 调用会排队等空闲 slot——不报错但延迟高。实战：把大任务拆成多个 Background 任务时，确认并发数 < 10，给主会话留 space。

坑 3：isolation: worktree 与 background: true 组合。2026 年新坑——worktree 模式下每个 subagent 跑在独立 git worktree，但 worktree 与 main 分支的 diff 不会自动合并。你需要显式 git merge 才能把 subagent 的改动合回主线。

常见坑与反模式

五个高频坑，按「现象 → 原因 → 修法」拆解——全部来自真实团队的踩坑复盘：

坑 1：description 写得太泛，subagent 永远不被触发。 现象：定义了 subagent，主 agent 却总是自己动手。原因：description 是主 agent 的路由依据——写 "helps with code tasks" 这种泛泛描述，主 agent 无法判断何时该委派。修法：description 里写明触发场景 + 例句（如 triggers on "review my changes"），并写清「何时不该用」。

坑 2：工具白名单漏掉 Read，subagent 开始瞎编。 现象：reviewer subagent 的结论与代码对不上，编造不存在的函数。原因：tools 只给了 Grep 没给 Read——模型只能靠 grep 结果的碎片猜文件全貌。修法：白名单永远包含 Read，并配合 disallowedTools 做减法而不是把 tools 收得太窄。

坑 3：background 模式下忙等轮询。 现象：主 agent 启动 background subagent 后立刻 SendMessage 问「好了吗」，连续占用轮次。原因：不了解 background 的返回时机。修法：主 agent 在 subagent 跑期间先做其他独立任务，收到完成通知再 resume 收结果；如果结果必须立刻用，直接用 foreground。

坑 4：把 subagent 之间的状态共享寄望于「内存」。 现象：两个 subagent 的产出对不上号，第二个不知道第一个干了什么。原因：上下文隔离是设计而非 bug——subagent 彼此不可见。修法：让 subagent 把结果写到文件（scratch 目录 / JSON / YAML），主 agent 读文件后把关键事实编进下一个 subagent 的 initialPrompt。

坑 5：isolation: worktree 以为改动会自动合并。 现象：subagent 报告「已完成修改」，主线分支上却什么都没有。原因：worktree 模式下改动留在独立 worktree 的分支上。修法：把「完成后输出 worktree 分支名」写进 subagent 的输出契约，由主 agent 或人显式 git merge。

实战案例：两个生产级编排

案例 A：并行代码调研团队（1 主 + 3 探索 + 1 汇总）。 场景：接手陌生大仓库，主 agent 要在几分钟内产出架构综述。编排方式：主 agent 派 3 个 Explore 型 subagent（read-only、Foreground 或并行 Background），分别调研「数据层」「服务层」「入口与配置」；每个 subagent 把发现写到 scratch/research-*.md；主 agent 读三份文件，把要点合成最终综述。

分工表（主 agent 实际下发的内容）：

| Subagent | 调研范围 | 输出到 | |---|---|---| | Explore #1 | src/db/、schema、migration | scratch/research-data.md | | Explore #2 | src/services/、RPC 边界 | scratch/research-services.md | | Explore #3 | 入口、路由、环境配置 | scratch/research-entry.md |

为什么这么设计：Explore 型工具集只含 Read/Grep/Glob，比 general-purpose 省 token；文件是共享层，绕开了「subagent 互相看不见」的限制；主 agent 最后只读三份摘要，不把三个 subagent 的原始输出灌进自己的上下文。

案例 B：PR 评审 subagent 的输出契约。 角色定义解决「怎么审」，输出契约解决「主 agent 怎么可靠地消费评审结果」。在 subagent 的 system prompt 里固定 verdict 枚举：

# PR Reviewer（system prompt 节选）

For every finding, output exactly one block:

VERDICT: BLOCKER | WARNING | NIT
FILE: <path>:<line>
ISSUE: <one sentence>
FIX: <suggested change, one sentence>

End with: SUMMARY: <BLOCKER count> blockers, <WARNING count> warnings.

主 agent 解析 SUMMARY 行即可决定下一步——0 blocker 自动通过、有 BLOCKER 则 SendMessage resume 让 reviewer 细化。关键点：把「自由文本评审」收敛成「枚举 + 计数」，主 agent 的后续决策从「读文章」变成「读结构化字段」，这也是 subagent 编排里最容易被忽略的一环。

常见问题

subagent 与普通 Bash 调用的区别是什么？

Bash 调用是同 context 内的一次工具使用——主 agent 直接看到结果，token 计入主会话。Subagent 是独立 context 的另一个 Claude——有自己的 system prompt、可配独立工具集、有自己的 maxTurns 限制。区别一句话：Bash 是「让 Claude 跑命令」；subagent 是「让另一个 Claude 跑任务」。

应该把 subagent 放项目级还是用户级？

团队共享放项目级（.claude/agents/*.md，提交到 git）；个人跨项目放用户级（~/.claude/agents/）。关键判断——如果团队成员都用该 subagent，把它放项目级；如果只你用，放用户级避免噪音。MDM 层由公司 IT 配置，个人无法绕过。

子任务能嵌套到第几层？

默认 3 层（CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH=3）。设大了 token 会爆炸（每层都加载独立 context）——除非你明确需要 subagent 内部再 spawn subagent，否则用默认。深嵌套调试也极难（需要 trace 多层 SendMessage 调用栈）。

Background subagent 跑挂了怎么拿结果？

三种方式：1) claude --debug 启动时打印 SendMessage 状态；2) 用 Task 工具显式 resume agent_id 看历史；3) subagent 自己的 isError 返回值会写到日志。最稳的方式：在 initialPrompt 里让 subagent 把关键中间结果写到 scratch 文件，主会话事后从文件读——不依赖 SendMessage。

subagent 的 description 字段怎么写才容易被主 agent 选中？

description 是主 agent 决定「要不要委派给这个 subagent」的唯一路由依据。写法要点：包含触发场景与例句（如 triggers on "review my changes"）、点明工具/视角差异（read-only 调研 vs 可写修改）、写清何时不该用。避免 "helps with tasks" 这类放之四海皆准的描述——主 agent 读不出路由信号，subagent 就形同虚设。

多个 subagent 之间怎么共享状态？

默认互相不可见——上下文隔离是设计。推荐的共享层是文件：每个 subagent 把结论写到 scratch/ 下的独立文件，主 agent 读文件、提炼要点、再编进下一个 subagent 的 initialPrompt。SendMessage 适合点对点传消息（resume 同一 agent 继续对话），不适合当共享存储用。把编排逻辑放在主 agent，把隔离留给 subagent，是多 agent 协作的稳定结构。

官方参考资料

本文基于截至 2026 年 8 月的 Claude Code v2.1.198+ subagent 规范，相关 API 可能演进；建议每 6 个月查一次规范版本号。