子代理本质上是一个独立上下文的 Claude 副本。 派一只 subagent,你付的成本是:多一次 prompt 装填、多一次 round-trip、 你看不到它中间在想什么——只能拿到最后那份总结。 所以"该不该派"的标准很硬:主代理做这件事会不会污染主上下文,或者顺序做太慢。

主代理 vs 子代理

该派 vs 不该派

内置子代理速览

内置 agent 通用但泛——团队里反复出现的工种(代码评审、迁移脚本、文档抽取、安全审计) 值得沉淀成自定义 agent:一个 Markdown 文件,描述清楚这个分身擅长什么、能用哪些工具、 它该怎么思考。下次任何人在项目里说"派 X 帮我看一下",Claude 就调起这个 agent。

agent 文件结构

# 文件:.claude/agents/code-reviewer.md
# 项目级 · commit 到 git · 团队共享

---
name: code-reviewer
description: |
  Use proactively after the user finishes implementing a non-trivial change.
  Best for catching bugs, security issues, and design problems before commit.
  Skip for typo fixes, comment-only changes, and pure refactors.
model: opus
tools: [Read, Grep, Bash, Glob]
---

You are a senior code reviewer. The user has just finished a change and
wants an independent second opinion before they commit.

Review goals (in order):
1. Correctness — does the change do what it claims?
2. Security — any injection / auth / secret leakage / unsafe deserialization?
3. Resource leaks — file handles, connections, memory.
4. Edge cases — empty input, concurrent access, error paths.
5. Tests — are tests added? do they actually cover the new code path?

Use `git diff` to see what changed. Read surrounding context for each
modified function. Cross-check callers with `grep`.

Output format:
- 🔴 Critical (must fix before commit)
- 🟡 Should fix (high impact but not blocking)
- 🟢 Nit (style / readability)
Each item: file:line, what's wrong, suggested fix.

frontmatter 字段

三层 agent 存放位置

写 description 的诀窍 — 让主代理"懂得派"

# ✗ 模糊 — 主代理不知道什么时候该派
description: "代码评审 agent"

# ✓ 具体 — 主代理一看 description 就能判断匹配
description: |
  Use proactively after the user finishes implementing a non-trivial change.
  Best for catching bugs, security issues, and design problems before commit.
  Skip for typo fixes, comment-only changes, and pure refactors.

# ✓ 主动触发关键词 — 告诉主代理"什么场景务必派我"
description: |
  MUST USE when user runs `git commit` or asks for review of pending changes.
  Specifically tuned for backend Go services in this repo.

tools 字段:给分身的"工具包"

# 一个只读的搜索 agent — 不给写权限是基本安全
tools: [Read, Grep, Glob, Bash]    # Bash 通常允许只读命令

# 一个评审 agent — 给读 + 跑测试,不给改
tools: [Read, Grep, Glob, Bash]    # 评审不需要 Edit/Write

# 一个迁移 agent — 给改文件 + 跑 migration
tools: [Read, Edit, Write, Bash, Grep]

# 不写 tools 字段:继承父代理的全部工具(包括 Agent 工具本身)
# 这意味着 subagent 可以再派 subagent — 递归深度过深时一定要限

最容易被忽略的能力:同一条消息里调用多次 Agent 工具,这些 subagent 会并行跑。 顺序派 5 个要等 5 倍时间,并行派 5 个只等最慢那一个。 但并行的前提是任务彼此独立——一旦后一个依赖前一个的结果, 并行就退化成串行加同步开销,反而更慢。

三种调度形态

并行派 — 主代理伪代码

# 主代理在【一条助手消息】里 emit 多个 Agent 调用 — 这些就并行

Agent(subagent_type="Explore", prompt="找权限验证逻辑")
Agent(subagent_type="Explore", prompt="找日志记录逻辑")
Agent(subagent_type="Explore", prompt="找错误处理逻辑")

# ↑ 三只手同时去搜 · 最慢那个跑完时主代理一次性收到 3 份摘要

# 反例:依赖关系不能并行
result_a = Agent(...)         # 等 A 完成
Agent(prompt=f"基于 {result_a} 继续做 B")   # B 必须等 A
# 这种就老老实实串行,别硬塞同一条消息

foreground vs background

prompt 必须自洽 — subagent 看不到你和主代理的对话

# ✗ 主代理这样派 — subagent 完全懵
Agent(prompt="基于上面我们讨论的方案,把它实现一下")
#       ↑ "上面的方案"是什么?subagent 没看过那段对话

