生成 Explorer/Plan/Reviewer 子代理以保护父代理上下文，并通过并行处理提升吞吐量。

Claude Code 中，Subagents（Task 工具）是大多数用户最晚才掌握的能力。在单个会话中包揽所有事情会迅速耗尽父代理的 context window，大型任务也受制于单线程瓶颈。将子代理作为抽象层来使用 — Explorer 负责搜索和摘要，Reviewer 只审查 diff — 相同时间内可以处理双倍工作量。

我认为 Subagents 模式的核心价值不在并行执行，而在上下文保护。以前父代理什么都自己做，context window 迅速耗尽；如今通过委托，父代理只收到摘要结果，由于那个摘要边界，核心判断能力才得以保留到最后。

本指南面向 Claude Code 1.x，在 Claude Code 配置和 Hooks 的基础上，将日常工作流提升到新的高度。

TL;DR

父代理 处理直接编辑 + 构建/测试 — 短小快速的工作
Explorer Subagent — 「X 在代码库的哪里？」搜索/摘要，不将大量结果拉入父代理
Plan Subagent — 仅为大型变更返回分步计划
Reviewer Subagent — 对父代理 diff 进行 second-opinion 审查
Specialist — 领域专属子代理，如 claude-api / security-review

核心原则 — context window 保护 + 并行执行。

前提条件

Claude Code 1.x 已安装 — Claude Code 配置
项目基础就绪：CLAUDE.md + .claude/settings.json
（可选）hooks 基础配置 — 部分父代理 hooks 也适用于子代理

1. Task 工具调用模型

在 Claude Code 中，Task 工具用单个 prompt 生成一个新代理。Subagent 有自己独立的 context window — 不与父代理共享消息，只有最终结果消息会返回给父代理。

父代理
   │
   ├─ Task("Explore", "find token-validation logic in src/auth/; return only function names + file paths")
   │   ↓ （独立上下文，最多 100k token 空闲）
   │   ↑ "validateToken: src/auth/verify.ts:42"  ← 父代理只收到结果
   │
   └─ Task("Reviewer", "scan the last commit's diff for security issues")
       ↓
       ↑ "1 finding: src/api/user.ts:88 — possible SQL injection"

父代理 context window 中只追加一条最终摘要。Subagent 可能读取了 200 个文件，父代理只收到一行结果。

2. 四种核心模式

2.1 Explorer — 隔离大型搜索结果

使用频率最高的模式。将「X 在哪里定义？」类问题委托给 Subagent。

"Delegate to an Explorer subagent:
'Find the useAuth hook definition + all usages in src/. Return
- def: file:line
- usages: file:line × all
Limit to a 30-line summary. Don't include code bodies.'"

父代理只收到 30 行摘要。若直接操作，grep + 多文件读取会消耗 5–20k tokens。

适用场景：

刚进入新代码库时
「这个功能在哪里实现？」
「我们是如何使用这个库的？」
依赖影响分析

不适用场景：

小型搜索 — 父代理一行 grep 即可解决
需要完整读取结果的场景 — 父代理直接读效率更高

2.2 Plan — 大型变更只返回分步计划

适用于 5+ 文件变更 / 新模块 / 架构调整 — Plan Subagent 完成调研 + 权衡分析后，只返回执行计划。

"Delegate to a Plan subagent:
'Return a step-by-step execution plan only.
Requirement: expand seeds from ~7/category to 10.
Constraints: build under 1 min, verify:assets 100%.
Output: category · topic · has-asset · estimated lines table + writing order.
Do not write code.'"

父代理收到计划后，执行由父代理负责或分配给其他 Subagent。

2.3 Reviewer — Second Opinion

由拥有独立 context window 的 Subagent 审查父代理的 diff。「新鲜的眼睛」能发现父代理遗漏的问题。

"Delegate to a Reviewer subagent:
'Review the diff of commit 4d2f0 from a security angle.
Specifically: SQL injection, XSS, hardcoded secrets, race conditions.
Output: N findings + file:line + 1-line note each. Or "clean".'"

父代理熟悉自己的代码，反而容易遗漏问题。Reviewer Subagent 从独立视角审查同一份 diff。

2.4 Specialist — 领域专属 Subagent

针对特定领域的子代理（claude-api、security-review、code-reviewer、build-validator 等），具备丰富的领域知识和适配该领域的输出格式。

"Delegate to security-review:
'Comprehensive security assessment of the current branch's changes.
Scope: authn / authz / input validation / secrets / sessions / CSRF.'"

Specialist 通常配有为其领域专门调优的 system prompt，输出质量更高。

3. 编写委托 Prompt

Subagent 无法访问父代理的上下文。Prompt 必须自包含。

好的 Prompt

"Find these patterns in src/:
- `fetch(...)` calls where baseURL is hardcoded
- Result: file:line + 1 code line + inferred baseURL domain
- Limit 30; if more, append '+N more'
- Don't attach code bodies — line only"

