目录
Subagent 是 Claude Code 中最强大却最被低估的特性。 本文从原理到实战，带你掌握这个让 AI 实现任务分治、并行加速、上下文隔离的核心机制。
Subagent 的本质是把 “一个 AI 做所有事” 变成 “专业团队分工协作”。 合理设计 Subagent 体系，是构建生产级 AI Agent 系统的关键。
什么是 Subagent？一个形象的比喻
想象你是一位项目总监，手头有一个复杂任务：对整个工程做全面 Code Review。 如果你亲自一行行读代码，同时要分析安全漏洞、检查测试覆盖率、审查性能问题…… 你的脑子很快就会混乱，而且做完一项再做另一项，效率极低。
聪明的做法是：召集三位专家分头行动——安全专家、测试专家、性能专家各自独立工作， 最后向你汇报结论。这就是 Subagent 的核心思想。
📖 官方定义Subagents（子智能体）是主 Agent 可以生成的独立 Agent 实例，用于处理专注的子任务。 每个 Subagent 运行在自己独立的 Context Window 中，拥有自定义的 System Prompt、特定的工具访问权限和独立的执行权限。
为什么需要 Subagent？核心问题
💡 一句话总结Subagent 解决的核心问题是：上下文管理（避免污染主对话）、 并行加速（多任务同步执行）、专业分工（专属指令提升质量）。
在理解 Subagent 的价值之前，我们先看看没有 Subagent 时会遇到什么问题：
问题一：Context Window 污染
Claude 的 Context Window 是有限的。当你让主 Agent 去探索一个大型代码库时， 它读取的数十个文件、搜索结果、中间过程会塞满上下文，导致后续任务质量下降， 甚至触发 Context Limit 强制压缩。
问题二：串行执行效率低
复杂任务往往包含多个独立的子任务。如果全部串行执行，时间是各任务之和； 而并行执行可以让时间接近最慢的那个任务，效率提升数倍。
问题三：角色混乱、专注度不足
让一个 Agent 同时扮演安全专家、性能优化师、文档编写者…… 它的注意力会被分散，而专门设计的 Subagent 可以通过精心编写的 System Prompt 达到更高质量的专业化输出。
如何定义一个 Subagent（两种方式）
Claude Code 提供了两种定义 Subagent 的方式，各有适用场景：
| 方式 | 适用场景 | 优先级 | 持久化 |
|---|---|---|---|
| 📁 文件系统方式（Markdown 文件） | 团队共享、跨项目复用、Claude Code 交互式使用 | 低（可被覆盖） | ✓ 持久 |
| 💻 编程方式（agents 参数） | SDK 开发、CI/CD、动态生成、自动化流水线 | 高（优先级最高） | ✗ 仅当次运行 |
方式一：文件系统方式（推荐新手）
在 .claude/agents/ 目录下创建 Markdown 文件，文件格式为带 YAML frontmatter 的 Markdown。
.claude/agents/security-reviewer.md
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 |
--- name: security-reviewer description: 安全代码审查专家。当需要检查安全漏洞、认证问题、 SQL 注入、XSS 等安全风险时自动调用。 tools: Read, Grep, Glob model: sonnet --- 你是一位资深的代码安全专家，专注于识别和分析安全漏洞。 ## 审查重点 - SQL 注入、XSS、CSRF 漏洞 - 认证与授权逻辑缺陷 - 敏感数据硬编码（API Key、密码等） - 不安全的加密实现 - 输入验证缺失 ## 输出格式 对每个发现的问题，请提供： 1. 漏洞类型和严重等级（Critical/High/Medium/Low） 2. 代码位置（文件名 + 行号） 3. 具体的修复建议 保持简洁，只返回关键发现，不要包含搜索过程。 |
⚠️ 关键字段说明description 是最重要的字段——Claude 依据此字段决定何时自动调用这个 Subagent，写得越清晰，调用越准确。 tools 限制可用工具（省略则继承父 Agent 所有工具）。 model 可指定不同模型（如用 Haiku 降低成本）。
方式二：编程方式（SDK 开发）
在代码中通过 agents 参数直接定义，适合构建自动化 Pipeline：
review-pipeline.ts
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 |
import { query } from '@anthropic-ai/claude-agent-sdk'; const result = query({ prompt: "对 src/auth 模块做全面代码审查", options: { // ⚠️ 必须把 Task 加入 allowedTools，否则 Subagent 永远不会被调用 allowedTools: ["Read", "Glob", "Grep", "Task"], agents: { // Subagent 名称作为 key 'security-reviewer': { description: '安全专家，负责识别注入攻击、认证缺陷、权限漏洞', prompt: `你是资深安全工程师。重点检查： - SQL 注入 / XSS / CSRF - 认证绕过和权限提升 - 密钥硬编码 每个问题给出严重等级和修复方案。`, tools: ['Read', 'Grep', 'Glob'], model: 'sonnet' // 可指定不同模型 }, 'test-coverage': { description: '测试覆盖率分析师，检查未测试的关键路径', prompt: `你是测试专家。分析测试文件，找出： - 缺少单元测试的核心函数 - 边界条件未覆盖的场景 - 集成测试的空白区域 输出：未测试代码占比 + 优先补测清单。`, tools: ['Read', 'Glob', 'Bash'], model: 'haiku' // 简单任务用廉价模型 } } } }); // 监听 Subagent 调用事件 for await (const message of result) { if (message.type === 'tool_use' && message.name === 'Agent') { console.log(`🚀 启动 Subagent: ${message.input.agent_name}`); } } |
存储位置与优先级
| 存储位置 | 作用范围 | 优先级 |
|---|---|---|
.claude/agents/ |
当前项目（可提交到 Git 团队共享） | ★★★ 最高 |
~/.claude/agents/ |
当前用户所有项目 | ★★ 中 |
SDK agents 参数 |
当次运行（可动态生成） | ★★★ 最高（覆盖同名文件） |
典型应用场景全景
Subagent 适合哪些场景？核心判断标准只有两个：
- 任务是否上下文密集（会产生大量中间数据）？
- 或者任务是否可以并行分解（子任务相互独立）？
场景一：代码审查流水线
同时启动安全、性能、可维护性三个专家 Subagent，并行分析后汇总报告。
场景二：文档调研与总结
让专属 Subagent 去爬取大量文档页面，在子上下文中消化信息，只返回精炼摘要给主对话，避免文档噪音污染你的 Context。
场景三：多语言本地化
为每种目标语言创建一个翻译 Subagent，10 种语言同步翻译，时间从串行的 10x 缩短到接近 1x。
场景四：大型重构任务
主 Agent 制定重构计划，派发不同模块给不同 Subagent 独立执行。各模块互不干扰，完成后合并。
场景五：CI/CD 自动化
在 PR 流程中自动触发代码审查 Subagent、测试运行 Subagent、文档更新 Subagent，形成完整的自动化质检流水线。
| 场景 | 核心收益 | 推荐工具权限 |
|---|---|---|
| 代码审查 | 并行 + 专业化 | Read, Grep, Glob（只读） |
| 文档调研 | 上下文隔离 | Read, WebFetch, Grep |
| 多语言翻译 | 并行加速 | Read, Write |
| 大型重构 | 模块隔离 | Read, Write, Edit, Bash |
| CI/CD 审查 | 自动化 + 专业化 | Read, Bash, Glob |
完整 Demo：代码库全面审查系统
下面是一个完整的、可直接运行的 Demo，展示如何用三个并行 Subagent 对代码库进行安全审查、测试覆盖分析和性能检查。
项目结构
|
1 2 3 4 5 6 7 8 9 10 11 |
my-project/ ├── .claude/ │ └── agents/ │ ├── security-reviewer.md # 安全审查专家 │ ├── test-analyzer.md # 测试覆盖分析师 │ └── perf-auditor.md # 性能审计员 ├── src/ │ └── auth/ │ ├── login.ts │ └── token.ts └── review.ts # 主入口（SDK 方式） |
Step 1：定义三个 Subagent 文件
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 |
--- name: security-reviewer description: 代码安全审查。检测 SQL 注入、XSS、认证漏洞、 硬编码密钥等安全问题时调用。 tools: Read, Grep, Glob model: sonnet --- 你是 OWASP Top 10 安全专家。只关注安全问题，不做其他评价。 审查完成后，以如下 JSON 格式输出，不要有任何额外文字： { "findings": [ { "severity": "Critical|High|Medium|Low", "type": "漏洞类型", "file": "文件路径", "line": 行号, "description": "问题描述", "fix": "修复建议" } ], "summary": "一句话总结" } |
.claude/agents/test-analyzer.md
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 |
--- name: test-analyzer description: 测试覆盖率分析。当需要了解测试质量、未测试代码、 测试盲区时调用。 tools: Read, Glob, Bash model: haiku --- 你是测试覆盖率专家。分析源码和测试文件，找出未被覆盖的关键路径。 用 Bash 运行 `npx jest --coverage --json` 获取覆盖率数据（如果可用）。 否则通过阅读测试文件手动分析。 输出 JSON 格式： { "coverage_estimate": "百分比估算", "untested_functions": ["函数列表"], "priority_gaps": ["最需要补充测试的功能"], "summary": "一句话总结" } |
Step 2：编写主入口（SDK 方式）
review.ts
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 |
import { query } from '@anthropic-ai/claude-agent-sdk'; /** * 代码库全面审查：三个 Subagent 并行工作 * 安全审查 + 测试覆盖 + 性能分析 */ async function fullCodeReview(targetPath: string) { console.log(`\n🔍 开始对 ${targetPath} 进行全面审查...\n`); const startTime = Date.now(); const events: string[] = []; const stream = query({ prompt: `对 ${targetPath} 目录进行全面代码审查。 请并行启动以下三个专家子任务： 1. 调用 security-reviewer 进行安全漏洞扫描 2. 调用 test-analyzer 分析测试覆盖率 3. 调用 perf-auditor 检查性能问题 最后整合三份报告，给出优先级排序的改进清单。`, options: { // ⚠️ Task 必须在 allowedTools 中，否则 Subagent 无法被调用 allowedTools: ['Read', 'Glob', 'Grep', 'Bash', 'Task'], // 动态定义额外的 Subagent（会覆盖同名文件定义） agents: { 'perf-auditor': { description: '性能审计：检查 N+1 查询、内存泄漏、低效算法', prompt: `你是性能优化专家。 重点检查： - 数据库 N+1 查询问题 - 大量同步 I/O 阻塞 - 内存泄漏风险（未释放的 listener、闭包引用） - 可缓存但未缓存的重复计算 输出 JSON：{ "issues": [...], "quick_wins": [...], "summary": "..." }`, tools: ['Read', 'Grep', 'Glob'], model: 'haiku' // 性能任务用 Haiku 节省成本 } }, // 预算保护，防止失控 maxBudgetUsd: 2.0 } }); // 处理流式消息 for await (const message of stream) { if (message.type === 'tool_use') { // 兼容新版 "Agent" 和旧版 "Task" if (message.name === 'Agent' || message.name === 'Task') { const agentName = message.input?.agent_name || 'unknown'; events.push(`⚡ [${elapsed(startTime)}] 启动 Subagent: ${agentName}`); console.log(events[events.length - 1]); } } if (message.type === 'text' && message.text) { // 实时输出最终结果 process.stdout.write(message.text); } } console.log(`\n\n✅ 审查完成，耗时 ${elapsed(startTime)}`); } function elapsed(start: number): string { return `${((Date.now() - start) / 1000).toFixed(1)}s`; } // 运行 fullCodeReview('./src/auth').catch(console.error); |
Step 3：运行 Demo
|
1 2 3 4 5 6 7 8 9 10 11 12 13 |
# 安装依赖 npm install @anthropic-ai/claude-agent-sdk # 运行（Node.js 18+ 或 Bun） npx tsx review.ts # 或者在 Claude Code 交互式模式中直接调用 claude # 然后输入： > @security-reviewer 审查 src/auth 目录的安全问题 # 列出所有可用 Subagent claude agents |
预期输出
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 |
🔍 开始对 ./src/auth 进行全面审查... ⚡ [0.8s] 启动 Subagent: security-reviewer ⚡ [0.9s] 启动 Subagent: test-analyzer ⚡ [1.0s] 启动 Subagent: perf-auditor # 三个 Subagent 并行工作中... ## 综合审查报告 ### 🔴 Critical Issues（立即修复） 1. **[Security]** src/auth/login.ts:42 - SQL 拼接注入风险 修复：使用参数化查询 ### 🟡 High Priority 2. **[Test]** token.ts 的 refresh() 函数无单元测试 3. **[Perf]** 每次请求都重新建立数据库连接（N+1） ### 🟢 Quick Wins ... ✅ 审查完成，耗时 18.3s（三任务并行 vs 串行约 45s） |
💡 交互式模式快捷调用在 Claude Code 交互式会话中，可以用
@subagent-name 任务描述手动调用特定 Subagent， 也可以让 Claude 根据任务自动判断并调用合适的 Subagent（这正是 description 字段的作用）。
执行原理深度解析
理解 Subagent 的执行机制，能帮你写出更高效的配置。
调用机制：Agent Tool
Subagent 通过一个名为 Agent Tool（旧版叫 Task Tool）来触发。 当主 Agent 决定调用 Subagent 时，它会生成一个 tool_use 消息块， 名称为 Agent，参数包含目标 Subagent 名称和任务描述。
|
1 2 3 4 5 6 7 8 9 |
{ "type": "tool_use", "name": "Agent", // v2.1.63+ 改名为 Agent，旧版为 Task "input": { "agent_name": "security-reviewer", "description": "对 src/auth 目录进行安全审查", "prompt": "请检查 src/auth/ 下所有文件的安全漏洞..." } } |
Context 隔离原理
每个 Subagent 的工作过程如下：
并行执行原理
主 Agent 可以在一次响应中发出多个 Agent Tool 调用，Claude Code Runtime 会并发执行这些 Subagent。 这正是为什么三个审查任务可以同时进行，总耗时接近单个最慢任务的时间，而非三者之和。
⚠️ 兼容性提示Tool 名称在 v2.1.63 从
"Task"改为"Agent"。system:init工具列表和permission_denials[].tool_name中仍使用"Task"。 为了向前兼容，检测时应同时检查两个名称：block.name === 'Agent' || block.name === 'Task'。
Subagent 的限制
| 限制项 | 说明 |
|---|---|
| 不能递归调用 | Subagent 的工具列表中不能包含 Task/Agent，即 Subagent 不能再生成 Subagent |
| 工具继承 | 不指定 tools 字段则继承父 Agent 所有工具；建议明确限制权限 |
| 上下文单向传递 | 主 Agent → Subagent 单向，Subagent 间无法直接通信 |
| 计费独立 | 每个 Subagent 的 Token 消耗独立计算，记得设置 maxBudgetUsd |
最佳实践与常见陷阱
✅ 最佳实践
Best Practice 1 — Description 要像搜索引擎关键词Description 是 Claude 决定何时调用你的 Subagent 的唯一依据。 写清楚触发条件（何时调用）比描述功能更重要。 例如：“当需要检查 SQL 注入、XSS、认证漏洞时调用” 比 “安全代码检查工具” 更有效。
Best Practice 2 — 只读任务明确限制工具权限分析类 Subagent 只需要
Read, Grep, Glob， 绝不要给它Write, Bash。最小权限原则既防止误操作，也让 Claude 更聚焦。Best Practice 3 — 让 Subagent 输出结构化 JSON在 System Prompt 中要求 Subagent 返回 JSON 格式，便于主 Agent 解析和整合多个 Subagent 的结果。 同时要求“不要包含中间过程，只返回最终结论”。
Best Practice 4 — 用廉价模型处理简单子任务
model: 'haiku'适合格式转换、简单搜索等任务，成本仅为 Sonnet 的约 1/5。 把 Sonnet 留给需要深度推理的核心任务，分配给安全审查等高难度 Subagent。
❌ 常见陷阱
Trap 1 — 忘记把 Task 加入 allowedTools最常见的错误！ 如果
allowedTools中没有"Task"（SDK 方式）， 主 Agent 根本无法调用任何 Subagent，且不会报错，只是静默地不生成子任务。Trap 2 — 在 Subagent tools 中包含 TaskSubagent 不支持递归调用。如果你在 Subagent 的
tools中包含了"Task"， 它要么被忽略，要么引发意外行为。Trap 3 — Subagent 返回过多中间信息如果不在 System Prompt 中明确要求”只返回最终结论”，Subagent 可能会把读取的大量文件内容 作为结果返回，反而污染了主 Agent 的上下文——这和不用 Subagent 没有区别。
Trap 4 — 没有设置预算上限多个并行 Subagent 同时消耗 Token，在复杂任务中费用可能快速累积。 在 SDK 中始终设置
maxBudgetUsd参数作为保险。
