异步视界博客
iaieye.com

最近更新

    ↑↓ 选择↵ 打开esc 关闭

    Subagents:Agent tool 调度专家小队

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

    • Claude Code 功… · 8/16
    • 精读
    • 2026.05.13
    • 20 分钟
    • 9,759 字

    思思扬撰写 · AI 协作整理

    类型
    精读
    系列
    Claude Code 功能 + 集成生态调研(2026-05)
    位置
    第 8 篇 / 共 16 篇
    发布
    2026.05.13
    篇幅
    9,759 字 · 20 分钟
    章节
    8 节
    标签
    • claude-code
    • ai
    • subagents
    • context

    原文: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 memorymemory: 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模型工具用
    ExploreHaiku(便宜快)只读找文件、grep 代码、扫 codebase
    Planinherit只读plan mode 下做调研(防止套娃)
    general-purposeinherit全部多步任务、要修改代码的活

    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 settings1(最高)enterprise IT 强制下发
    --agents '{"name":{...}}' CLI flag2一次性测试
    .claude/agents/<name>.md3项目共享(进 git)
    ~/.claude/agents/<name>.md4个人所有项目
    <plugin>/agents/<name>.md5(最低)plugin 分发

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

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

    字段用
    name ⭐唯一标识,小写连字符
    description ⭐Claude 看这个决定何时派
    tools白名单 — 只允许这些工具
    disallowedTools黑名单 — 排除这些(跟 tools 一起用时先去黑名单)
    modelhaiku / sonnet / opus / inherit(默认)
    permissionModedefault / acceptEdits / auto / dontAsk / bypassPermissions / plan
    skills启动时预加载若干 skill(全文注入,不只是 description)
    mcpServerssubagent 独占的 MCP server(主 session 看不到!)
    memoryuser / 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 prompttask也加载
    Skill 带 context: fork来自 agent typeSKILL.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 爆炸

    🔗 延伸阅读

    2 条
    • 同系列: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
    系列全部 16 篇
    1. 01Agent View:一个窗口管所有 Claude Code sessions13 分钟
    2. 02Remote Control:用浏览器和手机驱动本机的 Claude Code16 分钟
    3. 03Claude in Chrome:让 Claude Code 直接驾驶你的浏览器14 分钟
    4. 04Plugins + Marketplace:Claude Code 一切扩展的载体20 分钟
    5. 05Skills 系统:把再次输入的指令变成可加载的能力19 分钟
    6. 06Hooks:在 Claude Code 生命周期上挂触发器18 分钟
    7. 07MCP 客户端 + 第三方服务器生态18 分钟
    8. 08Subagents:Agent tool 调度专家小队20 分钟
    9. 09Routines / Scheduled Tasks / /loop:三层调度栈16 分钟
    10. 10GitHub Actions 集成:让 Claude 在 CI 里跑17 分钟
    11. 11Memory 系统:CLAUDE.md + auto memory19 分钟
    12. 12Channels:把外部事件推进活跃 session15 分钟
    13. 13IDE 集成:VSCode + JetBrains 扩展16 分钟
    14. 14Computer Use:让 Claude 真的操作你的电脑18 分钟
    15. 15Claude Code 概念全集 / 关键词速查表36 分钟
    16. 99附录:Claude 全产品矩阵中 Claude Code 的位置12 分钟