Claude Code 子代理（Sub-agents）教程：创建、调用与实战用法
本文是一份 claude code sub-agents how to use guide，基于 Claude Code 的公开文档与通用用法整理；具体命令与配置字段以官方文档为准。
用 Claude Code 干复杂活的时候，你大概遇到过这两个烦恼：一是主对话越聊越长，翻过的大量文件把上下文塞满，模型开始「忘事」；二是同一类任务（比如代码审查、写测试）每次都要重新交代一遍要求。子代理（sub-agents）就是为这两个问题准备的：把一类任务交给一个有独立上下文窗口的专职助手去做，做完只把结论带回主对话。这篇 sub-agents tutorial 按「是什么 → 怎么建 → 怎么调 → 实战配置 → 常见坑」的顺序讲完，读完就能上手。
一、子代理是什么：独立上下文的专职助手
子代理是 Claude Code 里可以自定义的「分身」。每个子代理有三点关键性质：
独立上下文窗口：子代理在发起后自己去读文件、跑命令，这些中间过程不会挤占主对话的上下文；它只把最终结果返回给主对话。
专属系统提示与工具集：你可以给每个子代理单独写职责说明（system prompt），并限定它能用哪些工具——比如让审查型子代理只读不写。
可指定模型档位：重活用能力强的档位，例行活用便宜档位，成本上可以分开控制。
一句话判断要不要用子代理：这个任务的中间过程很长、但需要的只是结论——典型如全库检索、批量审查、并行调研。如果任务本身很轻，直接在主对话做反而更快。
二、如何创建子代理：agents 目录与 frontmatter
Claude Code 的子代理以 Markdown 文件定义，放在两个位置之一：
.claude/agents/—— 项目级，随仓库提交，团队共享；~/.claude/agents/—— 用户级，对你所有项目生效。
文件由 YAML frontmatter 加正文（正文即该子代理的系统提示）组成。一个最小的代码审查子代理长这样：
---
name: code-reviewer
description: 审查当前分支的代码改动，找缺陷与安全隐患。在写完一段代码后主动使用。
tools: Read, Grep, Glob, Bash
---
你是资深代码审查员。对传入的改动逐文件审查，输出按 BLOCKER / MAJOR / MINOR 分级的问题清单，
每条给出文件与行号。只读不改；没有问题时明确说「未发现阻断性问题」。三个字段的要点：
name：小写连字符命名，是显式调用时的名字。
description：最重要也最容易被写坏的行——它既是自动委派的触发依据，也应该写清「什么时候用」。建议格式：「做什么 + 什么场景该用（when to use）」。
tools：可选。不写则继承全部工具；按最小权限原则只给必需工具（比如审查型就别给写文件权限）。
也可以不手写文件，在交互会话里输入 /agents 按引导创建，效果相同。
三、子代理怎么被调用：自动委派与显式调用
配置好之后有两种用法：
自动委派：Claude Code 会拿当前任务和每个子代理的 description 做匹配，匹配上就自动把任务交给它。这就是 description 要写清「使用场景」的原因——写得越具体，自动触发越准。
显式调用：在对话里直接点名，例如「用 code-reviewer 审一下这次改动」。要指定行为细节时也用这种方式，比如「用 code-reviewer，只看认证模块」。
两个使用要点：
并行：多个相互独立的子代理可以在同一条消息里一起派出（比如同时让两个子代理分别调研不同模块），总耗时约等于最慢的那个。
传上下文：子代理看不到你们之前的对话内容，它在发起时是「新人」。所以派单时把必要背景写进请求里（目标、约束、相关文件路径），别指望它自己猜。
四、三个值得抄的配置模式
专职审查者：像第二节那样建 code-reviewer，只读工具 + 分级输出。它每次审查都带着同样的标准，比主对话里随手一句「帮我看看」稳定得多。
调试专班：name: debugger，给它 Bash 与检索工具，系统提示里写死流程——先复现、再定位、给出根因与最小修复建议，不允许顺手大改。调试过程产生的海量日志都留在它自己的上下文里，主对话只收结论。
模型分档：例行、机械的子代理（批量重命名、格式检查）在 frontmatter 里指定轻量档位；疑难分析才用重型档位。子代理是按各自档位计费的，分档是直接的成本杠杆。
最后是数量与命名的建议：宁可少而专，不要多而杂。一个子代理只负责一类任务，名字直接表意（code-reviewer、test-writer），控制在十个以内——列表越长，自动委派的匹配就越容易失准，维护成本也越高。先从一两个高频任务开始配，跑顺了再逐步加。
五、常见坑与排查
写了子代理却从不触发：九成是 description 太含糊（比如「帮我干活」）。把使用场景写实：输入是什么、什么时候该用它。
子代理「不知道」你们聊过的内容：不是 bug，是设计。需要的背景放进派单请求。
权限报错：检查 frontmatter 的 tools 是否漏给了必需工具。
结果质量差：多半是系统提示太薄。把输出格式、分级标准、禁止事项写进正文，把它当一个新员工的岗位说明书来写。
如果你还没用过 Claude Code，建议先读我们的 Claude Code 入门教程，再回头配子代理；需要给子代理接外部工具时，参考 Claude Code MCP 服务器配置指南。
六、没有官方 key？从 CodeGateway 开始跑
在官方渠道使用 Claude Code 需要 API key 与海外支付方式，这一步拦住了不少人。如果你没有官方 key、或不想绑外卡，可以直接在 [CodeGateway](https://www.codegateway.dev/pricing) 拿一个：注册即用，提供 OpenAI / Anthropic 兼容端点，Claude Code 与子代理功能照常使用。先到模型目录确认在售模型，再小额度跑通第一个子代理，验证流程后放量即可。
本文为工具使用教程，基于 Claude Code 公开文档整理；界面与字段可能随版本变化，以官方文档为准。