概述

当单一 Claude 会话同时承担架构设计、写测试、查安全、写文档时，上下文很快会被搜索结果、日志和文件内容淹没，主线任务被迫中断。本教程教你用 Claude Code 的子代理（Subagents）机制，在 .claude/agents/ 下定义一组各司其职的"专家"，让主会话像项目经理一样把子任务委派出去，各自在独立上下文窗口里工作，只把结论交回来。学完你将掌握：子代理的创建、frontmatter 全字段配置、工具围栏、模型分级、并行委派，并能落地一个由架构师、测试、安全三位专家组成的"代码审查团队"。适合已跑通 Claude Code 基础用法、想从单兵作战升级到团队协作的开发者。

前置条件

• 已安装 Claude Code（v2.1.x 以上，本文以 2026 年的 claude-opus-4-8 / claude-sonnet-4-6 / claude-haiku-4-5 为模型示例）
• 有一个可交互的终端会话（子代理主要在交互会话中自动委派）
• 已有一个待审查的真实代码仓库（git 仓库最佳，便于使用 worktree 隔离）
• 对 YAML frontmatter 有基本认识

一、为什么单一 Agent 不够：子代理解决的三类痛点

主会话（main thread）是你和 Claude 对话的那个上下文窗口。它有一个硬约束：容量有限。一旦你让它在主线里跑 grep 全仓库、读十几个文件、跑测试看日志，这些中间产物就会挤占宝贵的上下文额度，把真正要解决的问题"挤出"记忆。

子代理正是为切断这种污染而设计。它有三个本质特征：

1. 独立上下文窗口：子代理在自己独立的上下文里运行，搜索结果、日志、文件内容都留在它自己的窗口里，主会话只拿到它返回的摘要。
2. 受限工具集：你可以规定某个子代理只能读不能写，或只能调用特定 MCP 服务器。
3. 专属系统提示：子代理只接收你写的系统提示加上基本环境信息（工作目录等），不继承主会话的完整系统提示，因此可以高度专业化。

flowchart LR
    User([你]) -->|对话| Main[主会话<br/>项目经理]
    Main -->|委派研究| Exp[Explore 子代理<br/>Haiku·只读]
    Main -->|委派审查| Arch[架构师 子代理<br/>Opus]
    Main -->|委派测试| Test[测试 子代理<br/>Sonnet]
    Main -->|委派安全| Sec[安全 子代理<br/>Haiku]
    Exp -.只返回摘要.-> Main
    Arch -.只返回结论.-> Main
    Test -.只返回报告.-> Main
    Sec -.只返回清单.-> Main
    style Main fill:#ffe9b3,stroke:#b8860b,stroke-width:2px

Claude Code 内置了几个开箱即用的子代理，理解它们是写好自定义子代理的前提：

注意一个关键设计：Explore 和 Plan 会跳过你的 CLAUDE.md 和主会话的 git 状态，以保证研究既快又便宜；而其他自定义子代理都会加载这两者。这个差异在后面调优成本时很重要。

二、创建第一个子代理：两种姿势

姿势 A：用 /agents 命令（推荐新手）

在交互会话里输入：

/agents

切到 Library 标签 → Create new agent。你可以选 Generate with Claude，用自然语言描述需求，例如：

A code improvement agent that scans files and suggests improvements for readability, performance, and best practices.

Claude 会自动生成 name、description 和系统提示词。接着依次选择：工具（只读审查就只勾 Read-only tools）、模型（选 Sonnet 平衡能力与速度）、显示颜色、记忆范围（选 User scope 会让它在 ~/.claude/agent-memory/ 跨会话积累经验）。保存后立即生效，无需重启。

姿势 B：手写 Markdown 文件（推荐自动化、版本控制）

子代理就是一个带 YAML frontmatter 的 .md 文件。最简形态：

---
name: code-reviewer
description: Reviews code for quality and best practices
tools: Read, Glob, Grep
model: sonnet
---

