Subagent

派一个子 agent 去做独立任务，保护主 loop 的上下文。

Task 工具是什么

Claude Code 主 loop 里有一个内置工具叫 Task，它的作用只有一个：起一个子 agent 去干一件事，等这个子 agent 干完，把最终结果作为一条消息塞回主 loop。

这件事听起来平平无奇，但它解决的是 agent 系统里一个真实痛点：上下文污染。主 loop 里如果一件事情要读 20 个文件才能给出答案，这 20 个文件的内容全部会留在主上下文里，后面每一次对话都要带着它们走。派一个子 agent 去读，读完只把结论传回来，主上下文只多了一条消息，噪音全部隔离在子 agent 那边。

子 agent 是全新上下文

Task 派出去的默认是一个 fresh context 的子 agent。它看不到你和主 agent 的对话历史，看不到主 agent 已经读过的文件，也看不到当前项目的 CLAUDE.md 之外的自定义状态。它拿到的只有一个东西：你在 Task 调用里写的那段 prompt。

这一点决定了怎么写 prompt：不能像跟主 agent 说话那样"接着刚才那个 bug 修一下"，得像给一个刚入职的同事交代任务一样，把背景、目标、涉及文件路径全部写清楚。

例外：fork

Claude Code 还有一种特殊的子 agent 叫 fork，它继承主 agent 的完整上下文。fork 用来处理那种"我要做一次开放性调研，但结果里的中间产物我不想留在自己脑子里"的场景。fork 走完，主 agent 只拿到最终结论。判断标准是："这一堆中间输出我以后还用得上吗？"用不上就 fork。

内置的 agent 类型

主 loop 里能派出去的子 agent 分几种类型，每种类型自带一套预设的工具权限和系统 prompt。

general-purpose：万能型，能读能写能搜索能执行 bash。绝大多数搜索、探索、研究类任务用这个。

code-reviewer：只读工具集，专门用来做代码评审。给它一个 diff、一个 PR 链接或者一段代码，它会独立给出评审意见。因为是新上下文，不会被主 agent 已经"想通了这段代码"的偏见影响。

statusline-setup / output-style-setup：非常窄的用途，只帮你配 Claude Code 的状态栏和输出样式。

不同发行版里内置类型可能略有差异，用 /agents 命令能查当前会话里能调的所有类型。

什么时候派 subagent

判断依据其实很直接：这件事的中间过程你到底在不在乎。

搜索类任务：项目里有 5000 个文件，你想找某个函数在哪调用过。让主 agent 一个个 grep，中间产物爆炸。派一个 general-purpose，它自己 grep、自己筛、只把最后的位置清单还给你。

独立评审：你刚写完一段代码，想让一个"没看过你思路"的评审者来找茬。主 agent 已经站在你这边了，它会替你合理化。派一个 code-reviewer，fresh context，天然中立。

大范围 refactor：改一个函数签名，有 30 处调用要跟着改。你可以派多个子 agent 并行处理不同目录，每人管一片，最后主 agent 汇总。

并行调研：想同时问三个独立问题，比如"这个库的性能、许可证、社区活跃度"。一条消息里发三个 Task，三个 subagent 并行跑，速度是串行的三倍。

定义自己的 agent 类型

内置类型不够用时，可以在 .claude/agents/ 下丢一个 markdown 文件定义新类型。文件名就是 agent 名，frontmatter 里写元信息，正文是这个 agent 的系统 prompt。

---
name: security-auditor
description: 独立审计代码中的安全漏洞
tools: [Read, Grep, Glob, Bash]
model: opus
---

你是一位资深的安全审计工程师。收到代码或 diff 后，你需要：

1. 逐文件通读，标出所有可能的漏洞点：SQL 注入、XSS、CSRF、
   路径穿越、命令注入、密钥泄漏、不安全的反序列化。
2. 每个发现给出：文件路径 + 行号 + 漏洞类型 + 攻击场景 + 修复建议。
3. 报告不超过 500 字，只留高置信度问题，低置信度直接丢掉。

放好之后主 agent 就能派 security-auditor 类型的 subagent 了。团队共用的放 .claude/agents/，只有自己用的放 ~/.claude/agents/。

一个案例：让 subagent 独立评审 PR

主 loop 里你可以这样调（自然语言就行，Claude Code 会自己拼 Task 参数）：

用 code-reviewer 独立评审当前 diff。重点看：
1. 有没有把敏感字段写进日志。
2. 有没有新的外部依赖没在 package.json 声明。
3. 错误处理是不是覆盖了所有可能失败的 IO 路径。
只报高置信度问题，200 字以内。

主 agent 收到之后会调 Task，起一个 code-reviewer 子 agent，把 diff 塞给它。子 agent 独立跑 grep、读文件，最后返回一段浓缩的评审意见。整个过程主上下文里只多了两条消息：一条 Task 调用、一条评审结论。

这一层机制配合 skill、CLAUDE.md 一起用，就能搭出很有意思的多层结构：主 agent 编排流程，subagent 负责专业环节，每一层都保持自己的上下文干净。

用 subagent 的几条注意

别为了用而用。派 subagent 有成本：多起一个 LLM 会话、多一层通信开销、总 token 消耗更多。任务本身就三步的小事直接让主 agent 干，别搞得像微服务架构。

prompt 要自包含。fresh context 意味着子 agent 不知道你在聊什么。文件路径要写全绝对路径、涉及的函数名要写全、判断标准要列清楚。少一个前提，子 agent 就会瞎猜。

结果要求要具体。让子 agent"评审代码"太宽泛，回来的东西会又臭又长塞爆主上下文。明确要求"200 字以内、只列高置信问题、每条包含文件路径和行号"，回来的东西才好用。

并行时要独立。同一条消息里派多个 subagent 时，它们之间不会通信。别把有依赖的任务并行拆，比如"A 查数据、B 基于 A 的结果分析"这种，A 和 B 得串行。

和 fork 的实际选择

判断标准就一条：中间产物对你有价值吗？

写代码找 bug、开放性调研、看代码通读一遍，这些任务的中间探索路径可能对你后续判断有帮助，但没必要留在主上下文里。fork 一份，让它带着你现在的语境去挖，挖完只给你结论。

搜索、独立评审、重复性检查，这些任务的中间过程对你完全没意义，甚至最好别看到，用 fresh subagent 更干净。