×−+
子代理第 8 课 · Claude Code 教程
第 8 课 · SUBAGENTS

子代理:
找个同事帮忙

让 Claude 翻遍整个仓库、跑完所有测试,结果全堆在你的对话里,桌面很快就乱了。子代理像一位同事:拿着任务去自己的桌子上干,回来只交一页结论。

约 45 分钟 11 节 · 8 个动手练习 章末测验 改编自 luongnv89/claude-howto(MIT)
你的对话
⇄派任务
交结论
子代理的桌子
入门先用起来 原理弄懂为什么 实战动手练 深入进阶与避坑

时间紧就先看"入门"和"实战";"原理"讲清楚子代理带走什么、看不到什么,决定你派出去的活能不能干好。

01入门

子代理是什么?

子代理是另一个 Claude:有自己的上下文、自己的说明书、自己能用的工具。Claude 把一块活交给它,它干完只把结论交回来。

它能帮你做到这几件事:

  • 保持对话干净:搜索结果、测试日志、一大堆文件内容留在子代理那边,你的对话里只多一段结论。
  • 限制权限:只给它读文件的工具,它就改不了代码。
  • 专人专事:一份专门写给"代码审查"的说明书,比一句"帮我看看代码"靠谱。
  • 省钱:简单的活可以交给更快、更便宜的模型,比如 Haiku。

什么时候派,什么时候自己做

留在主对话派给子代理
要来回商量、反复修改会产生大量你之后用不上的输出(日志、搜索结果)
计划、实现、测试几个阶段要共用很多背景想限制它能用的工具或权限
改一两行的小改动活是独立的,最后交一份总结就行
着急要结果(子代理从零开始,要先花时间了解情况)几件事互不相关,可以同时开工
和前几课的东西怎么分

Skill(第 5 课)是一本操作手册,在主对话里照着做;子代理是一位同事,在另一张桌子上做。只是想问一句关于当前对话的小问题,用第 1 课的 /btw 就行,它能看到整个对话,回答也不会留在记录里。

02入门

现成的几位同事

不用任何配置,Claude Code 自带几个子代理,Claude 会在合适的时候自己派它们出去。

子代理能做什么什么时候用
Explore只读,不能改文件。模型跟你的对话一样,但最高到 Opus在代码库里找东西、弄懂代码。Claude 会指定"快速 / 适中 / 非常彻底"三种细致程度
Plan只读,模型跟你的对话一样规划模式里先调研代码,再给你出方案(第 9A 课)
general-purpose子代理能用的工具都能用,能改代码又要查、又要改的多步任务
claude子代理能用的工具都能用哪个专门的都不合适时的"万能工"
statusline-setup 等专用助手运行 /statusline、问 Claude Code 用法时自动出场
  • Explore 和 Plan 不读 CLAUDE.md,也不拿 git 状态,为的是查得快、花得少。其余子代理都会读。
  • 内置子代理默认都在。想禁用某一个,在设置的 permissions.deny 里写 Agent(Explore);想让 Claude 完全不派子代理,禁用 Agent 工具本身。
03入门

请一位自己的专职同事

子代理就是一个 Markdown 文件:开头写配置,下面写它的说明书。最简单的做法是让 Claude 帮你写。

① 让 Claude 写

对 Claude 说
在 ~/.claude/agents/ 里建一个个人用的 code-improver 子代理:检查代码的可读性、性能和最佳实践,每个问题都要解释原因、给出现在的代码和改进后的代码。它只能读、不能改,用 Sonnet 模型。

② 检查它写的文件

~/.claude/agents/code-improver.md
---
name: code-improver
description: Scans files and suggests improvements for readability, performance, and best practices. Use after writing or modifying code.
tools: Read, Grep, Glob
model: sonnet
---

You are a code improvement specialist. For each issue you find, explain
the problem, show the current code, and provide an improved version.

③ 派它去干活

说"用 code-improver 看看这个项目有什么能改进的"。对话里会出现一行 code-improver(…),表示任务交给了它。找不到它的话,重启一次 Claude Code。只有 ~/.claude/agents/ 是这次会话开始后才新建的,才会这样。

文件放在哪

