跳至主要內容

Subagent 子代理完整指南：官方 Subagents、Task 委派与社区代理资源

Mr.Over2026/5/1大约 14 分钟aiaiclaude code

Subagent 子代理完整指南：官方 Subagents、Task 委派与社区代理资源

📚 本课学习目标

完成本课学习后，你将能够：

  1. 理解子代理的概念：知道 Subagent 是什么、怎么工作的
  2. 掌握官方子代理入口：知道 .claude/agents/、/agents、Task 委派各自负责什么
  3. 分清官方能力与社区资源：明确 VoltAgent 之类的第三方代理包不是 Claude Code 官方内置
  4. 提升开发效率：在实际项目中合理使用多代理并行协作

术语表

术语英文全称通俗解释
SubagentSub-agent子代理，Claude Code 通过 Agent 工具启动的专业化 AI 代理
VoltAgent-社区维护的 awesome-claude-code-subagents 开源项目
Agent Definition-.md 格式的代理定义文件，描述代理的角色、能力和行为规范
Agent 工具Agent ToolClaude Code 内置工具，用于启动子代理执行独立任务；旧资料可能写作 Task
并行调用Parallel Invocation同时启动多个子代理处理不同任务，提高效率

⚠️ 重要提醒：Token 消耗

使用多 Agent 并行调用的 token 消耗量巨大。每启动一个子代理都会消耗独立的上下文窗口。
建议按需调用，不要一次性启动太多代理。

第一部分：官方快速上手

🎯 官方主路径：先理解，再扩展

官方 Subagents 的最小闭环不是“先去装一个第三方代理包”，而是：

  1. 知道 Claude Code 可以用 Agent 工具委派子任务
  2. 知道项目级 / 用户级子代理定义文件放在哪里
  3. 知道如何在当前项目里启用和查看它们

你需要记住的 3 个入口

入口作用什么时候用
Agent 工具把一个子任务委派给独立上下文窗口日常并行处理
.claude/agents/项目级子代理定义目录当前仓库专用代理
~/.claude/agents/用户级子代理定义目录跨项目复用代理

官方最小示例

请开一个 reviewer 子代理，检查这次改动的回归风险和缺失测试。
并行开两个子代理：
1. 一个检查后端接口变更
2. 一个检查前端样式回归

查看与管理

  • 在 Claude Code 里用 /agents 查看当前已启用的子代理
  • 项目级定义优先于用户级定义
  • 子代理最适合做边界清晰、可独立完成的任务，不适合把主流程完全拆碎

第二部分：社区代理资源（VoltAgent 等）

这一部分讲的是第三方社区资源，不是 Claude Code 官方内置目录。

方法一：交互式脚本安装（社区方案）

git clone https://github.com/VoltAgent/awesome-claude-code-subagents.git
cd awesome-claude-code-subagents
./install-agents.sh

方法二：独立快捷安装（社区方案）

curl -sO https://raw.githubusercontent.com/VoltAgent/awesome-claude-code-subagents/main/install-agents.sh
chmod +x install-agents.sh
./install-agents.sh

方法三：手动安装（社区方案）

  1. 确定存放路径：
    • 全局可用：将代理文件放入 ~/.claude/agents/
    • 项目专用：将代理文件放入当前项目根目录下的 .claude/agents/
  2. 复制文件：从社区仓库中选择需要的 .md 代理定义文件，放到对应目录。

💡 使用小贴士

  • 如何查看：安装完成后，在 Claude Code 中输入 /agents
  • 如何调用：优先用自然语言描述任务边界，再让 Claude 选择是否委派
  • 优先级规则：项目特定代理优先于全局代理

第三部分：VoltAgent 代理目录总览

以下目录是 VoltAgent 提供的社区代理集合，适合“缺能力再补能力”，不建议当成官方默认菜单来理解。

1. 核心开发 (Core Development)

插件包：voltagent-core-dev — 处理日常编码任务的基础专家。

代理说明
api-designerREST 和 GraphQL API 架构师
backend-developer可扩展 API 的服务器端专家
electron-pro桌面应用程序专家
frontend-developerReact、Vue 和 Angular 的 UI/UX 专家
fullstack-developer端到端功能开发
graphql-architectGraphQL Schema 和 Federation 专家
microservices-architect分布式系统设计师
mobile-developer跨平台移动专家
ui-designer视觉设计和交互专家
websocket-engineer实时通信专家
wordpress-masterWordPress 开发和优化专家

2. 语言专家 (Language Specialists)

插件包：voltagent-lang — 具备特定编程语言和框架深厚知识的专家。

