子代理（Subagent）：Claude 派出的小工

你让 Claude Code "把 src 下面所有的 TODO 注释整理成一份报告"。

它没有一个一个文件读——它停了一下，然后告诉你："我派一个子代理去扫。"

几秒钟后，子代理回来交作业：87 个 TODO，按文件归类好了。

这就是 Subagent——Claude Code 干大活的关键武器。

1. 主代理一个人干不动

回想一下上下文窗口的限制。如果主代理一个一个 Read 你 src 下的 200 个文件，几万 token 就用完了——后面什么都做不了。

更聪明的做法：

1. 主代理告诉系统："我要派一个工具人，让它去扫所有文件找 TODO，然后给我一个摘要回来。"
2. 子代理被启动——是另一个独立的 Claude 实例，有它自己的桌面（独立上下文）。
3. 子代理用 Glob + Grep 扫完 200 个文件，自己消化完毕。
4. 子代理把摘要（不是原始内容）扔回主代理。
5. 主代理只看到一份精炼的报告——只占几百 token。

主代理的桌面没被占满，可以继续干别的活。

2. 子代理 ≠ 多线程

很多人第一反应"哦这是并行"。不完全是。子代理的核心价值不是快——是上下文隔离：

没有子代理	用了子代理
200 个文件内容塞进主上下文	200 个文件只塞进子代理上下文
主代理被噪声干扰	主代理只看到"找到 87 个 TODO"
后续没桌面继续做事	主代理桌面干净，能继续推进

副产品才是"快"——多个子代理可以并行跑，但这不是主要卖点。

3. 什么时候 Claude 会用子代理

它会自己判断。常见触发：

• 大批量扫描：上面 TODO 那个例子。
• 试错型任务：让一个子代理跑测试，跑挂了不污染主对话。
• 专业角色扮演：让一个子代理扮演"安全审计员"过一遍代码——它的视角和主代理不同，能看到主代理忽略的问题。
• 可以并行的小活：同时改 3 个文件、各派一个子代理。

4. 自定义子代理（agents 文件）

你可以预定义几种角色的子代理。在项目根目录：

.claude/agents/security-reviewer.md

文件内容：

---
name: security-reviewer
description: 专门审视代码安全问题
tools: [Read, Grep, Glob]
---

你是一名安全审计员。专注于：
- SQL 注入风险
- XSS / CSRF
- 敏感信息泄露（密钥、token 写死在代码里）
- 依赖中的已知漏洞

不要修代码，只报告。报告格式：
- 严重程度（高 / 中 / 低）
- 位置（文件 + 行号）
- 风险描述
- 建议

主代理之后看到合适的任务（比如你说"过一遍 auth 模块的安全"），会自动派 security-reviewer 子代理去干。

tools 字段限定子代理能用什么工具——这个 reviewer 不给 Edit / Write / Bash，确保它只读不写。

5. 子代理的边界

它不能做的事：

• 直接跟你说话：子代理的输出会回到主代理，主代理决定是否转告你。
• 持久记忆：子代理任务结束就消失，下次新派的是新实例。
• 看到主对话历史：除非主代理在派任务时主动塞过去（这是好事，避免污染）。

6. 怎么避免子代理"乱跑"

实战经验：

1. 写好 description。子代理的 description 决定主代理什么时候用它——写得糊涂会被乱调用。
2. 限定 tools。能不给的工具就不给。reviewer 不给 Bash，scanner 不给 Write。
3. review 输出。子代理交回来的报告主代理会按它的判断处理——但你要 review 主代理的处理，万一子代理胡说八道，至少在主代理回你之前你能拦下。

7. 一句话总结

子代理 = "派一个独立的小 Claude 去干一段活，跑完只回结果不回过程。"

理解这一点，你就理解了为什么 Claude Code 干 30 分钟的任务比 ChatGPT 一回合 5 分钟强——因为它内部全是这种"分而治之"。

---

子代理的可视化在 Claude 课 里——选 /scan-todo 场景看树状派工。