08 Subagent：子Agent的妙用

定义

Subagent就像你的专职员工，完成一个特定的任务、有自己的权限范围。Claude Code是Subagent们的主管，遇到哪类活就派给对应的员工，对方独立干完把结果交回来

为什么需要Subagent

1. 你在使用CC做长任务时一定遇到过一个问题

上下文被挤爆，任务越做越乱 一个复杂任务，CC可能先阅读几十篇文章（读了20个文件）→ 再写实现 → 再跑测试 → 再做review 这个过程所有命令、尝试步骤、调研笔记，全部挤进主对话的上下文 几轮之后，CC就自动Compact，开始"健忘"。开始对你最初的需求有些模糊，忘了之前定好的规则，甚至开始胡来

1. Subagent不会让这种情况发生

Subagent让主上下文始终干净 把"调研任务"丢给research-subagent，它在自己的上下文里读20个文件，只把一份总结交给主Claude Code 把"代码Review"丢给reviewer-subagent，它独立读代码、独立思考，只把意见交给主CC Claude Code主会话的上下文不被污染，相当于把指挥官和执行者的频道分开了

Subagent能做什么？

1. 上下文隔离
2. 调研、读文件、跑长命令都在子上下文完成，主上下文只收最终结论，不被噪音淹没
3. 专职专能
4. 每个Subagent只干一件事。code-reviewer就是审代码，test-writer就是写测试，debugger就是排查bug
5. 权限控制
6. 可以给Subagent单独配工具权限。reviewer只开Read/Grep，连改代码的权限都没有，从机制上防止越权
7. 成本优化
8. 复杂任务交给主Opus，简单活交给Haiku版Subagent，同样的活单位成本大幅下降

Subagent长什么样

示例

---name: code-reviewerdescription: 专业代码审查员。关注安全、性能、可维护性tools: Read, Grep, Glob, Bashmodel: sonnet---你是一名资深Code Reviewer，按以下流程工作：1. 先跑 `git diff` 看本次改动2. 只审修改过的文件3. 按三个优先级输出意见：   - 🔴 必须修：安全漏洞、逻辑错误   - 🟡 建议修：性能隐患、可读性问题   - 🟢 可以考虑：风格建议每条意见都要给出具体的修改示例

要素

1. name
2. Subagent的唯一标识，小写+连字符（如 code-reviewer），主CC靠这个名字调用它
3. description
4. 最关键的字段。主CC读description判断"什么时候该叫这个Subagent"。写得越具体越容易被自动路由
5. 小技巧：在description里加上"主动调用 / use proactively"，CC会更积极地调用它
6. tools
7. 给这个Subagent开哪些工具权限。不填则默认继承主CC的全部权限
8. 建议做权限控制，如code reviewer只开Read/Grep就够，不给Edit/Write
9. model
10. 指定用哪个模型。简单审查用haiku省钱，中等任务用sonnet，复杂推理用opus
11. 正文（system prompt）
12. YAML下面的Markdown提示词就是这个Subagent的"落地指南"。要写清楚：它是谁、按什么流程干活、输出什么格式

类型介绍

研究型

1. 适用场景
2. 需要大量读文件、搜代码、查文档，输出一份总结报告。典型场景：技术方案调研、市场调研、竞品研究
3. 示例

---name: codebase-researcherdescription: 代码库调研专员，需要跨多文件搜索分析时主动调用tools: Read, Grep, Globmodel: sonnet---你的任务是回答关于代码库的问题：1. 先用Glob定位相关文件2. 用Grep搜关键符号和调用链3. 读关键文件，理解上下文4. 输出一份结构化答案：涉及哪些文件、核心逻辑、数据流向不要修改任何文件。不要列出所有读过的文件——只讲结论

审查型

1. 适用情况
2. 只读操作，给主CC提意见不动手。典型场景：Code Review、安全审查
3. 示例

