概述

本教程带你掌握 Claude Code 的子代理（Subagents）机制：用一份份带 YAML frontmatter 的 Markdown 文件，定义一批"专职小工"——代码审查员、测试生成器、文档抽取器……主代理在需要时自动把活派给它们，每个子代理在独立上下文窗口里干活，只把结论回传。它的价值在于三件事：保护主上下文（海量搜索结果/日志不再污染对话）、收紈权限（只给它干活需要的工具）、并行拆分（多个独立子代理同时跑）。适合想让 Claude Code 从"单线程对话"升级为"小型调度中心"的进阶用户。

前置条件

• Claude Code v2.1.196 及以上（/doctor 可检测同名冲突；本文 frontmatter 字段对应 v2.1.198–v2.1.200 语法）。
• 一个 Git 仓库（要用到 isolation: worktree 字段时必须有）。
• 已会用基本交互命令与计划模式（本系列前几篇已覆盖）。
• 安装并登录好 Claude Code：claude 命令可正常启动会话。

正文

步骤一：先搞清楚"子代理"到底解决了什么

在理解语法前，先建立正确的心智模型。Claude Code 默认只有一条主线对话，所有读文件、跑测试、看日志的结果都堆进同一个上下文窗口，几轮下来窗口就满了。子代理的本质是把"杂活"外包给一个独立窗口：它在那边翻箱倒柜，最后只交回一份摘要。

官方把"并行/委派"能力分成四种形态，子代理只是其一：

本篇聚焦第一种：子代理。其余三种在后续进阶篇展开。

预期结果：你能在心里画出"主代理 → 委派决策 → 子代理（独立上下文）→ 摘要回传"这条链路，这是后面所有配置的目标方向。

常见问题： - 子代理和"在终端开多个 Claude 窗口"有什么区别？ 多窗口是多个独立会话，彼此不通气；子代理是同一会话内由主代理调度的工人，结果直接回灌到当前对话，你能无缝接着用。 - 子代理能不能改我的代码？ 默认能（若 tools 留空则继承全部工具），但你可以把它收紧成只读——这正是它的安全价值。

步骤二：创建第一个子代理文件

子代理就是一个 Markdown 文件 + YAML 头。两种放法：

• 项目级：<repo>/.claude/agents/code-reviewer.md（进版本控制，团队共享）
• 用户级：~/.claude/agents/code-reviewer.md（你所有项目可用）

直接写一个最简单的版本，保存为 .claude/agents/code-reviewer.md：

---
name: code-reviewer
description: 审查代码质量与最佳实践。在代码被写入或修改后主动使用。
tools: Read, Glob, Grep
model: sonnet
---

你是一名资深代码审查员。被调用时，分析指定代码并给出具体、可执行的反馈，
覆盖质量、安全与最佳实践。每条问题要说明：问题在哪、当前写法、改进写法。

• 操作说明：frontmatter 里只有 name 和 description 是必填；tools 留空则继承全部工具，这里显式只给三个只读工具，让它无法动文件。
• 预期结果：保存后，Claude Code 的目录监视器几秒内检测到改动，下次委派自动用新定义，无需重启。
• 常见问题：
• 改了文件没生效？ 监视器只覆盖会话启动时已存在的目录。如果是该 scope 的第一个子代理文件（新建的 agents/ 目录），需要重启一次 Claude Code。
• 名字怎么取？ name 只能用小写字母和连字符（如 code-reviewer）。同一 scope 内重名只加载一个；/doctor（v2.1.196+）会报告同名冲突并指出当前生效的定义。

步骤三：读懂 frontmatter，按需调参

这是子代理最强大的部分。下表覆盖全部字段（对照官方 v2.1.198–v2.1.200 语法）：

三个最常用的调参点：

1. description 是触发器。它越清晰，自动委派越准。别写"代码相关任务"，要写"在代码被修改后主动审查质量、安全与最佳实践"——主代理据此判断要不要派活。
2. model 是省钱开关。把"只读检索"类子代理设 model: haiku，把"需要复杂推理"的设 sonnet/opus，能在质量和成本间精准权衡。也可用环境变量 CLAUDE_CODE_SUBAGENT_MODEL 全局覆盖。
3. isolation: worktree 解决并行写冲突。多个会同时改文件的子代理，各跑各的临时 worktree（默认从你的默认分支拉），互不踩踏，结束后自动清理。

常见问题： - 我想让子代理有 Bash 但不能 rm？ 用 tools: Read, Grep, Glob, Bash 给白名单，再用 disallowedTools 配合权限规则收紧，或在 permissionMode 上做文章。 - 完整模型 ID 怎么写？ 与 --model 同取值，如 claude-opus-4-8、claude-sonnet-5。

步骤四：自动委派 vs 显式调用

子代理有两条触发路径：

• 自动委派：主代理读到你的请求后，对照各子代理的 description，自行决定派给谁。你只管描述任务，剩下交给调度。
• 显式调用：在提示里点名，例如"用 code-reviewer 子代理审查 src/auth.py"。会话里也可用 @ 提及选中某个子代理类型。