You are a code reviewer. When invoked, analyze the code and provide
specific, actionable feedback on quality, security, and best practices.

文件放哪决定了它的作用域，优先级从高到低：

实践建议：与具体代码库绑定的专家（如"本项目的领域规则审查员"）放 .claude/agents/ 并提交进 git，让全团队共享；与个人习惯绑定的（如"我的 commit message 润色员"）放 ~/.claude/agents/。

一个重要细节：子代理在会话启动时加载。如果你直接在磁盘上新建/编辑了文件，需要重启会话才能识别；而通过 /agents 界面创建的则会立即生效。

还有一个命令行姿势，适合自动化脚本里临时定义、不留盘的子代理：

claude --agents '{
  "code-reviewer": {
    "description": "Expert code reviewer. Use proactively after code changes.",
    "prompt": "You are a senior code reviewer. Focus on quality, security, and best practices.",
    "tools": ["Read", "Grep", "Glob", "Bash"],
    "model": "sonnet"
  },
  "debugger": {
    "description": "Debugging specialist for errors and test failures.",
    "prompt": "You are an expert debugger. Analyze errors, identify root causes, and provide fixes."
  }
}'

注意 JSON 形态下用 prompt（对应文件形态的 Markdown 正文）承载系统提示词。

三、frontmatter 全字段解析：把专家调到最佳状态

这是本教程最硬核的一节。下表是官方支持的完整字段，只有 name 和 description 必填：

三个最容易被忽视、却极有价值的字段：

description 是自动委派的灵魂。 Claude 完全靠它判断"这个任务该不该交给这个子代理"。写得越具体、越能触发，越不容易误派。对比：

# ❌ 太模糊，容易和内置 Explore 抢活
description: Searches the codebase

# ✅ 具体、有边界，触发精准
description: Audits TypeScript code for missing error handling around async/await and Promise chains. Use after backend route handlers or API client code changes.

isolation: worktree 让并行专家不互相踩脚。 默认情况下子代理共享主会话的工作目录，多个专家同时改文件会冲突。设为 worktree 后，每个子代理拿到一份临时仓库副本（默认从你的 default branch 而非父会话 HEAD 分支），干完活若没改动会自动清理。

memory 让专家越用越聪明。 设为 project 后，子代理会在 .claude/agent-memory/ 跨会话积累洞见——比如"这个仓库习惯用 Zod 做校验"、"用户偏好函数式写法"。

四、工具围栏：给专家划定安全作业半径

工具控制有两条独立轴线，可以单独或组合使用。

白名单（tools）——只给最少必要工具：

---
name: safe-researcher
description: Research agent with restricted capabilities
tools: Read, Grep, Glob, Bash
---

这个研究员能读、能搜、能跑命令，但不能写、不能改。

黑名单（disallowedTools）——继承全部工具，只摘掉危险的：

---
name: no-writes
description: Inherits every tool except file writes
disallowedTools: Write, Edit
---

两条都设时，先按 disallowedTools 摘除，再在剩余集合里按 tools 取交集；同时出现在两边的一律删除。

MCP 工具也能按服务器粒度控制，写法是 mcp__<server> 或 mcp__<server>__*：

---
name: local-only
description: Inherits every tool except those from the github MCP server
disallowedTools: mcp__github
---

黑名单里写 mcp__* 可以一次性摘掉所有 MCP 工具。

还有一类需要特别留意——有些工具永远不可用于子代理，即使你写进 tools 也没用：AskUserQuestion、EnterPlanMode、ScheduleWakeup、WaitForMcpServers，以及（除非子代理处于 plan 模式的）ExitPlanMode。原因都是这些工具依赖主会话的 UI 或会话状态。

最后一个高级技巧：当一个 agent 通过 claude --agent 当作主线运行时，可以用 Agent(worker, researcher) 这种语法限制它只能再生成哪几种子代理，实现"协调员-工人"的层级编排。

五、模型分级：能力与成本的精密天平

