Claude Code 最强大但使用率最低的功能是 Subagents——通过 Task 工具生成多个独立的 Claude 实例，各自有独立的上下文窗口，并行处理任务，结果只把摘要返回给主线程。掌握这个功能，开发效率能有质的飞跃。
Subagents 的核心概念
Subagent 是什么：主 Claude 通过 Task 工具生成的独立 Claude 实例，有自己独立的上下文窗口，完成任务后只返回结果摘要，不把整个对话历史带回来。
为什么重要：
- 上下文隔离：Subagent 在探索代码库时读了大量文件，这些不会污染主线程的上下文
- 真正并行：多个 Subagent 同时运行，互不等待
- 结果精炼：主线程只收到摘要，不是完整的探索过程
主 Claude → Task 工具 → Subagent 实例 1
→ Subagent 实例 2
→ Subagent 实例 3
各自独立运行
↓ ↓ ↓
结果摘要 1 结果摘要 2 结果摘要 3
↓ ↓ ↓
主 Claude 汇总
内置 Subagent 类型
Claude Code 包含几种专用 Subagent：
Explore Agent：快速、轻量，专门用于代码库探索。只读模式，快速发现文件和分析代码结构。在 Plan Mode 里研究代码库时 Claude 会自动使用。
Plan Agent：规划阶段使用，在展示实现计划前先做彻底调查。保持主上下文干净的同时收集完整信息。
General Purpose Agent：处理不适合其他类型的复杂多步骤任务。
基础：并行研究模式
最简单的 Subagent 用法——并行探索代码库不同部分：
用 4 个并行任务探索代码库，每个 Agent 负责不同目录：
- Agent 1：分析 src/api/（API 接口和路由）
- Agent 2：分析 src/services/（业务逻辑）
- Agent 3：分析 src/models/（数据模型和 Schema）
- Agent 4：分析 src/utils/（工具函数）
每个 Agent 返回该目录的功能概述、主要文件说明、对外依赖关系
每个 Agent 有自己的上下文窗口，等效于把可用上下文扩大了 4 倍。
7 任务并行实现新功能
对于复杂功能，按关注点分解并并行实现：
用并行任务实现用户资料功能：
Task 1（组件）：在 src/components/profile/ 创建：
- ProfileCard：显示用户基本信息
- ProfileEdit：编辑表单（含验证）
- AvatarUpload：头像上传（支持裁剪）
Task 2（API）：在 src/api/profile.ts 创建端点：
- GET /api/users/:id/profile
- PUT /api/users/:id/profile
- POST /api/users/:id/avatar
Task 3（数据库）：
- 更新 Prisma schema 添加 profile 相关字段
- 创建数据库 migration
- 添加 seed 数据
Task 4（测试）：
- 所有新组件的单元测试
- API 端点的集成测试（happy path + 错误场景）
- 组件的 Storybook stories
Task 5（类型）：
- 在 src/types/ 创建 Profile 相关类型定义
- 确保前后端类型一致
Task 6（状态管理）：
- 创建 useProfile Hook
- 处理加载/错误状态
Task 7（文档）：
- 更新 API 文档（docs/api.md）
- 更新 README 的功能列表
全部并行运行。
这模拟了真实团队并行开发的方式，每个成员专注各自领域。
多版本对比：让 Agent 探索不同实现路径
并行创建 3 个版本的认证流程，在不同 Git 分支里：
- Version A（feature/auth-jwt）：JWT + Refresh Token 方案
- Access Token 15 分钟，Refresh Token 7 天
- 无状态，适合微服务
- Version B（feature/auth-session）：服务端 Session 方案
- Redis 存储 Session，支持主动失效
- 适合单体应用
- Version C（feature/auth-oauth）：OAuth2 + PKCE 方案
- 接入 Google/GitHub OAuth
- 适合需要第三方登录的场景
每个版本完成后，在 COMPARISON.md 里记录：
实现复杂度、性能特点、安全性考虑、适用场景
团队可以对比三个版本，根据实际需求选择最合适的。
配置自定义 Subagent
在 .claude/agents/ 目录里创建自定义 Subagent 定义文件：
.claude/
└── agents/
├── security-reviewer.md
├── performance-analyzer.md
└── doc-generator.md
示例：安全审查 Subagent
# Security Reviewer Agent
## 描述
专门分析代码安全漏洞，聚焦 OWASP Top 10、认证问题和注入漏洞。
## 自动触发条件
以下情况自动介入：
- 新增认证或授权代码
- 修改用户输入处理逻辑
- 添加或修改数据库查询
- 实现文件操作功能
## 能力范围
- 读取源文件
- 分析代码模式
- 参考安全最佳实践
- 生成漏洞报告
## 执行步骤
分析代码时：
1. 检查注入漏洞（SQL、命令、XSS）
2. 验证认证和会话处理
3. 审查权限检查
4. 检查敏感数据处理
5. 识别常见安全反模式
返回格式：
- 严重程度（Critical/High/Medium/Low）
- 具体行号和代码片段
- 修复建议Claude 通过读取描述来判断何时使用哪个 Subagent。描述写得越准确，触发时机越合适。
依赖管理：分阶段并行
不是所有任务都能完全并行，有依赖关系的按阶段组织：
实现支付系统：
Phase 1（并行）：
- Task A：创建 Transaction 数据模型和 Prisma Schema
- Task B：配置 Stripe SDK，设置 Webhook 端点
Phase 2（Phase 1 完成后并行）：
- Task C：基于 Phase 1 的 Schema 实现支付处理 Service
- Task D：创建支付 API 端点，集成 Stripe
Phase 3（Phase 2 完成后）：
- Task E：写端到端集成测试
- Task F：实现前端支付表单
每个 Phase 完成后通报进展，确认没有问题再进入下一阶段。
Subagent 和其他工具的对比
| 工具 | 用途 | 位置 | 触发方式 |
|---|---|---|---|
| CLAUDE.md | 始终生效的项目上下文 | 项目根目录 | 自动 |
| Slash Commands | 按需调用的工作流 | .claude/commands/ | 手动（/command） |
| Subagents | 隔离的并行任务 | .claude/agents/ | 自动或显式 |
| Skills | 有丰富资料支撑的工作流 | .claude/skills/ | 自动发现 |
使用 Subagents 的时机：
- 任务需要读大量文件（把读文件的上下文消耗隔离到 Subagent）
- 多个独立任务可以并行
- 不同任务需要专门的关注点（安全 + 性能 + 正确性分别由专属 Agent 处理）
高效使用的关键原则
原则 1：明确描述，不要依赖自动判断
Claude 默认比较保守，不主动用 Subagent。明确描述你要并行的内容：
# 不够明确（可能不会用 Subagent）
"实现用户资料功能"
# 明确（触发 Subagent）
"用 4 个并行 Task 实现用户资料功能：
Task 1：前端组件，Task 2：API，Task 3：数据库，Task 4：测试"
原则 2：关联任务分组，不要细碎拆分
# 效率低（太碎）
Task 1: 读 user.ts
Task 2: 读 auth.ts
# 效率高（适当分组）
Task 1: 读取并分析所有认证相关文件（user.ts, auth.ts, session.ts）
原则 3：了解局限
- Subagent 执行时父 Agent 看不到它们的活动，完成后才能看到结果
- 父子之间没有实时通信（不同于 Agent Teams 的 Mailbox 系统）
- 文件写入冲突需要在任务设计时避免（通过清晰的文件范围边界）
来源：turion.ai Claude Code Subagents 完整指南 | Anthropic 官方文档 | 整理：ClaudeEagle