显式调用适合你明确知道该走哪个专家；自动委派适合你只描述目标，让 Claude 选人。两者可混用。

操作说明：在会话里输入：

请审查 src/auth.py 这个文件

预期结果：若 code-reviewer 的 description 匹配，Claude 会显示"委派给 code-reviewer 子代理"，子代理在独立上下文里读完文件、产出审查意见，主对话只保留摘要——你不会看到它逐行 grep 的过程。

常见问题： - 没被自动委派？ 多半是 description 写得不够具体，或任务描述里没出现匹配信号。改 description，或直接显式 @code-reviewer。 - 想彻底关掉自动委派？ 在 permissions.deny 里 deny Agent 工具本身即可；只想去掉内置 Explore/Plan，设 CLAUDE_CODE_DISABLE_EXPLORE_PLAN_AGENTS=1。

步骤五：并行编排——把多个专家同时撒出去

真正的提速在这一步。当几个子任务互相独立时，主代理可以并行委派多个子代理，各自在独立上下文里跑，齐了再汇总。

三个编排要点：

• 独立上下文天然并行：每个子代理有自己的窗口，主代理可在一条消息里同时派多个。
• background: true / v2.1.198 默认后台：子代理后台跑时，主代理不被阻塞，任务列表里实时看状态。
• 链条式编排：A 子代理出结论喂给 B 子代理，串成流水线（如"审查 → 据审查意见生成测试"）。

操作说明：在会话里一次性描述三个独立子任务：

对当前这次改动做三件事并行处理：
1) 审查 src/ 下的代码质量
2) 为 src/ 下缺少测试的函数补单元测试
3) 从改动里抽取要写进 CHANGELOG 的条目

预期结果：Claude 同时委派三个子代理（reviewer / test-writer / doc-extractor），任务列表里三个色块并行滚动，完成后主对话只收到三份汇总。

常见问题： - 三个子代理都要改文件，会互相覆盖吗？ 会。解法：给写文件的子代理加 isolation: worktree，各跑各的副本；或让写操作串行、只读操作并行。 - 并行会不会爆 token？ 会线性增长。官方明确：同时跑多个子代理 = token 用量翻倍。对大批量任务，考虑 /batch 技能（自动把一个大改动拆成 5–30 个 worktree 隔离子代理，各自开 PR）或 Dynamic workflows。

实战案例：三专家子代理处理一次功能分支变更

目标：造一个"提 PR 前自检流水线"，由三个专职子代理协同处理一次代码变更。

先建三个文件。.claude/agents/qa-reviewer.md（只读审查，贵模型）：

---
name: qa-reviewer
description: 在代码修改后主动审查质量、安全与潜在 bug。只读，不改文件。
tools: Read, Glob, Grep
model: opus
color: yellow
---

你是资深审查员。聚焦：边界条件、空指针、注入风险、错误处理缺失。
每条问题给：文件:行号、风险描述、修复建议。读不到问题就明确说"无问题"，不要凑数。

.claude/agents/test-writer.md（可写，隔离 worktree 防冲突，中档模型）：

---
name: test-writer
description: 为新增或修改的函数补齐单元测试。需要写文件。
tools: Read, Glob, Grep, Write, Edit, Bash
model: sonnet
isolation: worktree
color: green
---

你是测试工程师。先跑 `npm test` 确认现状，再为无覆盖的函数补 Jest 测试，
每加一个用例就重跑测试确保通过。只返回新增文件清单与最终通过/失败数。

.claude/agents/doc-extractor.md（只读抽取，便宜模型省钱）：

---
name: doc-extractor
description: 从一次代码改动里抽取适合写进 CHANGELOG 的条目。只读。
tools: Bash, Read
model: haiku
color: cyan
---

你从 `git diff` 输出里提炼面向用户的变化条目，按 Keep a Changelog 格式
（Added/Changed/Fixed/Removed）输出，每条一行，去技术黑话。

接着两种用法各演示一次。

用法 A——一句话触发并行编排：

针对当前 feature 分支相对 main 的改动，并行：审查、补测试、抽 CHANGELOG。

主代理识别出三个子任务，同时委派三个子代理：qa-reviewer（opus，只读）跑审查；test-writer（sonnet，worktree 隔离）在副本里补测试并自跑；doc-extractor（haiku，最省）读 diff 出条目。三路并行，主对话只收三份摘要——你的主上下文全程没被任何 grep、test log 污染。

用法 B——临时子代理，不落盘（用 --agents 传 JSON，仅本次会话有效）：

claude --agents '{
  "qa-reviewer": {"description":"代码修改后主动审查，只读。","prompt":"你是审查员，给出文件:行号、风险、修复建议。","tools":["Read","Grep","Glob"],"model":"opus"},
  "doc-extractor":{"description":"从改动抽 CHANGELOG 条目，只读。","prompt":"按 Keep a Changelog 输出。","tools":["Bash","Read"],"model":"haiku"}
}'

