· CLAUDE-CODE-FEATURE-RADAR · 2026.05.13 · 20 MIN ·

Subagents:Agent tool 调度专家小队

卸载主线 context 的唯一办法 —— subagent 在自己 context 里跑,只把 summary 带回来,主 session 不被污染。 · by 思扬

AI · HERO seed:3520260513 卸载主线 context 的唯一办法 —— subagent 在自己 context 里跑,只把 summary 带回来,主 session 不被污染。

FIG.00 — cover · ai-generated · placeholder

原文:https://code.claude.com/docs/en/sub-agents 官方定位:Specialized AI assistants that handle specific types of tasks. Use one when a side task would flood your main conversation with search results, logs, or file contents you won’t reference again.

🔥 影响力卡片

维度	数据
内置 subagent 数量	3 大主类 + 2 辅助(`Explore`、`Plan`、`general-purpose`、`statusline-setup`、`claude-code-guide`)
加 plugin 后实际能用的	superpowers 套件带来的 process skills + understand-anything 套件 9 个 specialist subagents,叠加内置 5 个,常见配置下接近 15+ 个
5 个 scope 层级	Managed > CLI(`--agents` JSON)> Project(`.claude/agents/`) > User(`~/.claude/agents/`)> Plugin
Frontmatter 字段数	18+ 个(name / description / tools / disallowedTools / model / permissionMode / maxTurns / skills / mcpServers / hooks / memory / background / effort / isolation / color / initialPrompt 等)
persistent memory	`memory: user/project/local` 让 subagent 跨会话沉淀经验(本机 `~/.claude/agent-memory/`)
2.1.63 改名	Task tool → Agent tool(老代码里 `Task(...)` 仍兼容)

🎯 为什么必读

1. Subagent 是 Claude Code 里”卸载主线 context”的唯一办法。

主 session 跟你聊久了,什么都装在里头 — 搜过的文件、读过的 PR、改过的代码、debug 输出。Subagent 把脏活外包出去:它在自己的 context 里跑,只把 summary 带回来。这意味着你的主 context 不被污染。

2. 内置 3 个 subagent 已经覆盖 80% 用例

Subagent	模型	工具	用
`Explore`	Haiku(便宜快)	只读	找文件、grep 代码、扫 codebase
`Plan`	inherit	只读	plan mode 下做调研(防止套娃)
`general-purpose`	inherit	全部	多步任务、要修改代码的活

Explore 是隐藏的省钱秘诀 — 它跑 Haiku,速度快、价格低。每次让主 session 跑 grep 都很贵,但派 Explore 去就便宜得多。

3. 自定义 subagent 让你做”AI 团队”

你能在 ~/.claude/agents/ 写一堆自己的专家:security-reviewer、commit-writer、test-generator — 每个有自己的 system prompt、tools 限制、模型选择、记忆。

一句话总结

Subagent = 一个独立的 Claude session,但被你的主 session 派出去干一件事,跑完只把 summary 返回。可以指定 model、tools、permission mode、preloaded skills,可以持久记忆,可以隔离到独立的 git worktree。

💎 金句墙

★ “Use one when a side task would flood your main conversation with search results, logs, or file contents you won’t reference again.” “当某个支线任务会用搜索结果 / log / 不会再看的文件内容淹没你的主对话时,用 subagent。” —— 🟢 派 subagent 的唯一判断标准 — 不是任务复杂度,是”产物对未来还有用吗”

★ “Subagents cannot spawn other subagents.” “Subagent 不能再派 subagent。” —— 🟢 防止套娃。这条决定了 subagent 树永远只有 2 层 — 主 session + 一层 subagent

★ “Memory: user — Enables cross-session learning.” “memory: user — 启用跨会话学习。” —— 🟢 一个 code-reviewer subagent 装上 memory: user 后,review 完一个项目的发现可以永久积累,下次 review 别的项目时拿来用

📋 核心精读

1. 内置 3 个 subagent — 何时派谁

Explore — Haiku、只读、便宜

What did the auth flow change between v1.2 and v1.3?
→ 主 Claude 派 Explore(thoroughness: medium)
→ Explore 跑 Grep / Read / Glob,自己消化几百行代码
→ 返回 5 句话 summary

派 Explore 的几个信号:

任务以”找…”、“哪里…”、“搜…”开头
你不需要看具体代码,只要结论
想省 token(Haiku 是 Sonnet 的 1/10 价)

Plan — 跟 plan mode 联动

> /plan
> Refactor the database layer.
→ 主 Claude 进入 plan mode (不允许写)
→ 自动派 Plan subagent 调研代码
→ Plan 用只读工具搞清架构
→ Plan 返回结构化分析
→ 主 Claude 基于这个分析,产出 plan
→ 你审 plan,通过后 → 退出 plan mode → 执行

关键防套娃:plan mode 下主 Claude 没有 Edit/Write,但不能再套娃派 Explore — 所以才有 Plan 这个专门的”plan-time 调研员”。

general-purpose — 万金油,多步任务