位置对谁有效同名时的优先级
组织策略设置整个公司1(最高)
启动时的 --agents 参数这一次会话,不存盘2
.claude/agents/当前项目,可以提交到 git 和团队共用3
~/.claude/agents/你的所有项目4
插件的 agents/装了这个插件时(第 10 课)5(最低)
/agents 不再是创建向导

老教程里常说"输入 /agents 打开向导创建子代理"。从 v2.1.198 起这个向导取消了,现在只会提示你:让 Claude 写,或者直接编辑 .claude/agents/ 里的文件。改完文件几秒钟内就生效,不用重启。

04入门

练一练:这件事交给谁?

每个场景选一个最合适的做法。

05原理

派出去的同事带着什么

子代理从一张空桌子开始:看不到你们之前的对话。它手里只有 Claude 写给它的任务说明,外加几样固定的东西。

所以任务要交代清楚

Claude 会替你写任务说明,但你在对话里说过的某些要求(比如"别动 vendor 目录"),它不一定会写进去。重要的限制,在派活时明确说一遍。

06原理

配置文件逐行看

只有 name 和 description 是必填的,其余都能省。点带色条的行看解释。

.claude/agents/test-runner.md
全部字段一览
name 名字(必填,不能带冒号,也不能以 - 开头)· description 什么时候派它(必填)· tools 能用的工具 · disallowedTools 不许用的工具 · model 模型 · permissionMode 权限模式 · maxTurns 最多几步 · skills 预先加载的 skill · mcpServers 能用的 MCP 服务器 · hooks 只对它生效的 hook · memory 它自己的长期记忆 · background 总在后台跑(交互模式下子代理本来就都在后台,这个字段主要对 -p 有用) · effort 思考力度 · isolation 设为 worktree 时在独立的仓库副本里干活(副本默认从默认分支拉出来,不是你当前的分支) · omitClaudeMd 不读 CLAUDE.md · color 显示颜色 · initialPrompt 作为整个会话的主角时自动发的第一句话 · experimental 实验选项(目前只有 cacheTtl,控制提示缓存留多久)。字段名大小写要写对,写错的会被悄悄忽略。
07原理

前台、后台与 fork

派出去的同事可以让你等着(前台),也可以你继续干你的(后台)。还有一种特别的:带着整段对话出去的 fork。

前台后台
你能不能继续要等它干完能,它在旁边同时干
要权限时直接问你也会在你的主对话里问你,并说明是哪个子代理在要;按 Esc 只拒绝这一次
默认是哪种交互模式下默认后台。按 Ctrl+B 能把正在前台跑的任务挪到后台;/tasks 查看所有子代理

fork:带着整段对话出去的同事

普通子代理从零开始;fork 继承到目前为止的全部对话,不用再解释背景。它干活的过程同样不进你的对话,只交回结果。输入 /subtask 任务 手动开一个:

对话里
/subtask 根据我们刚才改的解析器,草拟单元测试
fork普通子代理
上下文整段对话从零开始,只有任务说明
说明书和工具和主对话一样来自它的配置文件
模型和主对话一样来自配置里的 model
费用能复用主对话的缓存,更省单独的缓存
别和第 5 课的 context: fork 搞混

第 5 课 skill 里的 context: fork 名字里也有 fork,但它派出去的是一个普通子代理,看不到你们的对话。这里讲的 fork 才带着整段对话出去。

也别和 /fork 搞混:/fork 是把整个会话复制成一个独立的后台会话,结果不回到这里(第 9B 课)。/subtask 要 v2.1.212 以上;更早的版本,或者关掉了代理视图时,这个功能叫 /fork。

接着干、同时干、层层派

  • 接着干:子代理干完后,说"接着刚才的审查,再看看权限逻辑",Claude 会叫回同一个子代理,它记得之前做过的一切。Explore 和 Plan 是一次性的,叫不回来。
  • 同时干:"分别用子代理并行研究登录、数据库、接口三个模块"。注意每个子代理的结论都会回到你的对话,派得太多、结论太长,一样会占满上下文。
  • 层层派:子代理还能再派子代理,默认最多往下三层;同一时间默认最多 20 个在跑,两个上限都能用环境变量改。
08实战

子代理生成器

填表,实时生成配置文件,并按官方建议自动体检。也可以从原仓库的 9 个模板开始改。

