生命不息，折腾不止。上一篇把 Claude Code 装进了终端，这一篇上硬菜：用 Subagents 把一个大任务拆给一支并行小队，主对话坐收渔利。

一、Subagents 到底是啥：主对话的「分身术」

上一篇说过，Claude Code 干活时读文件、跑命令、看日志，全堆在同一个上下文窗口里。任务一大，窗口很快被塞满，它就开始「失忆」——前面看过的关键信息被挤出去，干活质量直线下滑。

Subagents（子代理）就是解法：给 Claude 开「分身」。每个子代理有自己独立的上下文窗口，干完活只把一句总结送回主对话。主对话永远清爽，那些中间过程——跑测试的几百行日志、搜代码的几十个文件内容——全部留在子代理自己的窗口里，用完即弃。

官方说法更直接：当一个辅助任务会用搜索结果、日志或文件内容「充斥」你的主对话、而这些内容你以后不会再引用时，就该丢给子代理。

它还能顺手干三件事：

  • 强制约束：只给子代理 Read 权限，它就永远改不了文件；
  • 专门化：每个子代理配一套专属系统提示，审代码的、写文档的、跑测试的，各司其职；
  • 控成本：把不重要的活路由到更便宜的模型（比如 Haiku），好钢用在刀刃上。

一句话：Subagents 就是 Claude Code 里的「多线程」——主对话当项目经理，子代理当干活的人。

二、写第一个子代理：文件放哪、怎么写

一个子代理就是一个带 YAML 头部的 Markdown 文件，放在两个位置之一：

  • .claude/agents/（项目级，跟项目走，可以提交进 git 给团队共用）
  • ~/.claude/agents/（用户级，你机器上所有项目通用）

优先级：项目级 > 用户级，同名时项目级生效。

文件长这样——frontmatter 是配置，正文是它的系统提示，只有 name 和 description 是必填：

1
2
3
4
5
6
7
8
9
10
---
name: code-reviewer
description: Expert code review specialist. Use proactively after writing or modifying code.
tools: Read, Grep, Glob, Bash
model: sonnet
---

You are a senior code reviewer. When invoked, run `git diff` first,
focus on modified files, and report issues ordered by priority:
critical / warning / suggestion. Never edit files.

逐行解释：

  • name：唯一标识，只能小写字母和连字符（code-reviewer 这种），也是你后面调用时的名字；
  • description：最关键的字段。Claude 全靠它判断「什么时候该把任务交给这个子代理」，写得越具体，自动委托越准；
  • tools：允许列表。这里只给了 Read、Grep、Glob、Bash，没给 Write 和 Edit——所以这个审查员物理上改不了代码；
  • model：指定这个子代理用哪个模型，省略则继承主对话。

从 v2.1.198 开始，官方把 /agents 交互式向导砍了，现在就是两种方式：直接手写文件，或者直接对 Claude 说「帮我建一个 xxx 子代理」让它代写。个人推荐手写——文件简单，还能完全掌控它。

三、怎么调用：三种姿势从轻到重

姿势一：自然语言（最常用）。不用特殊语法，直接点名就行：

1
Use the code-reviewer subagent to look at my recent changes

Claude 会根据 description 判断要不要真派活。想让它更主动，就在 description 里加 use proactively 这类字眼。

姿势二：@-mention（保证运行）。输入 @ 从弹出的选择器里选子代理，或者直接手打：

1
@agent-code-reviewer look at the auth changes

区别在确定性：自然语言是「建议」，@ 是「点名」，点名了它就一定跑这个子代理。

姿势三：整个会话变身。--agent 标志能让整个会话都以某个子代理的身份运行：

1
claude --agent code-reviewer

它的系统提示会整个替换掉默认的 Claude Code 提示，工具权限、模型也按文件里的来。适合「这一个会话就只干审查这一件事」的场景。

四、实战：把一个大任务拆给并行小队

光说不练假把式。假设一个典型场景：你改了三个模块——登录、支付、报表，现在要「每个模块跑一遍单元测试，再把结果汇总给我」。

没有子代理时，Claude 得一个模块一个模块地跑，测试日志全堆进主上下文，三个模块跑完它基本就「饱」了。有了子代理，拆成三个并行小队。

先写 .claude/agents/test-login.md：

1
2
3
4
5
6
7
8
9
10
11
---
name: test-login
description: Runs unit tests for the login module and reports pass/fail summary.
tools: Bash, Read, Grep
model: haiku
---

You are a test runner for the login module only. Run the login test
suite (npm test -- login), then return a one-paragraph summary: how
many tests ran, how many failed, and the root cause of each failure.
Do not modify any code.

照葫芦画瓢再写 test-payment、test-report 两个文件，改一下 description 和测试命令即可。

然后回到主对话，一句话全派出去：

1
2
Run the login, payment, and report test suites in parallel using their
subagents, then give me one combined summary.

Claude 会把三个子代理并行跑起来（从 v2.1.198 起子代理默认在后台跑），每个都在自己的窗口里消化测试日志，最后只把三小段总结送回主对话。你得到的是一份清爽的汇总，而不是几千行测试输出。

这里有个省钱细节：model: haiku 把这种机械、不需要深度推理的活，路由到便宜快速的小模型。跑测试、查文件这类任务，Haiku 足够用，成本比 Sonnet/Opus 低一个量级。走中转站按量付费的话，「主对话用旗舰模型、子代理用 Haiku」就是性价比最高的搭配——Claude 全系模型在 ai.aklibk.com 都按人民币按量计费，大小模型分工能省不少钱。

五、给子代理上保险：权限与工具锁

子代理能干多少活，全看你发多少「通行证」。两个字段一正一反：

  • tools：允许列表，只写你希望它有的工具；
  • disallowedTools：拒绝列表，继承所有工具但砍掉不想给的。

几个实用组合：

1
2
3
4
5
6
7
8
# 只读分析：只能看，不能改、不能执行
tools: Read, Grep, Glob

# 能跑测试，但不能改文件
tools: Bash, Read, Grep

# 继承全部工具，但砍掉文件写入
disallowedTools: Write, Edit

更狠的用 permissionMode 控制它触发权限提示时的行为：default 正常问你、acceptEdits 自动接受编辑、plan 只读规划、bypassPermissions 全部放行（慎用，等于给子代理开了免审批，生产环境不建议）。

实战记住官方那四条：

  1. 一个子代理只精一件事；
  2. description 写详细，Claude 靠它做委托决策；
  3. 工具只给必需的，安全和专注两不误；
  4. 提交进版本控制，项目级子代理跟团队共享。

六、踩坑清单（都是真坑）

  1. 新建 agents 目录要重启。如果 ~/.claude/agents/ 目录在会话开始前不存在，会话里新建的第一个文件它检测不到，重启 Claude Code 就好；
  2. name 必须唯一。同一个 .claude/agents/ 下（含子文件夹）两个文件同名，只会加载其中一个，还选得随缘。/doctor 能帮你查重；
  3. 子代理看不到你的对话历史。它是全新窗口，只拿到 Claude 写的一句任务描述。所以 description 和正文提示词要写足背景，别指望它「顺着上文猜」；
  4. 改完文件几秒内生效，一般不用重启（除了第 1 条那种新目录的情况）；
  5. 嵌套有上限：子代理也能再派子代理（v2.1.172 起），但深度最多五层，第五层的子代理拿不到 Agent 工具，不能再往下派。

生命不息，折腾不止。下一篇开 Skills：把「多步骤的可复用流程」打包成随时调用的技能卡，让你的子代理和主对话共用同一套工作流。先把上面三个测试子代理跑通，下一篇见。