模型选择是子代理区别于普通提示词工程的最大杠杆——你终于可以按任务难度给不同专家配不同档位的脑子。模型解析顺序为：

1. 环境变量 CLAUDE_CODE_SUBAGENT_MODEL（若设置，全局覆盖）
2. 单次调用的 model 参数
3. 子代理定义里的 model 字段
4. 主会话模型

实务上的黄金分配：

一条经验法则：让 80% 的"杂活"跑在 Haiku 上，把 Opus 留给真正需要深思的 20%。 一个用 Haiku 扫全库找未捕获 Promise 的子代理，成本可能只有 Opus 版的十几分之一，而结果几乎一样好。

六、并行委派：让专家团队同时开工

子代理不是串行工具，Claude 会在一条消息里同时委派多个独立任务，让它们并发执行。这种"扇出（fan-out）"是把复杂工作切成可并行块的关键。

显式调用子代理有三种方式：

1. 自然语言委派：Use the code-reviewer agent to review src/api/
2. @-mention：在消息里 @code-reviewer 直接点名
3. 作为主线启动：claude --agent code-reviewer，此时它成为主会话，可配合 initialPrompt 自动执行首条指令

并行委派的典型场景：当你下达"帮我全面体检这个 PR"时，Claude 会判断出架构审查、测试覆盖、安全扫描三者相互独立，于是在一条消息里同时派出三个子代理：

sequenceDiagram
    participant U as 你
    participant M as 主会话(协调员)
    participant A as 架构师 Opus
    participant T as 测试 Sonnet
    participant S as 安全 Haiku
    U->>M: 全面体检 PR #42
    M->>A: 审查模块边界与耦合
    M->>T: 评估测试覆盖率
    M->>S: 扫描注入与密钥泄漏
    par 三个专家并发工作（各自独立上下文/worktree）
        A-->>M: 架构报告
        T-->>M: 覆盖率缺口清单
        S-->>M: 安全风险清单
    end
    M->>U: 汇总三方结论 + 优先级建议

主会话收到的只是三条摘要，而不是三份完整的代码搜索结果——这就是上下文不被污染的全部魔法。

七、实战案例：落地一个"代码审查三专家团队"

下面我们把前面所有概念串起来，构建一个可直接用的项目级团队。在仓库根目录创建三个文件。

文件 1：.claude/agents/arch-reviewer.md —— 架构师，最强模型 + 写权限以便能给出可直接应用的补丁：

---
name: arch-reviewer
description: Reviews module boundaries, coupling, and design patterns in TypeScript/Go backends. Use after changes that touch multiple files or service layers.
model: claude-opus-4-8
tools: Read, Grep, Glob, Bash
effort: high
color: purple
memory: project
---

You are a principal software architect. When invoked:
1. Map the affected modules and their dependencies.
2. Flag tight coupling, circular dependencies, and leaky abstractions.
3. Propose the minimal refactor that preserves behavior.
Return a prioritized list: each item has severity, location (file:line),
problem, and a concrete fix. Do not edit files unless explicitly asked.

文件 2：.claude/agents/test-auditor.md —— 测试审计员，中档模型，worktree 隔离以便它能安全地实际跑测试：

---
name: test-auditor
description: Evaluates test coverage and quality for changed code. Runs the suite and reports gaps.
model: sonnet
tools: Read, Grep, Glob, Bash
disallowedTools: Edit
isolation: worktree
maxTurns: 25
color: green
---

You are a test engineer. When invoked:
1. Identify changed functions/classes from git diff.
2. Run the test suite (`npm test` or equivalent).
3. List untested branches and brittle tests.
Return a coverage gap report. Never commit changes.

文件 3：.claude/agents/security-scanner.md —— 安全扫描员，便宜模型扫全库 + 专属安全 MCP：

---
name: security-scanner
description: Scans for injection, hardcoded secrets, and unsafe deserialization across the repo.
model: haiku
tools: Read, Grep, Glob
mcpServers:
  - github
color: red
---