从例子开始:
基本
name
description
放在哪
能做什么
tools
一个都不勾 = 继承所有能用的工具
model
权限模式
记忆
独立仓库副本 isolation: worktree
说明书
保存为

原仓库的 9 个模板

保留英文原文。拿去用之前,按上面的体检项看一遍 tools 和 description 合不合你的需要,再删掉末尾那段 Last Updated / Compatible Models 页脚:它在正文里,会跟着说明书一起发给子代理,白占上下文。

保存到 .claude/agents/
09实战

终端演练:请一位审查员

建一个代码审查子代理,派它干活,再同时派三个 Explore 去调研。点"下一步"回放,放完可以自己输入。

my-app — claude — 90×28
>

终端画面为教学示意,审查结果、步数、token 数、用时都是虚构的;子代理的工作方式与真实的 Claude Code 一致。

10深入

进阶与避坑

派不出去、不按预期干活、上下文还是爆了……按症状查。

建好的子代理,Claude 就是不派
  1. Claude 靠 description 决定派谁。写清楚"什么时候用",想让它主动派,加上 "use proactively"。
  2. 几个子代理的描述写得太像,Claude 分不清。每个描述要能单独点出"就是它"。
  3. 直接点名:"用 test-runner 修一下失败的测试"。要保证一定派它,输入 @ 从列表里选,会变成 @"test-runner (agent)"。
文件放进去了,但好像没被加载
这几种情况会被悄悄跳过:没写 name;有 name 没 description;开头的 --- 不在第一行;名字以 - 开头或带 :;YAML 格式错误。用 claude --debug 启动看日志;想先查 YAML 有没有写错,运行 claude plugin validate .claude/agents(它不查漏写 name)。另外,如果 agents 文件夹是会话开始后才新建的,要重启一次。
我在 disallowedTools 里写了 Bash(git push *),结果整个 Bash 都没了
在子代理的 disallowedTools 里,带括号的写法也会拿走整个工具。只想拦某些命令,把 Bash(git push *) 写进设置的 permissions.deny,它对主对话和子代理都生效;或者给子代理挂一个 PreToolUse hook(第 6 课)。
给子代理设了 permissionMode,却没效果
主对话在 acceptEdits、auto 或 bypassPermissions 模式下时,子代理跟主对话走,忽略你设的值。主对话在 Manual(default)、dontAsk、plan 模式下时,才按你设的来;但子代理自己设 bypassPermissions 不行,它会沿用主对话的模式。
想让所有子代理都用便宜的模型
在设置的 env 里写 CLAUDE_CODE_SUBAGENT_MODEL,比如 haiku。它只是默认值:子代理自己写了 model 的、Claude 派活时指定了模型的,都按那个来;内置的 Explore 和 Plan 也不受它影响。要强制全部统一,再加 CLAUDE_CODE_SUBAGENT_MODEL_FORCE=1,连 Explore、Plan 也会换。fork 例外,始终和主对话一样。
插件带来的子代理,hooks 和 mcpServers 不生效
出于安全考虑,插件里的子代理会忽略 hooks、mcpServers、permissionMode 三个字段。需要的话,把文件拷到 .claude/agents/ 或 ~/.claude/agents/ 再改。
派了很多子代理,上下文还是满了
每个子代理的结论都会回到你的对话。并行派出去的越多、要求的汇报越详细,占的地方越大。派活时说清楚"只汇报失败的测试和错误信息"这类要求,让结论短一点。
整个会话都让某个子代理当主角
claude --agent code-reviewer 启动后,主对话直接用它的说明书、工具限制和模型,启动画面会显示 @code-reviewer。想让某个项目默认这样,在 .claude/settings.json 里写 "agent": "code-reviewer"。
老教程里的说法和官方不一样
  1. 说 claude agents 会列出配置好的子代理:官方文档里它打开的是"代理视图",用来管理后台运行的会话,不是子代理清单。
  2. 文件位置的优先级漏了组织策略下发的子代理,它的优先级比 --agents 还高。
  3. 说后台子代理遇到权限请求会自动拒绝:v2.1.186 起改成在主对话里问你。
  4. 说在子代理配置里写 context: fork 就能继承整段对话:子代理没有这个字段。context: fork 是 skill 的字段(第 5 课),而且恰恰看不到对话。
11检验

小测验

8 道题,每题选完会立刻看到解析。