---name: security-auditordescription: 代码安全审计员，涉及认证、加密、SQL、外部输入的改动主动调用tools: Read, Grep, Globmodel: opus---你是安全审计员，专门找以下问题：- SQL注入、命令注入、XSS- 硬编码密钥、明文密码- 未校验的用户输入- 不安全的依赖按严重程度输出：Critical / High / Medium / Low每条问题给出文件路径+行号+修复建议

执行型

1. 适用情况
2. 需要动手改代码或跑命令的任务。典型场景：修bug、写测试、跑部署
3. 示例

---name: test-writerdescription: 单元测试编写员，新功能或重构后主动调用tools: Read, Write, Edit, Bashmodel: sonnet---按以下流程写测试：1. 读被测文件，理解接口和逻辑2. 写覆盖正常路径、边界、异常的测试3. 跑一次测试确认通过4. 输出：新增的测试文件路径 + 覆盖的场景

1. 放置规则
2. 用户级别（全局生效） 1. 对你电脑上所有项目生效。适合放通用Subagent，比如code-reviewer这种不分项目的角色 ``` ~/.claude/agents/<name>.md

  2. 项目级别（仅在该项目内生效）
    1. 只对当前项目生效。适合放项目专属Subagent，比如熟悉本项目的migration-writer。可以提交到git，团队共享同一套Subagent
    ```
你的项目根目录/.claude/agents/<name>.md

创建&管理Subagent

创建

1. 让Claude Code帮你创建（推荐）
2. 一句话描述你要什么，Claude Code帮你生成完整Subagent文件

帮我创建一个Subagent，叫geo hunter。职责是认真研究1个网站的geo策略，给出详细的geo报告只能用Read/Write/Bash模型用sonnet

2. 用 /agents 命令
3. 在Claude Code中输入 /agents，选择"Create new agent"点击回车
4. 选择创建方式，让Claude创建 or 自己写配置文件。推荐Claude直接创建，你描述需求即可
5. 选择放置的位置，项目 or 全局
6. 描述这个subagent的用途
7. 选工具权限
8. 选择模型
9. Agent的背景色设置
10. 设置Agent的记忆机制 1. Agent记忆作用
    1. 有了记忆，Agent会携带之前窗口的工作记忆（比如你曾经纠正过它什么错误）。打开一个新的窗口，Agent不会失忆，会减少重复的踩坑和犯错
    2. 四种记忆设置 | 设置 | 说明 | | --- | --- | | Project scope（推荐） | 跟着项目 git 走，相当于团队共享的记忆。比如一个项目是多人协作，放到了github上。这份记忆，其他协作者使用这个agent也会受惠 | | None | 不产生记忆 | | User scope | 放在本地的跨项目的全局记忆 | | Local scope | 当前项目但不跟git走，适合你自己的独家记忆，不想让协作者看到 |
11. 创建完成，Claude已经把Subagent创建完了。点击回车即可

调用

1. 自动匹配
2. 主CC根据你说的任务内容匹配当前的Subagent的"description"字段，决定调哪个Subagent
3. 显式指定（自然语言）
4. 直接点名，跟Claude Code说：用code-reviewer agent审一下刚改的登录模块

管理

查看Subagent

1. 在Claude Code中输入 /agents，点击键盘上的➡️，切换到Library。可以看到所有已配置的Subagent

修改Subagent

1. 在Agents Library中，选择对应的Agent，点击回车。选择「Edit agent」
2. 你可以选择在编辑器里统一修改“Open in editor”，或者单独编辑工具、模型或配色 比如这是我常用的vs code自带的编辑器，可以自己修改描述、模型、工具权限等

删除Subagent

1. 依旧是从Library选择特定的Agent，点击「Delete agent」

Subagent vs Skill

一句话

1. Skill是一条工作流水线，Subagent是流水线上的工作单元。Skill定义"多任务全流程怎么做"，Subagent来落地"单任务具体怎么做"

关键差异