You are an application security analyst. Scan for:
- SQL/command injection and unsafe eval
- Hardcoded secrets and API keys
- Path traversal and unsafe deserialization
Return a risk list with file:line and remediation. Read-only.

三个文件就位后，重启会话让 Claude Code 加载它们。然后在主会话里下达：

我刚合并了 feat/payment 的改动，请用 arch-reviewer、test-auditor、security-scanner
三个专家并行体检，最后给我一份按严重程度排序的整改清单。

预期结果：Claude 会判断这三项审查相互独立，于是一条消息里同时派出三位专家。架构师用 Opus 在共享目录做推理；测试审计员在独立 worktree 里实际 npm test 拿到真实覆盖率；安全扫描员用 Haiku 快速扫全库。约一两分钟后，你收到一份汇总清单，主会话上下文依然清爽。

把 .claude/agents/ 提交进 git，全团队 git pull 后就能复用同一套专家，这是从"个人工具"升级到"团队资产"的关键一步。

八、常见问题与排坑

子代理没被自动触发？ 九成是 description 写得太宽泛，和内置 Explore 撞车。把它改得足够具体——写明触发条件、限定语言/场景。

多个专家改同一文件冲突？ 给会改文件的子代理加 isolation: worktree，各自在临时副本上工作。

改动文件后子代理没更新？ 直接编辑磁盘文件需要重启会话才生效；用 /agents 界面改则即时生效。

插件子代理的 hooks 不生效？ 出于安全，来自插件的子代理会忽略 hooks、mcpServers、permissionMode 三个字段。需要时把文件复制到 .claude/agents/ 下。

想完全屏蔽某个内置子代理？ 在 permissions.deny 里加 Agent（屏蔽所有）或具体类型，或设置环境变量 CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS=1。

子代理成本失控？ 检查是否该用 Haiku 的搜索型任务误配了 Opus；用 maxTurns 给长任务兜底；用 disallowedTools 防止意外的 MCP 调用。

九、延伸阅读

• 官方《Create custom subagents》—— frontmatter 字段与权限的权威出处
• 官方《Run agents in parallel》—— subagent / agent view / agent teams 三种并行模式的对比
• 官方《Orchestrate teams of Claude Code sessions》—— Agent Teams，子代理之上的多会话协作（实验特性，需 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS）
• 官方《Context window visualization》—— 直观理解子代理如何省上下文

下一步进阶方向：把本教程的三专家团队与 hooks 结合，让 PostToolUse 在每次提交后自动触发这套审查流水线；或进一步探索 Agent Teams，让多个会话之间通过共享任务列表真正"对话"协作。

十、训练营适用性评估

• 适合的训练营类型：进阶/高级班。学员需已掌握 Claude Code 基础交互、理解上下文窗口概念。
• 不适合：零基础入门班——子代理的心智模型（独立上下文、委派、并行）对新手偏重。
• 预计教学时长：理论讲解 + 跟做三专家案例，约 2.5～3 小时；若要求学员自行设计一个领域专属子代理（如 SQL 审计员、API 契约校验员）并演示，再加 1.5 小时实操。
• 核心教学点：① 独立上下文的隔离价值 ② description 驱动自动委派 ③ 模型分级做成本控制 ④ worktree 并行隔离。建议用"改造前后上下文占用对比"作为最直观的 A/B 演示。

参考来源

1. Create custom subagents — Claude Code Docs — 官方子代理权威文档，frontmatter 全字段表、scope 优先级、工具围栏的出处
2. Run agents in parallel — Claude Code Docs — subagent / agent view / agent teams 三种并行机制对比
3. Orchestrate teams of Claude Code sessions — Claude Code Docs — Agent Teams 多会话协作编排（实验特性）
4. Claude Code Subagents Guide 2026: Parallel Agents — 子代理隔离上下文模型与并行实践详解
5. Claude Code Subagents and Multi-Agent Orchestration Guide — 多代理编排与委派模式的工程化经验

[!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 等场景全覆盖。