适合写脚本/CI 里临时用一组子代理，不污染项目目录。注意 --agents 的 JSON 用 prompt 字段放系统提示（等价于文件版的 Markdown 正文），并支持 disallowedTools、permissionMode、mcpServers、hooks、maxTurns、skills、effort、isolation 等全部字段。

预期结果：一次 PR 自检从"人工切三个窗口、手动复制结果"变成"一句话、三专家并行、主对话只留结论"。审查走 opus 保质量，抽 changelog 走 haiku 保成本，写测试进 worktree 保不冲突——这正是子代理"专、紧、并行"三性的集中体现。

工作流程图

下图展示一次三专家并行编排的数据流（每个子代理独立上下文，只回传摘要）：

flowchart TD
    U[用户：审查+补测试+抽CHANGELOG] --> MAIN[主代理：解析任务]
    MAIN --> DEC{委派决策<br/>匹配 description}
    DEC -->|代码质量| A1[qa-reviewer<br/>opus 只读]
    DEC -->|缺测试| A2[test-writer<br/>sonnet worktree]
    DEC -->|改动提炼| A3[doc-extractor<br/>haiku 只读]
    A1 -.独立上下文.-> C1[审查报告摘要]
    A2 -.独立上下文.-> C2[新测试+通过数]
    A3 -.独立上下文.-> C3[CHANGELOG 条目]
    C1 --> MAIN
    C2 --> MAIN
    C3 --> MAIN
    MAIN --> R[主对话：仅保留三份摘要<br/>上下文未被污染]
    style MAIN fill:#fef3c7
    style R fill:#dcfce7

下面这张是主代理"是否委派"的决策链，帮你理解自动委派与显式调用的分叉：

flowchart LR
    TASK[新任务进入主对话] --> CHK{有匹配的子代理<br/>description 吗}
    CHK -->|有，且用户未指定| AUTO[自动委派<br/>选最匹配者]
    CHK -->|用户已 @点名| EXPL[显式调用<br/>指定子代理]
    CHK -->|无匹配/任务轻| SELF[主代理自己做]
    AUTO --> ISOL{需写文件且可能冲突}
    EXPL --> ISOL
    ISOL -->|是| WT[worktree 隔离<br/>独立副本]
    ISOL -->|否| DIR[直接在当前目录]
    WT --> SUM[子代理独立上下文<br/>干活+回传摘要]
    DIR --> SUM
    style AUTO fill:#dbeafe
    style EXPL fill:#ede9fe
    style SUM fill:#dcfce7

训练营适用性评估

• 适用类型：进阶营（已掌握交互与计划模式的开发者）。不适合纯零基础营——需要先理解上下文窗口、工具权限等概念。
• 预计教学时长：理论讲解 45 分钟 + 动手造三个子代理 60 分钟 + 并行编排演练 45 分钟，合计约 2.5 小时。
• 能力考核点：能否独立写出"触发清晰的 description + 恰当的 tools/model/isolation 组合"，并能解释为何这样省 token、保安全、避写冲突。
• 延伸方向：学完本篇可顺势接 Agent view（claude agents）、Agent teams、Dynamic workflows 与 /batch，向"调度中心"进阶。

延伸阅读

• 官方子代理主文档：https://code.claude.com/docs/en/sub-agents——frontmatter 全字段权威说明
• 官方并行总览：https://code.claude.com/docs/en/agents——四种并行形态对比
• 官方 Agent SDK 子代理：https://code.claude.com/docs/en/agent-sdk/subagents——编程式调用子代理

参考来源

1. Create custom subagents — Claude Code Docs — 子代理 frontmatter 全字段、scope 优先级、内置子代理与委派机制权威说明
2. Run agents in parallel — Claude Code Docs — Subagents / agent view / agent teams / dynamic workflows 四种并行形态对比
3. Subagents in Claude Code: Delegating without losing control — 自动委派、显式调用与并行执行的实战教程
4. Claude Code Subagents: The Complete Guide — ComputingForGeeks — 完整 frontmatter schema 与常用编排模式
5. Claude Code Subagents Collection — GitHub (chusri) — 75 个开箱即用专职子代理，可直接借鉴 frontmatter 写法

[!tip] 51学通信知识星球 星主：爱卫生（微信：gprshome201101）——公众号「51学通信」创办者，19 年通信行业运维与讲师经验，著有《GPRS网络信令实例详解》《EPC原理与实践》《5G核心网原理与实践》三本纸质书（各大电商平台有售）。 星球定位：深耕 5G 核心网、IMS、NFV/AI、云原生等 ICT 领域，主打运维岗位与信令分析。 当前规模：5200 篇主题 / 990 个回答，198 元/年。 加入福利：加入星球后请加爱卫生微信，拉您进知识星球年度陪伴与答疑群——不限量回复您的各种问题，另有群内分享。 AI 加持：51学通信知识星球已作为 skill 接入 WorkBuddy，使用 deepseek-4-flash 在海量星球帖子中精准找贴、找视频、找 FAQ 和案例，做总结、找文档和 PPT 等场景全覆盖。