代理说明
typescript-proTypeScript 专家
python-proPython 生态系统大师
rust-engineer系统编程专家
golang-proGo 并发专家
java-architect企业级 Java 专家
javascript-proJavaScript 开发专家
react-expertReact 18+ 现代模式专家
vue-expertVue 3 Composition API 专家
angular-architectAngular 15+ 企业模式专家
nextjs-developerNext.js 14+ 全栈专家
swift-expertiOS 和 macOS 专家
kotlin-expert现代 JVM 语言专家
cpp-proC++ 性能专家
csharp-developer.NET 生态系统专家
php-proPHP Web 开发专家
sql-pro数据库查询专家
django-developerDjango 4+ Web 开发专家
laravel-expertLaravel 10+ PHP 框架专家
rails-expertRails 8.1 快速开发专家
spring-boot-engineerSpring Boot 3+ 微服务专家
flutter-expertFlutter 3+ 跨平台移动开发专家
elixir-expertElixir 和 OTP 容错系统专家
dotnet-core-expert.NET 8 跨平台专家
dotnet-framework-4.8-expert.NET Framework 传统企业专家
powershell-5.1-expertWindows PowerShell 5.1 自动化专家
powershell-7-expert跨平台 PowerShell 7+ 自动化专家

3. 基础设施 (Infrastructure)

插件包：voltagent-infra — 负责 DevOps、云计算和系统部署。

代理说明
cloud-architectAWS/GCP/Azure 专家
devops-engineerCI/CD 和自动化专家
kubernetes-expert容器编排大师
terraform-engineer基础设施即代码专家
database-admin数据库管理专家
sre站点可靠性工程专家
deployment-engineer部署自动化专家
azure-infra-engineerAzure 基础架构专家
network-engineer网络基础设施专家
platform-engineer平台架构专家
security-engineer基础设施安全专家
incident-responder系统事件响应专家
devops-incident-responderDevOps 事件管理
windows-infra-adminAD、DNS、DHCP 和 GPO 自动化专家

4. 质量与安全 (Quality & Security)

插件包：voltagent-qa-sec — 负责测试、安全审计和代码质量保证。

代理说明
code-reviewer代码质量守护者
security-auditor安全漏洞专家
qa-automation-engineer测试自动化专家
performance-engineer性能优化专家
debugging-expert高级调试专家
error-detective错误分析和解决专家
penetration-tester道德黑客专家
architecture-reviewer架构评审专家
accessibility-testerA11y 合规专家
chaos-engineer系统弹性测试专家
compliance-auditor监管合规专家
testing-automation-expert测试自动化框架专家
ad-security-auditorActive Directory 安全审核专家
powershell-security-hardenerPowerShell 安全加固专家

5. 数据与人工智能 (Data & AI)

插件包：voltagent-data-ai — 数据工程、机器学习和 AI 专家。

代理说明
ai-engineer人工智能系统设计与部署专家
llm-architect大型语言模型架构师
ml-engineer机器学习系统专家
machine-learning-engineer机器学习专家
data-engineer数据管道架构师
data-scientist分析和洞察专家
data-analyst数据洞察与可视化专家
database-optimizer数据库优化专家
postgres-proPostgreSQL 数据库专家
mlops-engineerMLOps 和模型部署专家
nlp-engineer自然语言处理工程师
prompt-engineer提示优化专家

6. 开发者体验 (Developer Experience)

插件包：voltagent-dev-exp — 提升开发效率、工具链和文档。

代理说明
refactoring-expert代码重构专家
documentation-engineer技术文档专家
git-workflow-managerGit 工作流和分支专家
legacy-code-modernizer遗留代码现代化专家
mcp-developer模型上下文协议专家
build-engineer构建系统专家
cli-developer命令行工具创建器
dependency-manager软件包和依赖项专家
dx-optimizer开发者体验优化专家
tooling-engineer开发工具专家
slack-expertSlack 平台和 @slack/bolt 专家
powershell-ui-architectPowerShell UI/UX 专家
powershell-module-architectPowerShell 模块架构专家

7. 专业领域 (Specialized Domains)

插件包：voltagent-domains — 特定垂直领域技术专家。

代理说明
blockchain-developerWeb3 和加密货币专家
game-developer游戏开发专家
fintech-engineer金融科技专家
iot-engineer物联网系统开发人员
embedded-systems-engineer嵌入式和实时系统专家
api-documenterAPI 文档专家
seo-specialist搜索引擎优化专家
mobile-app-developer移动应用专家
payment-integration-specialist支付系统专家
quantitative-analyst量化分析专家
risk-manager风险评估和管理专家
m365-adminMicrosoft 365 管理专家

8. 业务与产品 (Business & Product)

插件包：voltagent-biz — 产品管理、业务分析和敏捷流程。