Implement the OAuth redirect flow including tests and docs.
→ 主 Claude 派 general-purpose(理由:多步 + 要改文件)
→ general-purpose 自己 explore + edit + write test + run test
→ 返回:"完成了,改了 3 个文件,2 个测试通过"

派 general-purpose 的信号:

多步骤
需要写代码
完成后主 Claude 不需要看细节,只要结论

2. 自定义 subagent — 写 markdown 文件就行

mkdir -p ~/.claude/agents

---
name: commit-writer
description: Writes git commit messages following team conventions. Use when user wants to commit but hasn't written a message.
tools: Read, Bash(git diff *), Bash(git log *)
model: haiku
disallowedTools: Write, Edit
---

You write commit messages.

Conventions:
- Imperative mood: "fix bug", not "fixed bug"
- 50 char subject line, 72 char body line
- Group related changes; split unrelated into separate commits
- For my projects: lowercase first letter, no period at end

When invoked:
1. Run `git diff HEAD` to see what changed
2. Run `git log -5 --oneline` to see recent style
3. Propose a message
4. If multi-purpose changes, suggest splitting

主 session 看到 description 自动派(disable-model-invocation 字段适用于 skill 不适用于 subagent — 这里 description 决定路由)。

主动调用:在主 session 输入框里 @commit-writer write a commit。

3. 5 个 scope — 哪儿放定义

位置	优先级	适合
Managed settings	1(最高)	enterprise IT 强制下发
`--agents '{"name":{...}}'` CLI flag	2	一次性测试
`.claude/agents/<name>.md`	3	项目共享(进 git)
`~/.claude/agents/<name>.md`	4	个人所有项目
`<plugin>/agents/<name>.md`	5(最低)	plugin 分发

同名时高优先级覆盖。/agents 命令显示哪个 active。

4. 18+ frontmatter 字段 — 必懂的 9 个

字段	用
`name` ⭐	唯一标识,小写连字符
`description` ⭐	Claude 看这个决定何时派
`tools`	白名单 — 只允许这些工具
`disallowedTools`	黑名单 — 排除这些(跟 tools 一起用时先去黑名单)
`model`	`haiku` / `sonnet` / `opus` / `inherit`(默认)
`permissionMode`	`default` / `acceptEdits` / `auto` / `dontAsk` / `bypassPermissions` / `plan`
`skills`	启动时预加载若干 skill(全文注入,不只是 description)
`mcpServers`	subagent 独占的 MCP server(主 session 看不到!)
`memory`	`user` / `project` / `local` — 持久记忆!

其他字段:hooks、background、effort、isolation: worktree、color、initialPrompt、maxTurns、mcpServers。

5. `memory: user` 持久记忆 — 杀手级特性

---
name: codebase-archaeologist
description: Understands historical decisions in this codebase
memory: project
---

When asked about why something exists:
1. git blame the file
2. Read commit messages and PRs
3. Cross-reference against ~/.claude/agent-memory/codebase-archaeologist/

Always update memory after each task with:
- New insights about codebase structure
- Decisions you discovered
- Patterns that recur

跑完后 subagent 会在 ~/.claude/agent-memory/codebase-archaeologist/ 写入它学到的东西。下一次跑,这些笔记自动注入它的 context — 它真的会”学”。

3 个 scope:

user → ~/.claude/agent-memory/<agent>/
project → .claude/agent-memory/<agent>/
local → .claude/agent-memory/<agent>/(gitignored)

实战使用建议:

自己造的 specialist subagent → memory: user(跨项目积累)
项目特定的 subagent → memory: project(进 git,团队共享)
涉及敏感数据 → memory: local(本地)

6. `mcpServers` — subagent 独占 MCP server

---
name: browser-tester
description: Tests features in browser via Playwright
mcpServers:
  - playwright:
      type: stdio
      command: npx
      args: ["-y", "@playwright/mcp@latest"]
  - github          # 引用已配的
---

Use Playwright tools to navigate, screenshot, interact.

关键意义:

主 session 看不到 Playwright 工具(context 不被工具描述占)
只在 subagent 启动时连 server,结束时断
工具描述本身就要 token — 主 session 不需要时就该屏蔽

7. `isolation: worktree` — subagent 跑在独立 git 工作树

---
name: experimental-refactor
description: Tries a risky refactor in isolation
isolation: worktree
permissionMode: acceptEdits
---

Refactor the file system module to use streams.

subagent 启动时自动建一个 git worktree(在 .claude/worktrees/ 下)
subagent 在 worktree 里乱改,不动你的主 working dir
如果 subagent 啥都没改 → worktree 自动清理
如果 subagent 改了 → 你看 result,自己决定要不要 merge

配合 Agent View(01-agent-view.md):background session 默认就有自动 worktree;但 subagent 加 isolation: worktree 是显式控制。

8. `/agents` 交互界面

> /agents
# Running tab:  当前活的 subagent
# Library tab:  所有可用 subagent
#   Built-in / User / Project / Plugin 分组
#   "Create new agent" → 跟着 Claude 自动生成
#   "Generate with Claude" → 给 description,Claude 自动写出 system prompt + tools 配置

新建 subagent 的最快方法:

> /agents → Library → Create new agent → Personal → Generate with Claude
> 描述:"A code improvement agent that scans files and suggests improvements
       for readability, performance, and best practices."
→ Claude 给你写好 identifier / description / system prompt
→ 选 tools,选 model,选颜色,保存
→ 立刻可用

9. Subagent 跟其他东西的关系

                 [主 Claude]
                     │
       ┌─────────────┼─────────────┐
       │             │             │
       ▼             ▼             ▼
    Agent tool   Skill tool    其他工具
       │             │
       ▼             ▼
  [Subagent]      [Skill]
       │
   ┌───┴────┬─────────┬─────────┐
   ▼        ▼         ▼         ▼
 system   tools   preloaded   memory
 prompt           skills      / mcp

和 Skill 的微妙关系:

路径	system prompt	task	也加载
Skill 带 `context: fork`	来自 agent type	SKILL.md 内容	CLAUDE.md
Subagent 带 `skills:`	subagent 自己的 system prompt	主 Claude 给的任务	预加载的 skills + CLAUDE.md

两条路径用同一套底层。你想”让 skill 在隔离 context 里跑”用前者;你想”让 subagent 带着特定知识起步”用后者。

10. Agent Teams — 跨 session 通信(简介)

/en/agent-teams 是更高级的功能:

多个 Claude session 互相发消息
每个 session 可以是不同 subagent type
适合”我让 A session 写代码,B session review,他们直接对话”

本系列不单独写一篇 — agent teams 还在 Research Preview,而且 90% 用户更应该先掌握 Agent View(01-)和普通 subagent。

🟢 译者总评

1. 你已经在大量用 subagent,只是没意识到

每次主 Claude 用 Agent tool 找文件 / 调研 / 多步任务,它就在派 subagent。Anthropic 让这个机制无形 — 因为它该这样:你不需要思考”该不该派”,你只需要给指令。

但你可以让它更好 — 通过自定义 subagent。

2. 独立开发者应该写的 3 个 subagent

a. commit-writer(给我自己写) ← 上面的例子,直接用

b. frontend-reviewer

---
name: frontend-reviewer
description: Reviews React/Vue/Svelte UI code for accessibility, perf, and visual polish. Use when user is about to commit frontend changes.
tools: Read, Grep, Glob
model: sonnet
memory: user
skills:
  - frontend-design  # 如果装了 superpowers
---

Review for:
1. Accessibility (focus order, ARIA, keyboard nav)
2. Perf (unnecessary re-renders, large bundle imports)
3. Visual polish (animation timing, hover states, edge cases)
4. State management smell (prop drilling, derived state bugs)

Reference memory at ~/.claude/agent-memory/frontend-reviewer/ for patterns
you've seen recur. Update memory after each review with new patterns.

c. deployer

---
name: deployer
description: Deploys frontend / demo projects. Use when user says "deploy" or "ship X".
tools: Bash(git *), Bash(npm *), Bash(vercel *), Read, Write
model: haiku
disallowedTools: Edit
permissionMode: acceptEdits
---

Deployment SOP:
1. Ensure clean git status
2. Run build (npm/bun/vite as appropriate)
3. Deploy to Vercel / GitHub Pages
4. Update README badges
5. Tag a release

If anything fails, abort and report. Don't half-deploy.

写好放 ~/.claude/agents/,以后说 “deploy” 就自动走。

3. Subagent 真正的杠杆是”约束输出”而不是”任务复杂度”

人们以为 subagent 适合”复杂任务”。其实简单任务派 subagent 也有意义 — 如果输出会污染你的主 context。例如:

“查一下 v1.2 的 API 变化” → 派 Explore,主 session 不被那些代码淹没
“跑下测试看哪些挂” → 派 general-purpose,主 session 不被测试输出淹没

任务大小不重要,context 隔离才重要。

4. 警惕的反模式

❌ subagent 写得跟另一个 CLAUDE.md 一样长 → 注入 token 都是钱
❌ 给 subagent 全工具 + bypassPermissions(等于裸跑)
❌ 派完 subagent 又要主 session 重复工作(“subagent 报告了,让我自己看看”)— 没相信结果 = 没用 subagent
❌ 拼装超过 5 层 skill + agent + plugin 嵌套 — context 爆炸

🔗 延伸阅读

同系列:01-agent-view.md(Agent View 是 subagent 的 sibling 概念 — background session vs 同 session subagent)、05-skills-system.md(skills 配 subagent)
官方:/en/agent-teams — subagent 互相对话
官方:/en/context-window — 演示 subagent 怎么省 context
本机案例:~/.claude/plugins/cache/understand-anything/.../agents/ 里有 9 个真实 subagent 定义可参考

🔗 调研来源(可校验)

主原文:https://code.claude.com/docs/en/sub-agents
changelog v2.1.63:The Task tool was renamed to Agent
understand-anything plugin 提供的 7 个 specialist subagent:project-scanner / file-analyzer / architecture-analyzer / article-analyzer / assemble-reviewer / graph-reviewer / domain-analyzer / tour-builder / knowledge-graph-guide
内置 subagent 命名:claude / Explore / general-purpose / Plan / statusline-setup / claude-code-guide