本教程教你用 Claude Code 的子代理(subagents)机制,打造一支会自动接活的 AI 开发团队。读完你将掌握:子代理文件的写法、description 描述工程(如何让 Claude 在合适的时机自动把任务派给某个代理)、工具沙箱与权限隔离、三种调用方式的区别、并行与链式协作,以及持久记忆。适合已经用过 Claude Code、想从"一个人指挥一个 Claude"升级到"一个协调者调度一支代理团队"的开发者。
/fork 自 v2.1.161 起默认开启)CLAUDE.md、/agents 命令等基础概念很多人的用法是:对着主对话一个 Claude 说到黑。这种"单代理"模式有三个天然瓶颈——上下文会被搜索结果、测试日志、文件内容撑爆;Claude 开始遗忘;性能退化。
子代理解决了这个问题。它是一个跑在独立上下文窗口里的专职 AI,有自己专属的系统提示、专属的工具白名单、专属的模型选择。它干完活,只把结论摘要返回主对话,那些冗长的中间过程留在它自己的上下文里,从不污染你的主会话。
Claude Code 自带三个内置子代理:
| 子代理 | 模型 | 工具 | 用途 |
|---|---|---|---|
| Explore | Haiku(快) | 只读,Write/Edit 被禁 | 代码搜索、文件发现、代码库探索 |
| Plan | 继承主对话 | 只读 | 计划模式里收集上下文 |
| general-purpose | 继承主对话 | 全部工具 | 复杂多步、需探索+修改的任务 |
关键的反直觉点来了:Claude 会根据子代理的 description 字段,自动决定什么时候把活派给它——你不需要每次手动喊"用 XX 代理"。这就是本教程的核心:把 description 写好,让一支代理团队在你的项目里各司其职、自动接活。
子代理本质是带 YAML frontmatter 的 Markdown 文件。有两种创建方式。
/agents 命令(推荐新手)在 Claude Code 交互界面输入:
/agents
切到 Library 标签 → Create new agent → 选 Personal(存到 ~/.claude/agents/,所有项目可用)或 Project(存到 .claude/agents/,随仓库走、团队共享)。选 Generate with Claude,用一句话描述你要的代理,Claude 会帮你生成标识符、描述和系统提示。
这是本教程的主线,因为它最透明、最可控。在项目根目录创建 .claude/agents/code-reviewer.md:
---
name: code-reviewer
description: Reviews code for quality and best practices
tools: Read, Glob, Grep, Bash
model: sonnet
---
You are a code reviewer. When invoked, analyze the code and provide specific,
actionable feedback on quality, security, and best practices.
frontmatter 定义元数据,Markdown 正文成为系统提示。子代理只会收到这个系统提示加基础环境信息(工作目录等),而不是完整的 Claude Code 系统提示——这是它上下文干净的根本原因。
预期结果:重启会话后(磁盘上直接改文件需要重启,/agents 界面创建则即时生效),在 /agents 的 Library 里能看到 code-reviewer。
常见问题:
- 文件改了不生效? 直接编辑磁盘文件需重启会话;用 /agents 改则即时生效。
- 名字报重复? name 必须全树唯一。v2.1.196 起,/doctor 会报告同作用域重名。
这是本教程的核心章节。Claude 是否把任务自动派给某个子代理,主要看三样东西:你这次请求里的任务描述、子代理的 description 字段、当前上下文。
写法一(平庸,几乎不会自动触发):
description: Reviews code
写法二(合格):
description: Expert code reviewer. Reviews code for quality and security.
写法三(精准,会主动接活):
description: Expert code review specialist. Proactively reviews code for quality,
security, and maintainability. Use immediately after writing or modifying code.
差别在第几处?触发词和触发时机。官方明确建议:为了鼓励主动委派,在 description 里加入 "use proactively"、"use immediately after ..." 这类短语。Claude 读到这些词,才会在合适的场景主动派活,而不是等你点名。
当你有多个 description 重叠的代理时,Claude 会自己仲裁。但你可以用作用域优先级显式控制。Claude Code 扫描子代理有 5 级优先级(高到低):
| 位置 | 作用域 | 优先级 |
|---|---|---|
| Managed settings | 组织级 | 1(最高) |
--agents CLI 参数 |
当前会话 | 2 |
.claude/agents/ |
当前项目 | 3 |
~/.claude/agents/ |
你的所有项目 | 4 |
插件的 agents/ |
插件启用处 | 5(最低) |
同名时,高优先级覆盖低优先级。所以团队规范代理放 .claude/agents/(进版本库),个人偏好放 ~/.claude/agents/,组织强制规则走 managed settings。
常见问题: - 代理从不被自动触发? 八成是 description 太笼统、缺触发词。补上 "use proactively" 和明确场景。 - 代理被误触发(抢了别的代理的活)? 收窄职责描述,加边界;或调整作用域,用更高优先级的精确定义覆盖。
子代理默认继承主会话的所有内部工具和 MCP 工具。但生产环境里,你绝不希望一个"只读审查"代理能改文件。有四道闸门。
tools(只给必要的)---
name: safe-researcher
description: Research agent with restricted capabilities
tools: Read, Grep, Glob, Bash
---
这个代理只能读、搜、跑命令,不能 Edit/Write。
disallowedTools(继承全部,只禁某几个)---
name: no-writes
description: Inherits every tool except file writes
disallowedTools: Write, Edit
---
两者都设时,先应用 disallowedTools,再用 tools 在剩余池里收口。还能按 MCP 服务器批量收:disallowedTools: mcp__github 会干掉 github MCP 服务器的全部工具。
注意有些工具子代理永远拿不到,即使写进 tools:AskUserQuestion、EnterPlanMode、ExitPlanMode(除非 permissionMode: plan)、ScheduleWakeup、WaitForMcpServers——它们依赖主会话的 UI 或会话状态。
permissionMode 控制子代理怎么处理权限提示:
| 模式 | 行为 |
|---|---|
default |
标准提示 |
acceptEdits |
自动接受工作目录内的文件编辑 |
auto |
后台分类器审查命令和受保护目录写入 |
dontAsk |
自动拒绝(显式放行的工具仍可用) |
bypassPermissions |
跳过所有提示(慎用!) |
plan |
计划模式,只读探索 |
注意:父会话若是 bypassPermissions 或 acceptEdits,优先级更高,子代理无法覆盖。
当你需要"允许某个工具的某些操作、禁掉另一些"时,用 PreToolUse hook。下面这个代理能跑 Bash,但只允许只读 SQL:
---
name: db-reader
description: Execute read-only database queries. Use when analyzing data or reports.
tools: Bash
hooks:
PreToolUse:
- matcher: "Bash"
hooks:
- type: command
command: "./scripts/validate-readonly-query.sh"
---
配套校验脚本(读取 stdin 的 JSON,发现写操作就 exit 2 阻断):
#!/bin/bash
# ./scripts/validate-readonly-query.sh
INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')
if echo "$COMMAND" | grep -iE '\b(INSERT|UPDATE|DELETE|DROP|CREATE|ALTER|TRUNCATE)\b' > /dev/null; then
echo "Blocked: Only SELECT queries are allowed" >&2
exit 2 # exit code 2 = 阻断并把 stderr 反馈给 Claude
fi
exit 0
记住:chmod +x 让脚本可执行。这套"白名单+黑名单+模式+hook"四件套,就是你造最小权限沙箱的全部武器。
自动委派是默认行为,但它"不强求"。当你想更确定时,有三档 escalation。
Use the code-reviewer subagent to look at my recent changes
没有特殊语法,在 prompt 里点名即可。Claude 通常会委派,但保留判断权。
@"code-reviewer (agent)" look at the auth changes
输入 @ 从候选里挑,或在 v2.1.196+ 手敲 @agent-code-reviewer。保证那个代理一定为这个任务跑一次,选择权不交给 Claude。
--agent(整个会话级)claude --agent code-reviewer
整个会话的主线程直接变成那个子代理:用它的系统提示(替换默认 Claude Code 系统提示)、它的工具限制、它的模型。想给项目设默认代理,写进 .claude/settings.json:
{ "agent": "code-reviewer" }
CLI 参数会覆盖该设置。这是把一个项目彻底变成"专职审查工作台"的捷径。
Research the authentication, database, and API modules in parallel using separate subagents
Claude 为每个模块各派一个子代理,同时探索,各自独立上下文,最后由 Claude 综合结论。当研究路径互不依赖时效果最好。
Use the code-reviewer subagent to find performance issues,
then use the optimizer subagent to fix them
前一个的输出作为后一个的输入。每个代理完成后把结果交回 Claude,Claude 再把相关上下文传给下一个。
一个子代理还能派自己的子代理。典型场景:一个审查代理对每条发现各派一个验证代理,中间产物从不进入你的主对话,只有顶层代理的摘要返回给你。
约束:深度上限固定为 5 层——depth 5 的代理拿不到 Agent 工具,无法再派。要阻止某个代理派生,从它的 tools 里去掉 Agent,或加进 disallowedTools。
想限定某个作为主线程的代理(claude --agent)能派哪些子代理,用 Agent(type1, type2) 白名单语法:
---
name: coordinator
description: Coordinates work across specialized agents
tools: Agent(worker, researcher), Read, Bash
---
Ctrl+B 可把运行中的任务转后台。v2.1.186 起,后台子代理遇到需权限的工具调用时,提示会浮到主会话、标明是哪个代理在问。设 CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1 可彻底关闭后台功能。
给代理开 memory,它就有了跨会话的知识库,能积累代码库模式、调试经验、架构决策。
---
name: code-reviewer
description: Reviews code for quality and best practices
memory: project
---
You are a code reviewer. As you review code, update your agent memory with
patterns, conventions, and recurring issues you discover.
三个作用域:
| 作用域 | 位置 | 适用 |
|---|---|---|
user |
~/.claude/agent-memory/<name>/ |
跨所有项目积累 |
project |
.claude/agent-memory/<name>/ |
项目专属、可随版本库共享(推荐默认) |
local |
.claude/agent-memory-local/<name>/ |
项目专属但不入库 |
开启后,系统提示会自动注入记忆目录里 MEMORY.md 的前 200 行(或 25KB),且 Read/Write/Edit 会自动启用以便代理管理记忆文件。用法:让它开工前"查记忆"、收工后"存经验",日积月累就是机构知识库。
把前面所有招式串起来。目标:为一个真实代码库搭一支 3 人代理团队,自动守卫代码质量。
.claude/agents/code-reviewer.md(只读审查,写完代码自动接手):
---
name: code-reviewer
description: Expert code review specialist. Proactively reviews code for quality,
security, and maintainability. Use immediately after writing or modifying code.
tools: Read, Grep, Glob, Bash
model: inherit
memory: project
color: green
---
You are a senior code reviewer ensuring high standards. When invoked:
1. Run git diff to see recent changes
2. Focus on modified files
3. Begin review immediately
Review checklist: 命名清晰、无重复代码、错误处理到位、无泄露密钥、输入校验、测试覆盖。
按优先级输出:Critical(必修) / Warning(应修) / Suggestion(可选)。
每条问题给出具体修复示例。Review 后把发现的模式存入 agent memory。
.claude/agents/optimizer.md(可编辑,性能问题自动接手修复):
---
name: optimizer
description: Performance optimization specialist. Use proactively when code review
or profiling surfaces performance issues. Diagnoses and applies minimal fixes.
tools: Read, Edit, Bash, Grep, Glob
model: sonnet
color: orange
---
You are an expert in performance. When invoked:
1. 复现并量化性能问题(benchmark/profiler)
2. 定位瓶颈
3. 实施最小修复
4. 用 benchmark 验证改善
每次给出:根因、证据、改动、前后对比数据。
.claude/agents/test-guard.md(隔离测试噪音,后台友好):
---
name: test-guard
description: Test runner that executes the suite and reports only failures with
error messages. Use proactively after code changes to keep the build green.
tools: Bash, Read
model: haiku
background: true
color: blue
---
You run the project's test suite. When invoked:
1. 执行测试命令
2. 只报告失败的测试及其错误信息
3. 不把通过的测试细节带回来
保持主会话上下文干净。
写完一段代码后,直接说:
我刚改完了 auth 模块
你不需要点名 code-reviewer。因为它的 description 里有 "Use immediately after writing or modifying code",Claude 会自动把审查派给它。改完跑测试时,test-guard 因为 background: true 在后台跑,主会话不被阻塞。
先用 code-reviewer 审查最近改动,把它发现的性能问题交给 optimizer 修复;
同时用 test-guard 跑一遍测试,只汇报失败项。
这条指令触发:code-reviewer(前台)→ optimizer(链式接手)并行 test-guard(后台)。三个代理各用各的模型(审查继承、优化用 sonnet、测试用便宜的 haiku)和工具集,互不污染主上下文。
想整场会话只做代码审查:
claude --agent code-reviewer
此后整个会话就是审查专家,系统提示、工具、模型全换成它的。
预期效果:主会话上下文长期保持清爽;代码质量、性能、测试三道防线各司其职;代理还能靠 memory: project 把审查经验沉淀进版本库,团队共享。
flowchart TD
U[用户发起任务] --> MAIN[主会话 / Claude 协调者]
MAIN --> DEC{读取子代理 description<br/>决定委派}
DEC -->|自动| SA1[code-reviewer<br/>只读·审查]
DEC -->|自动| SA2[optimizer<br/>可编辑·修复]
DEC -->|后台| SA3[test-guard<br/>跑测试·只报失败]
SA1 -->|发现性能问题| SA2
SA1 -.链式.-> SA2
SA2 --> NEST[嵌套子代理<br/>逐项验证修复]
SA1 --> MEM[(project memory<br/>积累审查经验)]
SA2 --> MEM
SA1 -->|仅返回摘要| MAIN
SA2 -->|仅返回摘要| MAIN
SA3 -->|仅返回失败项| MAIN
MAIN --> R[综合结论交付用户]
classDef agent fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px;
classDef main fill:#fff3e0,stroke:#e65100,stroke-width:2px;
classDef mem fill:#e3f2fd,stroke:#1565c0,stroke-width:2px;
class SA1,SA2,SA3,NEST agent;
class MAIN,R main;
class MEM mem;
主会话只做协调与综合,所有重活(读 diff、改代码、跑测试)都在隔离的子代理上下文里发生,只有摘要回流,这是上下文经济学的核心。
| 问题 | 原因 | 解决 |
|---|---|---|
| 代理从不自动触发 | description 太笼统、缺触发词 | 加 "use proactively" + 明确场景 |
| 磁盘改文件不生效 | 需重启会话 | 用 /agents 改,即时生效;或重启 |
| 同名代理冲突 | 多作用域重名 | /doctor 查重;用高优先级作用域覆盖 |
| 后台代理权限总被拒 | v2.1.186 前后台自动拒提示 | 升级版本;提示会浮到主会话 |
| Explore/Plan 不能续跑 | 一次性代理,无 agent ID | 改用 general-purpose 或自定义代理 |
| 想恢复之前的子代理 | 新调用是新实例 | 用 SendMessage 按 agent ID 续跑 |
| 嵌套到第 5 层派不动 | 深度硬上限 | 拆分任务,减少嵌套层数 |
恢复子代理的细节:每次调用是全新实例。要续跑,直接对 Claude 说 "continue that code review",它用 SendMessage 按代理 ID 续跑并保留完整历史。转录文件在 ~/.claude/projects/{project}/{sessionId}/subagents/agent-{agentId}.jsonl。
code.claude.com/docs/en/sub-agents(frontmatter 字段、作用域、示例最权威来源)code.claude.com/docs/en/agents(子代理 vs agent view vs agent teams vs dynamic workflows)code.claude.com/docs/en/agent-sdk/overview(编程式调度子代理,接 CI/CD)code.claude.com/docs/en/context-window(直观感受子代理如何省上下文)code.claude.com/docs/en/permission-modes(六种 permissionMode 的完整语义)CLAUDE.md)。isolation: worktree 让代理在隔离副本里改代码;开启 memory: project 让团队共享代理经验。[!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 等场景全覆盖。