子代理 Subagents

子代理 Subagents

你在做一件复杂的事，比如重构一个大模块。你需要先探索当前代码长什么样，再制定方案，最后动手改。如果这三件事都你自己来，你的脑子（上下文）会被探索时读的几千行代码塞满，等到真正动手时已经记不清细节。

子代理就是解法。它是「外聘顾问」——你给它一个任务，它在独立的上下文里干完活，只把摘要交回来。它读的那一万行代码，不占你脑子的位置。

独立上下文：核心价值

这是 Subagent 最本质的特性。每个子代理有自己独立的上下文窗口：

• 主代理（你直接对话的 Claude）派任务给子代理
• 子代理在自己的上下文里探索、读文件、跑命令
• 干完活，子代理只返回一份摘要给主代理
• 子代理上下文里读的所有东西，不进入主代理的上下文

打个比方：你雇了个顾问去调研市场，他翻了一整柜资料、跑了十几个访谈，最后给你一份两页的总结报告。你拿到的是报告，不是那一柜资料。这就是「委托-返回」模式。

这解决了一个核心痛点：探索性任务会爆炸式吃 token。让 Explore 子代理去通读代码库，它读 10 万 token 也无所谓，回到你这里只有一份精炼摘要。

三个内置子代理

Claude Code 自带三个子代理，开箱即用：

子代理	职责	何时用
Explore	只读探索，不改任何东西	摸清代码结构、找实现位置
Plan	制定方案，不执行	想清楚怎么做再动手
General-purpose	通用任务，可读写	执行具体工作

你不用手动调用它们——主代理会根据任务自动判断要不要派子代理。但理解它们各自干什么，能帮你写更好的指令。

Explore：只读的侦察兵

Explore 子代理是个「侦察兵」。它只读不写，专门干探索的活：

• 通读代码库结构，画出模块关系
• 找到某个功能在哪个文件实现
• 摸清依赖关系、调用链

它的工具集是受限的——没有 Edit、Write 权限，只能读。这是有意设计：探索时不该动代码，避免边探边改引入混乱。

Plan：谋士

Plan 子代理负责「想」而不「做」。它接到任务后会制定方案、列出步骤、识别风险，但不执行任何改动。等它把方案交回来，你确认后再让主代理动手。

这是「先想后做」的实现方式——把思考和执行分开，避免脑子一热就开始改。

General-purpose：通用工兵

General-purpose 是个全能工兵，既能读又能写。适合需要实际干活的场景，比如「按这个方案把这三个文件重构一下」。

自定义子代理

内置三个不够用？你可以自定义。和命令、技能类似，子代理也是 markdown 文件：

.claude/agents/<name>.md

---
name: code-reviewer
description: 严格审查代码改动，按团队规范挑刺
tools: Read, Grep, Glob, Bash(git diff:*)
---

你是团队的资深代码审查员。你的职责：

1. 检查改动是否符合团队编码规范
2. 找出潜在的 bug、边界情况
3. 评估测试覆盖是否充分
4. 给出具体、可执行的修改建议

只做审查，不改代码。把发现整理成清单返回。

几个关键点：

• name + description：和 Skill 一样，是「标签」，主代理靠它判断该不该派这个子代理。
• tools 字段：这是子代理的核心控制项——限定它能用哪些工具。

tools 字段：给顾问划定权限边界

tools 是自定义子代理最重要的字段。它决定这个子代理能干什么、不能干什么。

tools: Read, Grep, Glob, Bash(git diff:*)

这行的意思是：这个子代理只能读文件、搜索、看 git diff，不能改任何东西。

为什么要限定？因为子代理是「外包出去」的，你不想让它越权。审查员就不该改代码，探索者就不该写文件。给每个子代理最小够用的权限，是安全的基本原则。

如果不写 tools 字段，子代理默认拥有完整工具集——这通常不是你想要的。

委托-返回：通信方式

主代理和子代理的通信是单向委托、单向返回：

1. 主代理委派：把任务描述给子代理。
2. 子代理独立干活：在自己的上下文里读文件、跑命令、思考。
3. 子代理返回摘要：把结果整理成一段文字交回。
4. 主代理接收：只拿到摘要，不拿到子代理的完整思考过程。

注意：主代理看不到子代理的中间过程。子代理读了什么、想了什么，主代理都不知道，只看到最终摘要。这既是省 token 的关键，也意味着你得把任务描述写清楚——子代理没有你的对话上下文，它只知道你给它的那段委派文字。

链式调用

子代理可以链式调用——主代理派 A，A 干完交回来，主代理再派 B，B 在 A 的结果上继续干。比如：

1. 派 Explore 子代理摸清代码结构 → 返回模块清单
2. 派 Plan 子代理基于清单制定重构方案 → 返回步骤
3. 你确认方案后，派 General-purpose 执行 → 返回改动结果

这种链式调用把「探索 → 计划 → 执行」拆成三段，每段独立上下文，互不污染。

一个限制：子代理不能再生子代理

这是重要的边界：子代理不能派子代理。

也就是说，委托只有一层。主代理可以派子代理，但子代理不能再去派「孙子代理」。这是有意的设计——避免无限嵌套导致失控。如果任务真的复杂到需要多级分解，应该由主代理来编排，分别派多个子代理。

/agents：管理子代理

用 /agents 命令可以：

• 查看当前有哪些子代理（内置 + 自定义）
• 创建新的子代理
• 编辑已有子代理的配置

这是子代理的管理入口，和 /hooks、/mcp 是同一类管理命令。

实战：探索一个陌生代码库

接手一个新项目，最经典的做法是派 Explore 子代理先去摸底：

请帮我探索这个代码库：
1. 项目的技术栈、构建工具
2. 目录结构和模块划分
3. 主要功能的入口在哪
4. 测试怎么组织、跑什么命令

不用改任何东西，把发现整理成一份摘要。

Explore 子代理会去读 package.json、tsconfig、目录结构、关键入口文件，可能在它的上下文里读了 5 万 token 的代码。但它交回来的，是一份几百 token 的精炼摘要。你拿到了信息，主上下文依然清爽。

一句话总结

Subagents 是外聘顾问——独立上下文干活，只交摘要回来，读多少都不占你脑子。三个内置：Explore 探、Plan 想、General-purpose 干。自定义用 tools 限定权限，委托-返回单向通信，不能嵌套但能链式。

---

下一站，去 钩子 Hooks 见识「不可贿赂的门卫」。🚀