不好的 Prompt

"Review that fetch thing earlier"   ← 无上下文，模糊

"Find all fetch calls"   ← 无输出格式，有大量输出的风险

编写检查清单

目标 — 你想知道什么
范围 — 在哪里（目录/文件/范围）
输出格式 — 表格 / 行级 / 摘要长度
排除项 — 不要返回什么（代码体、大型 diff）
停止条件 — N 个发现后停止
未知情况 — 「如果不知道，请说出来；不要猜测」

4. 并行执行 — 独立委托一起发送

相互独立的任务可以在单个响应中以多个 Task 调用发出，Claude Code 会并行生成它们。

"Three delegations at once:
1) Explorer — summarize where auth files live
2) Explorer — summarize db migration history
3) Reviewer — security review of last 5 commits

After receiving all three, do an integrated analysis."

父代理同时收到全部三个结果，总耗时缩短为 1/3。

不应并行的情况：

A 的输出是 B 的输入 — 必须顺序执行
两个任务编辑同一文件 — 存在竞态风险

5. 上下文管理 — 委托 vs 直接

信号	委托	直接
结果可缩减为 1–2 行	是	—
需要把代码体导入父代理	—	是
100+ 文件搜索	是	—
一两个 grep	—	是
结果立即用于下一步	—	是（委托+接收 > 直接）
需要不同视角	是（Reviewer）	—
领域专属知识	是（Specialist）	—

经验法则：若一个任务会消耗父代理 20% 的 context window，就应考虑委托。

6. 真实场景

A. 进入新代码库

1. Explorer — 文件夹结构 + 5 个关键模块摘要
2. Explorer — README + CLAUDE.md（如有）要点
3. Explorer — 最近 10 次提交摘要
↓
4. 父代理 — 综合为「关于这个 repo 的一段话」

B. 5+ 文件变更

1. Plan — 变更范围 + 步骤 + 风险表
2. 父代理 — 审查计划，逐步进行
3. 每一步之后，Reviewer — diff 审查
4. 最终提交前，Reviewer — 全变更第二意见

C. 调试

1. 父代理 — 定义错误日志 + 重现路径
2. Explorer — 追踪相关代码路径（从堆栈追踪）
3. 父代理 — 假设 + 尝试修复
4. 父代理 — 通过构建/测试验证

D. PR 合并前

1. Reviewer — diff 安全/性能审查
2. Reviewer — 与现有代码约定的一致性
3. Specialist（security-review）— 综合评估
4. 父代理 — 将发现整合为 PR 评论或修复

7. 与 Hooks 结合

Claude Code Hooks 的 PreToolUse 也可以拦截 Task 调用。

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Task",
        "hooks": [
          {
            "type": "command",
            "command": "/bin/bash -lc 'echo \"[delegate] $(jq -r .tool_input.description)\" >> ~/.claude/delegate.log'"
          }
        ]
      }
    ]
  }
}

记录委托数量和内容，便于事后回顾哪些是委托的、哪些是直接处理的。对成本追踪和模式学习很有价值。

8. 反模式 — 误用委托

8.1 事事委托

"把单文件编辑也委托出去"   ← 只会增加开销

Subagent 调用有 tokens / 时间成本。把 1 秒的任务变成 30 秒的委托是净损耗。

8.2 委托后父代理再次重复搜索

"Explorer 已摘要了 auth 文件位置 → 父代理又自己 grep 一遍相同文件"

→ 委托毫无意义。信任结果并直接进入下一步。

8.3 要求过多输出

"带上每个文件的完整代码 + 5 行解释 + 使用代码体"

→ 委托并未减少父代理的 context 消耗。在 prompt 中限制输出大小。

8.4 有依赖关系的并行委托

"A 的结果需要输入给 B，但两者同时委托"

→ B 无法获知 A 的结果，产生错误假设。此类情况必须顺序执行。

9. 分工矩阵 — 谁做什么

任务	父代理（主）	Explorer	Plan	Reviewer	Specialist
小型 grep	是	—	—	—	—
代码变更	是	—	—	—	—
构建/测试	是	—	—	—	—
大型搜索	—	是	—	—	—
大型变更计划	—	—	是	—	—
Diff 审查	（仅小型）	—	—	是	是（安全）
综合安全评估	—	—	—	—	是（security-review）
领域 API 使用	—	—	—	—	是（claude-api 等）

后续步骤

Claude Code 配置 — 父代理基础
Claude Code hooks — 记录/验证委托
多代理工作流 — 多工具/代理集成场景
Agent runner — 自主运行 + subagents 结合

参考资料

Claude Code 官方 — Task 工具
Anthropic — 代理设计模式 — 通用原则

更新日志

2026-05-12 — 初稿（devAlice M3 种子扩展）

Claude Code subagents — 通过 Task 工具进行角色分工