Skip to content

06-Subagent子代理完整指南.md

Latest commit

 

History

History
408 lines (309 loc) · 30.2 KB

06-Subagent子代理完整指南.md

File metadata and controls

408 lines (309 loc) · 30.2 KB

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

课程信息

  • 作者：老金
  • GitHub：https://github.com/KimYx0207
  • 公众号：老金带你玩AI
  • X（Twitter）：老金带你玩AI
  • 个人博客：https://aiking.dev
  • 预计学时：1-2小时
  • 难度等级：⭐⭐⭐ 中级
  • 更新日期：2026年4月
  • 适用版本：Claude Code v2.1.92（验证于2026-04-05）

📚 本课学习目标

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

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

2026-04 差量更新（先读）

这章旧版最大的问题，是把“官方 Subagent 能力”和“第三方社区代理包”写成了同一件事。现在请先分清：

  • 官方 Subagents：Claude Code 自己支持的子代理机制，核心是 Task 委派、独立上下文窗口、子代理定义文件。
  • 社区代理包：例如 VoltAgent 的 awesome-claude-code-subagents，它们是第三方资源，不是 Claude Code 官方内置功能。
  • Agent Teams：当前仍是实验性功能，默认不应当作稳定主路径来写，需要显式开启。

因此，本章前半部分先讲官方模型，后半部分把 VoltAgent 作为“可选社区资源目录”来看。

术语表

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

⚠️ 重要提醒：Token 消耗

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

第一部分：官方快速上手

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

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

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

你需要记住的 3 个入口

入口 作用 什么时候用
Task 工具 把一个子任务委派给独立上下文窗口 日常并行处理
.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-designer REST 和 GraphQL API 架构师
backend-developer 可扩展 API 的服务器端专家
electron-pro 桌面应用程序专家
frontend-developer React、Vue 和 Angular 的 UI/UX 专家
fullstack-developer 端到端功能开发
graphql-architect GraphQL Schema 和 Federation 专家
microservices-architect 分布式系统设计师
mobile-developer 跨平台移动专家
ui-designer 视觉设计和交互专家
websocket-engineer 实时通信专家
wordpress-master WordPress 开发和优化专家

2. 语言专家 (Language Specialists)

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

代理 说明
typescript-pro TypeScript 专家
python-pro Python 生态系统大师
rust-engineer 系统编程专家
golang-pro Go 并发专家
java-architect 企业级 Java 专家
javascript-pro JavaScript 开发专家
react-expert React 18+ 现代模式专家
vue-expert Vue 3 Composition API 专家
angular-architect Angular 15+ 企业模式专家
nextjs-developer Next.js 14+ 全栈专家
swift-expert iOS 和 macOS 专家
kotlin-expert 现代 JVM 语言专家
cpp-pro C++ 性能专家
csharp-developer .NET 生态系统专家
php-pro PHP Web 开发专家
sql-pro 数据库查询专家
django-developer Django 4+ Web 开发专家
laravel-expert Laravel 10+ PHP 框架专家
rails-expert Rails 8.1 快速开发专家
spring-boot-engineer Spring Boot 3+ 微服务专家
flutter-expert Flutter 3+ 跨平台移动开发专家
elixir-expert Elixir 和 OTP 容错系统专家
dotnet-core-expert .NET 8 跨平台专家
dotnet-framework-4.8-expert .NET Framework 传统企业专家
powershell-5.1-expert Windows PowerShell 5.1 自动化专家
powershell-7-expert 跨平台 PowerShell 7+ 自动化专家

3. 基础设施 (Infrastructure)

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

代理 说明
cloud-architect AWS/GCP/Azure 专家
devops-engineer CI/CD 和自动化专家
kubernetes-expert 容器编排大师
terraform-engineer 基础设施即代码专家
database-admin 数据库管理专家
sre 站点可靠性工程专家
deployment-engineer 部署自动化专家
azure-infra-engineer Azure 基础架构专家
network-engineer 网络基础设施专家
platform-engineer 平台架构专家
security-engineer 基础设施安全专家
incident-responder 系统事件响应专家
devops-incident-responder DevOps 事件管理
windows-infra-admin AD、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-tester A11y 合规专家
chaos-engineer 系统弹性测试专家
compliance-auditor 监管合规专家
testing-automation-expert 测试自动化框架专家
ad-security-auditor Active Directory 安全审核专家
powershell-security-hardener PowerShell 安全加固专家

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-pro PostgreSQL 数据库专家
mlops-engineer MLOps 和模型部署专家
nlp-engineer 自然语言处理工程师
prompt-engineer 提示优化专家

6. 开发者体验 (Developer Experience)

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

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

7. 专业领域 (Specialized Domains)

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

代理 说明
blockchain-developer Web3 和加密货币专家
game-developer 游戏开发专家
fintech-engineer 金融科技专家
iot-engineer 物联网系统开发人员
embedded-systems-engineer 嵌入式和实时系统专家
api-documenter API 文档专家
seo-specialist 搜索引擎优化专家
mobile-app-developer 移动应用专家
payment-integration-specialist 支付系统专家
quantitative-analyst 量化分析专家
risk-manager 风险评估和管理专家
m365-admin Microsoft 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-orchestrator IT 运维工作流编排专家
pied-piper SDLC 工作流 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/Task Agent Teams
协作模式 一对一（主代理 → 子代理） 多对多（团队协作）
任务管理 各自独立，互不感知 共享任务列表，实时同步
通信方式 子代理返回结果给主代理 团队成员间可互相通信
生命周期 任务完成即退出 持续运行直到团队解散
适用场景 独立子任务 复杂项目分工

典型使用场景

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

快速示例

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

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

💡 何时用哪个？

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

下一步学习：想深入了解如何自定义代理定义文件？请参考 07-Skills定制完整指南 中关于 Agent 配置的部分。