# ✓ 把上下文打包进 prompt
Agent(prompt="""
背景:用户在重构 auth 模块,目标是把 session 存储从 cookie 改成 JWT。
我们已经决定:① 用 jose 库 ② token 放 Authorization header
③ 保留 refresh-token 机制。

任务:实现 src/auth/jwt.ts,导出 signToken / verifyToken 两个函数。
约束:函数签名必须兼容现有 src/auth/session.ts 的调用方式。

完成后,简短报告:改了哪些文件、新增了什么、有没有遗留 TODO。
""")

实战:50 个文件批量重命名

# 任务:把项目里所有 getUserId() 改成 getCurrentUserId()

# 第一步:主代理用 Grep 列出所有命中
Grep("getUserId", output="files_with_matches")
# 输出 50 个文件 — 大致按目录分:auth/ (12) · api/ (15) · ui/ (23)

# 第二步:按目录分成 3 组,一条消息并行派
Agent(subagent_type="general-purpose", prompt="""
重命名 src/auth/ 下 12 个文件里的 getUserId → getCurrentUserId。
保持其他代码不变。完成后报告:改了哪些文件、行数、有无遗漏。
""")
Agent(subagent_type="general-purpose", prompt="重命名 src/api/ 下...")
Agent(subagent_type="general-purpose", prompt="重命名 src/ui/ 下...")

# 第三步:三只手同时改 · 主代理收齐 3 份报告 · 跑测试验证

并行派两个 subagent 同时改文件——一个改 src/auth/, 一个改 src/auth/login.ts 的同一段—— 在同一个工作目录里跑必然写冲突。 Git worktree 给每只手发一份独立的工作目录(同一仓库、不同分支、不同物理路径), 改完合并就好。Claude Code 把这个能力封装在 isolation: "worktree" 参数里。

Git worktree 30 秒入门

# 一个仓库可以有多个 worktree — 每个挂在自己的分支上

$ git worktree add ../proj-feat-auth feat/auth
#       ↑ 新目录                ↑ 检出/新建的分支
$ git worktree add ../proj-fix-login fix/login

$ git worktree list
/Users/me/proj            d4a92e1 [main]
/Users/me/proj-feat-auth  d4a92e1 [feat/auth]
/Users/me/proj-fix-login  d4a92e1 [fix/login]

# 三个目录共享同一份 .git · 各自独立的工作区
# 在不同目录里改不同分支,互不干扰 · build / test 也独立

$ git worktree remove ../proj-feat-auth   # 清理

subagent + worktree 的组合

两种用法

# 用法 1:派 subagent 时指定 worktree 隔离
#         agent 全程在新 worktree 里操作 · 完成后报告路径/分支

Agent(
  subagent_type="general-purpose",
  isolation="worktree",
  prompt="在新分支上把 src/auth 从 cookie 改成 JWT,跑完测试"
)
# ↑ 父代理拿到结果:"已在 .claude/worktrees/abc/ 上 feat/jwt-xyz 分支完成,
#                  18 个文件改动 · 12 个测试通过"

# 用法 2:让当前会话进入 worktree
#         适合"我现在要切到另一个分支临时改东西"

EnterWorktree(name="hotfix-login")    # 创建并切入
# …你和 Claude 在新 worktree 里干活…
ExitWorktree(action="keep")              # 留着,稍后回来
# 或
ExitWorktree(action="remove")            # 干完直接清理

什么时候用 worktree

把前面的零件拼起来,真实项目里反复出现的四种 subagent 编排模式。 认出眼前任务是哪一种,就知道该派几个、串还是并、要不要 worktree。

把四种模式映射到一张决策图

# 拿到任务先问自己 4 个问题

Q1: 这是"在 N 个独立单元上做同一件事"吗?
   ✓ → PATTERN 01 · 分而治之(N 并行)
   ✗ → 继续

Q2: 主代理刚做完,想要不带偏见的复核?
   ✓ → PATTERN 02 · 独立评审(1 只读)
   ✗ → 继续

Q3: 目标模糊 / 不知道关键词 / 可能在 5+ 处?
   ✓ → PATTERN 03 · 广度探索(1 只读 + Explore)
   ✗ → 继续

Q4: 这件事会跑 5 分钟以上,你不想干等?
   ✓ → PATTERN 04 · 后台执行
   ✗ → 主代理自己做 · 不要派 subagent

1. 子代理与主代理在上下文窗口上的关系是什么?为什么这决定了"该不该派"的判断标准?
2. 自定义 agent 文件放在哪三个层级?各自的可见范围有什么不同?
3. 同一条消息里调用多个 Agent 工具 vs 分多条消息调用,行为上有什么区别?
4. isolation: "worktree" 为什么能让多个 subagent 并行改文件不冲突?它把冲突推到了哪一步?
5. 四种工作流模式各自的判别问题是什么?见到"批量重命名 50 个文件"该用哪一种?