代理说明
product-manager产品战略专家
business-analyst需求专家
project-manager项目管理专家
scrum-master敏捷方法论专家
technical-writer技术文档专家
ux-researcher用户研究专家
customer-success-manager客户成功专家
sales-engineer技术销售专家
legal-advisor法律和合规专家
content-marketing-specialist内容营销专家

9. 元数据与编排 (Meta & Orchestration)

插件包：voltagent-meta — 负责代理之间的协调、任务分配和管理。

代理说明
multi-agent-coordinator高级多智能体编排
workflow-orchestrator复杂工作流自动化
agent-organizer多代理协调器
agent-installer通过 GitHub 浏览并安装代理程序
context-manager上下文优化专家
task-dispatcher任务分配专家
error-coordinator错误处理和恢复专家
performance-monitor代理性能优化
knowledge-synthesizer知识聚合专家
it-ops-orchestratorIT 运维工作流编排专家
pied-piperSDLC 工作流 AI 子代理团队协调

10. 研究与分析 (Research & Analysis)

插件包：voltagent-research — 负责搜索、市场调研和数据分析。

代理说明
research-analyst综合研究专家
competitive-analyst竞争情报专家
market-researcher市场分析和消费者洞察
search-expert高级信息检索专家
trend-analyst新兴趋势和预测专家
data-researcher数据发现与分析专家

第四部分：Agent Teams 多代理团队协作 🆕

实验性功能：Agent Teams 当前仍需显式开启实验开关后再使用，不应默认视为稳定主路径。

开启方式：设置环境变量 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1，然后再进入相关工作流。

一句话理解：如果说普通 Subagent 是"你指派一个助手去干活"，那 Agent Teams 就是"你组建一个项目组，分工合作"。

核心概念

概念说明类比
Team Lead团队领导代理，负责分配任务和协调进度项目经理
Teammate团队成员代理，执行具体任务并汇报开发工程师
TaskList共享任务列表，所有成员可见进度和状态看板 / Trello
SendMessage代理间通信机制，支持直接消息和广播团队群聊

与普通 Subagent/Task 的区别

特性普通 Subagent/TaskAgent Teams
协作模式一对一（主代理 → 子代理）多对多（团队协作）
任务管理各自独立，互不感知共享任务列表，实时同步
通信方式子代理返回结果给主代理团队成员间可互相通信
生命周期任务完成即退出持续运行直到团队解散
适用场景独立子任务复杂项目分工

典型使用场景

  • 并行开发：前端、后端、测试代理同时工作，通过 TaskList 共享进度
  • 代码审查分工：安全审查、性能审查、风格审查代理并行检查，汇总结果
  • 大型重构：多个模块同时修改，团队成员间协调接口变更

快速示例

# 在 Claude Code 中，使用自然语言请求创建团队
You: 帮我组建一个团队，并行处理以下任务：
     1. 重构用户认证模块
     2. 编写 API 集成测试
     3. 更新相关文档

Team Lead 会自动将任务分配给不同的 Teammate，各成员独立工作并通过 SendMessage 同步关键信息。

💡 何时用哪个？

  • 简单独立任务（翻译文件、生成测试）→ 普通 Subagent/Task，更轻量
  • 复杂协作项目（多模块重构、全栈开发）→ Agent Teams，但前提是你愿意接受实验性行为和额外编排成本

v2.1.133 重要变更：worktree.baseRef 和子代理环境

worktree.baseRef（v2.1.133）

当 Claude Code 为子代理或并行任务创建 git worktree 时，新 worktree 从哪里分叉？这个行为现在可以通过 worktree.baseRef 设置控制：

值分叉来源适用场景
fresh（默认）origin/<default-branch>确保从远程最新代码开始，适合协作项目
head本地 HEAD基于你当前工作状态继续，适合单人项目
// .claude/settings.json
{
  "worktree.baseRef": "head"
}

注意：默认值从旧行为（head）变更为 fresh。如果你发现新 worktree 丢失了本地未推送的更改，将 baseRef 设为 head。

CLAUDE_CODE_FORK_SUBAGENT（v2.1.132+）

当 Skill 使用 context: fork 模式（即 Forked Context 子代理）时，子进程环境变量 CLAUDE_CODE_FORK_SUBAGENT 会被自动设为 1。你可以在脚本或 Hook 中检测这个变量来区分"主会话"和"fork 子代理"。

子代理 Skill 发现修复

v2.1.121 修复了子代理无法正确发现项目级 Skills 的问题。如果你之前遇到过"子代理看不到项目 Skills"的情况，升级到 v2.1.121+ 后应该已经解决。

最近更新: