子代理:
找个同事帮忙
让 Claude 翻遍整个仓库、跑完所有测试,结果全堆在你的对话里,桌面很快就乱了。子代理像一位同事:拿着任务去自己的桌子上干,回来只交一页结论。
你的对话
交结论
子代理的桌子
时间紧就先看"入门"和"实战";"原理"讲清楚子代理带走什么、看不到什么,决定你派出去的活能不能干好。
子代理是什么?
子代理是另一个 Claude:有自己的上下文、自己的说明书、自己能用的工具。Claude 把一块活交给它,它干完只把结论交回来。
它能帮你做到这几件事:
- 保持对话干净:搜索结果、测试日志、一大堆文件内容留在子代理那边,你的对话里只多一段结论。
- 限制权限:只给它读文件的工具,它就改不了代码。
- 专人专事:一份专门写给"代码审查"的说明书,比一句"帮我看看代码"靠谱。
- 省钱:简单的活可以交给更快、更便宜的模型,比如 Haiku。
什么时候派,什么时候自己做
| 留在主对话 | 派给子代理 |
|---|---|
| 要来回商量、反复修改 | 会产生大量你之后用不上的输出(日志、搜索结果) |
| 计划、实现、测试几个阶段要共用很多背景 | 想限制它能用的工具或权限 |
| 改一两行的小改动 | 活是独立的,最后交一份总结就行 |
| 着急要结果(子代理从零开始,要先花时间了解情况) | 几件事互不相关,可以同时开工 |
Skill(第 5 课)是一本操作手册,在主对话里照着做;子代理是一位同事,在另一张桌子上做。只是想问一句关于当前对话的小问题,用第 1 课的 /btw 就行,它能看到整个对话,回答也不会留在记录里。
现成的几位同事
不用任何配置,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工具本身。
请一位自己的专职同事
子代理就是一个 Markdown 文件:开头写配置,下面写它的说明书。最简单的做法是让 Claude 帮你写。
① 让 Claude 写
在 ~/.claude/agents/ 里建一个个人用的 code-improver 子代理:检查代码的可读性、性能和最佳实践,每个问题都要解释原因、给出现在的代码和改进后的代码。它只能读、不能改,用 Sonnet 模型。
② 检查它写的文件
--- 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 打开向导创建子代理"。从 v2.1.198 起这个向导取消了,现在只会提示你:让 Claude 写,或者直接编辑 .claude/agents/ 里的文件。改完文件几秒钟内就生效,不用重启。
练一练:这件事交给谁?
每个场景选一个最合适的做法。
派出去的同事带着什么
子代理从一张空桌子开始:看不到你们之前的对话。它手里只有 Claude 写给它的任务说明,外加几样固定的东西。
Claude 会替你写任务说明,但你在对话里说过的某些要求(比如"别动 vendor 目录"),它不一定会写进去。重要的限制,在派活时明确说一遍。
配置文件逐行看
只有 name 和 description 是必填的,其余都能省。点带色条的行看解释。
全部字段一览
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,控制提示缓存留多久)。字段名大小写要写对,写错的会被悄悄忽略。
前台、后台与 fork
派出去的同事可以让你等着(前台),也可以你继续干你的(后台)。还有一种特别的:带着整段对话出去的 fork。
| 前台 | 后台 | |
|---|---|---|
| 你能不能继续 | 要等它干完 | 能,它在旁边同时干 |
| 要权限时 | 直接问你 | 也会在你的主对话里问你,并说明是哪个子代理在要;按 Esc 只拒绝这一次 |
| 默认是哪种 | 交互模式下默认后台。按 Ctrl+B 能把正在前台跑的任务挪到后台;/tasks 查看所有子代理 | |
fork:带着整段对话出去的同事
普通子代理从零开始;fork 继承到目前为止的全部对话,不用再解释背景。它干活的过程同样不进你的对话,只交回结果。输入 /subtask 任务 手动开一个:
/subtask 根据我们刚才改的解析器,草拟单元测试
| fork | 普通子代理 | |
|---|---|---|
| 上下文 | 整段对话 | 从零开始,只有任务说明 |
| 说明书和工具 | 和主对话一样 | 来自它的配置文件 |
| 模型 | 和主对话一样 | 来自配置里的 model |
| 费用 | 能复用主对话的缓存,更省 | 单独的缓存 |
第 5 课 skill 里的 context: fork 名字里也有 fork,但它派出去的是一个普通子代理,看不到你们的对话。这里讲的 fork 才带着整段对话出去。
也别和 /fork 搞混:/fork 是把整个会话复制成一个独立的后台会话,结果不回到这里(第 9B 课)。/subtask 要 v2.1.212 以上;更早的版本,或者关掉了代理视图时,这个功能叫 /fork。
接着干、同时干、层层派
- 接着干:子代理干完后,说"接着刚才的审查,再看看权限逻辑",Claude 会叫回同一个子代理,它记得之前做过的一切。Explore 和 Plan 是一次性的,叫不回来。
- 同时干:"分别用子代理并行研究登录、数据库、接口三个模块"。注意每个子代理的结论都会回到你的对话,派得太多、结论太长,一样会占满上下文。
- 层层派:子代理还能再派子代理,默认最多往下三层;同一时间默认最多 20 个在跑,两个上限都能用环境变量改。
子代理生成器
填表,实时生成配置文件,并按官方建议自动体检。也可以从原仓库的 9 个模板开始改。
原仓库的 9 个模板
保留英文原文。拿去用之前,按上面的体检项看一遍 tools 和 description 合不合你的需要,再删掉末尾那段 Last Updated / Compatible Models 页脚:它在正文里,会跟着说明书一起发给子代理,白占上下文。
.claude/agents/终端演练:请一位审查员
建一个代码审查子代理,派它干活,再同时派三个 Explore 去调研。点"下一步"回放,放完可以自己输入。
终端画面为教学示意,审查结果、步数、token 数、用时都是虚构的;子代理的工作方式与真实的 Claude Code 一致。
进阶与避坑
派不出去、不按预期干活、上下文还是爆了……按症状查。
建好的子代理,Claude 就是不派
- Claude 靠
description决定派谁。写清楚"什么时候用",想让它主动派,加上 "use proactively"。 - 几个子代理的描述写得太像,Claude 分不清。每个描述要能单独点出"就是它"。
- 直接点名:"用 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"。老教程里的说法和官方不一样
- 说
claude agents会列出配置好的子代理:官方文档里它打开的是"代理视图",用来管理后台运行的会话,不是子代理清单。 - 文件位置的优先级漏了组织策略下发的子代理,它的优先级比
--agents还高。 - 说后台子代理遇到权限请求会自动拒绝:v2.1.186 起改成在主对话里问你。
- 说在子代理配置里写
context: fork就能继承整段对话:子代理没有这个字段。context: fork是 skill 的字段(第 5 课),而且恰恰看不到对话。
小测验
8 道题,每题选完会立刻看到解析。
