Subagents 与 Agent 工具

Subagent 是在自己独立上下文窗口里干活的专职助手，由 Agent 工具启动；它只把摘要回报给主对话，且不能再生 subagent。

你的真实配置

你没在项目里写自定义 .claude/agents/，但通过插件已经有一批专职 subagent 可用——尤其是代码评审那套：

subagent	来自	干什么
Explore	内置	只读、Haiku、快速搜代码库（你 AGENTS.md 指定的"探索用它，别 grep 全仓库"就是它）
Plan	内置	plan 模式下只读调研
general-purpose	内置	全工具、多步复杂任务
code-simplifier:code-simplifier	插件	改完代码后简化、保功能
pr-review-toolkit:code-reviewer	插件	按规范审 diff
pr-review-toolkit:silent-failure-hunter	插件	专抓吞错/无声失败的 catch/fallback
pr-review-toolkit:type-design-analyzer	插件	审类型设计
pr-review-toolkit:comment-analyzer / pr-test-analyzer	插件	审注释 / 审测试覆盖
claude-code-guide	内置	回答 Claude Code 用法问题

去真实体验

想验证什么	这样做
看所有可用 subagent + 哪个在跑	输入 /agents
Explore 实测（最贴你 AGENTS.md）	「用 Explore 摸清 kj-frontend/ 的路由怎么组织的」——大量文件读取留在它独立窗口，主对话只拿摘要
代码评审 subagent 实测	改完 SpringBlade 某个 Controller 后：「用 pr-review-toolkit:code-reviewer 审一下我刚改的 diff」
@-mention 锁定某个	输入 @ 选 code-reviewer (agent)，保证就用它
整个会话用某 agent	claude --agent code-reviewer
找 subagent 的 transcript	~/.claude/projects/<project>/<sessionId>/subagents/agent-<id>.jsonl

真实案例：为什么 Explore 省上下文（贴你的约定）

你 CLAUDE.md 写了「探索代码库用 Explore agent，不要 grep 全仓库」。原因正是 subagent 机制：

直接在主对话里 grep + 读 20 个文件
  → 这 20 个文件全进主上下文，几万 token，后面一直占着

派 Explore 去
  → 它在自己独立窗口里读那 20 个文件
  → 只把"路由在 src/router、用 xxx 模式"这段摘要返回主对话（几百 token）

这跟「上下文管理」「提示词缓存」是同一套省 token 逻辑：把啰嗦的中间过程挡在子窗口里。

真实案例：评审你 SpringBlade diff 的链式用法

1. 你改了 blade-system 的鉴权逻辑
2. /agents 里没有自定义的，但插件给了一套：
   「用 pr-review-toolkit:code-reviewer 审这次 diff，
    再用 silent-failure-hunter 专门看有没有吞掉异常的地方」
3. 两个 subagent 各自独立窗口审，结论汇回主对话

注意：subagent 不能再生 subagent（不能嵌套）。要多步委派，要么从主对话链式调用（上面这样），要么用 Skills。

subagent vs 你在用的"团队/技能"

• subagent：副任务返回摘要，彼此不通信。你日常评审/探索用这个最多。
• agent teams（需开 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1）：多个会话互相讨论，适合"安全/性能/测试各一人并行评审 PR"——比单个 code-reviewer 更全，但更贵。
• 技能 + context: fork：让一个技能在子代理里隔离跑（如 superpowers 的研究类技能）。

---

官方文档要点

以下为按官方文档整理的系统性参考。

是什么

Subagent（子智能体）是专职 AI 助手，运行在自己独立的 context window 里，有自己的系统提示、限定的工具和独立权限，干完只把摘要回报给主对话——好处是把刷屏的中间过程（跑测试、读日志、查文档）挡在主对话外面。启动它的工具叫 Agent（官方 v2.1.63 起由 Task 改名为 Agent，旧名仍兼容）：『Agent』是启动动作，『subagent』是被启动的实体，是同一件事的两面。

怎么工作

• 主 agent 按每个 subagent 的 description 自动决定派谁；也可自然语言点名、@-mention 锁定、或 --agent 让整个会话用它。
• 每次启动都是全新隔离上下文，看不到主对话历史（fork 模式例外）；只加载自己的系统提示 + 委派任务 + CLAUDE.md（Explore/Plan 跳过 CLAUDE.md 和 git status）。
• 内置：Explore（Haiku、只读、查代码）、Plan（只读、plan 模式调研）、general-purpose（全工具），外加 statusline-setup、claude-code-guide。
• subagent 不能再生 subagent（不能嵌套）；默认也拿不到 Agent 工具本身、AskUserQuestion、ScheduleWakeup 等依赖主会话 UI 的工具。
• 可前台（阻塞）或后台（并发）运行；后台用已授权限、遇到要弹窗的工具自动拒绝。

怎么配置 / 用法

自定义 subagent = Markdown + YAML frontmatter：

• 项目级 .claude/agents/<name>.md，用户级 ~/.claude/agents/<name>.md，也可插件 / --agents JSON / 托管。
• 必填 name、description；可选 tools、disallowedTools、model（sonnet/opus/haiku/全 ID/inherit）、permissionMode、skills、memory（user/project/local）、isolation: worktree、maxTurns、hooks、color 等。

例：

---
name: code-reviewer
description: Reviews code for quality and best practices
tools: Read, Glob, Grep
model: sonnet
---
You are a code reviewer...

用 /agents 命令向导创建/管理；@-mention 或 --agent <name> 调用。

什么时候用

• 副任务输出很啰嗦、只要个摘要（跑测试、读日志、查文档）。
• 想限制工具/权限，或活儿自包含能返回摘要。
• 并行调研：派多个 subagent 各查一块，主 agent 汇总。
• 别用：需要频繁来回 / 多阶段共享大量上下文 / 快速小改 → 留在主对话。

限制 / 坑

• subagent 不能再生 subagent（无嵌套）；要多步委派用 Skills 或从主对话链式调用。
• 每个 subagent 完成时结果回主对话，开太多、每个都返回详细结果会吃主上下文。
• 默认从全新上下文开始，看不到主对话历史（fork 例外）。
• Explore/Plan 跳过 CLAUDE.md 和 git status，相关规则需在委派 prompt 里重述。

硬事实速查（7 条）

• Agent 工具 = 启动 subagent（v2.1.63 由 Task 改名 Agent，Task 仍作别名）。
• 配置路径：.claude/agents/（项目）、~/.claude/agents/（用户）、插件 agents/、--agents JSON、托管设置。
• frontmatter 必填 name/description；可选 tools/disallowedTools/model/permissionMode/skills/memory/isolation/maxTurns/hooks/background/effort/color/initialPrompt。
• 内置 subagent：Explore(Haiku 只读)、Plan(只读)、general-purpose(全工具)、statusline-setup、claude-code-guide。
• subagent 不能嵌套；默认无 Agent/AskUserQuestion/ScheduleWakeup 等工具。
• Agent(worker, researcher) 形式可限制主线程能 spawn 哪些类型；permissions.deny 里 Agent(Explore) 可禁用某个。
• transcript 存于 ~/.claude/projects/{project}/{sessionId}/subagents/agent-{id}.jsonl。

---

官方出处：https://code.claude.com/docs/en/sub-agents