08 Subagent：子Agent的妙用

定义

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

为什么需要Subagent

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

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

Subagent能做什么？

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

Subagent长什么样

示例

---
name: code-reviewer
description: 专业代码审查员。关注安全、性能、可维护性
tools: Read, Grep, Glob, Bash
model: sonnet
---

你是一名资深Code Reviewer，按以下流程工作：

1. 先跑 `git diff` 看本次改动
2. 只审修改过的文件
3. 按三个优先级输出意见：
   - 🔴 必须修：安全漏洞、逻辑错误
   - 🟡 建议修：性能隐患、可读性问题
   - 🟢 可以考虑：风格建议

每条意见都要给出具体的修改示例

要素

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

类型介绍

研究型

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

---
name: codebase-researcher
description: 代码库调研专员，需要跨多文件搜索分析时主动调用
tools: Read, Grep, Glob
model: sonnet
---

你的任务是回答关于代码库的问题：
1. 先用Glob定位相关文件
2. 用Grep搜关键符号和调用链
3. 读关键文件，理解上下文
4. 输出一份结构化答案：涉及哪些文件、核心逻辑、数据流向

不要修改任何文件。不要列出所有读过的文件——只讲结论

审查型

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

---
name: security-auditor
description: 代码安全审计员，涉及认证、加密、SQL、外部输入的改动主动调用
tools: Read, Grep, Glob
model: opus
---

你是安全审计员，专门找以下问题：
- SQL注入、命令注入、XSS
- 硬编码密钥、明文密码
- 未校验的用户输入
- 不安全的依赖

按严重程度输出：Critical / High / Medium / Low
每条问题给出文件路径+行号+修复建议

执行型

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

---
name: test-writer
description: 单元测试编写员，新功能或重构后主动调用
tools: Read, Write, Edit, Bash
model: sonnet
---

按以下流程写测试：
1. 读被测文件，理解接口和逻辑
2. 写覆盖正常路径、边界、异常的测试
3. 跑一次测试确认通过
4. 输出：新增的测试文件路径 + 覆盖的场景

3. 放置规则
   1. 用户级别（全局生效）
      1. 对你电脑上所有项目生效。适合放通用Subagent，比如code-reviewer这种不分项目的角色
      复制

      ~/.claude/agents/<name>.md

   2. 项目级别（仅在该项目内生效）
      1. 只对当前项目生效。适合放项目专属Subagent，比如熟悉本项目的migration-writer。可以提交到git，团队共享同一套Subagent
      复制

      你的项目根目录/.claude/agents/<name>.md

创建&管理Subagent

创建

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

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

   
2. 用 /agents 命令
   1. 在Claude Code中输入 /agents，选择"Create new agent"点击回车
   2. 选择创建方式，让Claude创建 or 自己写配置文件。推荐Claude直接创建，你描述需求即可
   3. 选择放置的位置，项目 or 全局
   4. 描述这个subagent的用途
   5. 选工具权限
   6. 选择模型
   7. Agent的背景色设置
   8. 设置Agent的记忆机制
      1. Agent记忆作用
         1. 有了记忆，Agent会携带之前窗口的工作记忆（比如你曾经纠正过它什么错误）。打开一个新的窗口，Agent不会失忆，会减少重复的踩坑和犯错
         2. 四种记忆设置

            设置	说明
            Project scope（推荐）	跟着项目 git 走，相当于团队共享的记忆。比如一个项目是多人协作，放到了github上。这份记忆，其他协作者使用这个agent也会受惠
            None	不产生记忆
            User scope	放在本地的跨项目的全局记忆
            Local scope	当前项目但不跟git走，适合你自己的独家记忆，不想让协作者看到

         
   9. 创建完成，Claude已经把Subagent创建完了。点击回车即可

调用

1. 自动匹配
   1. 主CC根据你说的任务内容匹配当前的Subagent的"description"字段，决定调哪个Subagent
2. 显式指定（自然语言）
   1. 直接点名，跟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来落地"单任务具体怎么做"

关键差异