课程信息

⠀

作者：老金
GitHub：https://github.com/KimYx0207
公众号：老金带你玩AI
X（Twitter）：老金带你玩AI
个人博客：https://aiking.dev
预计学时：1-2小时
难度等级：⭐⭐⭐ 中级
更新日期：2026年9月14日
适用版本：Claude Code v2.1.270（验证于 2026-09-14；旧差量保留为历史基线）

📚 本课学习目标

⠀

我把子代理当成分工工具，不当成神奇按钮；多开一个 agent 之前，先问清它到底负责什么。

⠀

2026-08-06 操作口径：v2.1.198 起 subagent 默认在后台运行（Explore agent 现继承主会话模型而非 haiku）；v2.1.219 起嵌套深度默认提升到 3 层（v2.1.217 曾临时回退到 0，v2.1.219 恢复到 3）；同时引入防失控上限——当时每会话 subagent 生成数默认 200、并发默认 20（累计生成数上限已在 v2.1.224 移除，见下文补录）（--max-budget-usd 达上限时会中止后台 subagent）。安全侧：v2.1.210 修复了 worktree 隔离 subagent 对主 checkout 做破坏性 git 操作的问题。/code-review 和 /deep-research 已重制为后台 subagent 形态（v2.1.218）。演示时仍先讲「边界清晰的一层委派」，再讲多层；多层不要当成默认做法。

⠀

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

⠀

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

术语表

⠀

术语

英文全称

通俗解释

Subagent

Sub-agent

子代理，Claude Code 通过 Agent 工具启动的专业化 AI 代理

VoltAgent

社区维护的 awesome-claude-code-subagents 开源项目

Agent Definition

.md 格式的代理定义文件，描述代理的角色、能力和行为规范

Agent 工具

Agent Tool

Claude Code 内置工具，用于启动子代理执行独立任务；旧资料可能写作 Task

并行调用

Parallel Invocation

同时启动多个子代理处理不同任务，提高效率

⚠️ 重要提醒：Token 消耗

⠀

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

第一部分：官方快速上手

⠀

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

⠀

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

⠀

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

⠀

你需要记住的 3 个入口

⠀

入口

作用

什么时候用

Agent 工具

把一个子任务委派给独立上下文窗口

日常并行处理

.claude/agents/

项目级子代理定义目录

当前仓库专用代理

~/.claude/agents/

用户级子代理定义目录

跨项目复用代理

⠀

官方最小示例

⠀

请开一个 reviewer 子代理，检查这次改动的回归风险和缺失测试。

⠀

并行开两个子代理：
1. 一个检查后端接口变更
2. 一个检查前端样式回归

⠀

查看与管理

⠀

在 Claude Code 里用 /agents 查看当前已启用的子代理
项目级定义优先于用户级定义
如果仓库里存在多层 .claude/agents 或 .claude/skills，以当前工作目录最近的配置为准；排障时先确认你是在仓库根目录还是子目录启动的会话
子代理最适合做边界清晰、可独立完成的任务，不适合把主流程完全拆碎

第二部分：社区代理资源（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

⠀

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

⠀

确定存放路径：

全局可用：将代理文件放入 ~/.claude/agents/
项目专用：将代理文件放入当前项目根目录下的 .claude/agents/

复制文件：从社区仓库中选择需要的 .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 就是"你组建一个项目组，分工合作"。

⠀

核心概念

⠀

2026-09-14 当前基线（v2.1.270）：并发上限现在可调：CLAUDE_CODE_WORKFLOW_MAX_CONCURRENT_AGENTS（取值 1–256）能提高 Workflow 工具单次运行的并发 agent 数；CLAUDE_CODE_SUBAGENT_MODEL_FORCE 可以让 CLAUDE_CODE_SUBAGENT_MODEL（或主模型）覆盖所有 subagent，忽略每次派生和 agent 定义里的 model:。稳定性上修了几个直接影响长任务的问题：响应在流式传输中断（休眠、掉线、服务端错误）时 subagent 会自动续跑而不是停住；转录超过 5 MB 的 subagent 恢复不再报 "No transcript found"；停掉后台 subagent 时它的监控也会一并停。远程会话里前台 subagent 的工具调用现在可以实时流式显示（后台 subagent 仍只显示状态）；后台 agent 运行期间，远程和无头会话不再误报"等待你输入"。

⠀

中间版本补录（核查日：2026-09-14）：v2.1.224 移除了每会话累计派生 200 个 subagent 的上限，并发和深度限制仍保留。v2.1.232 起默认支持 fork：subagent_type: "fork" 继承完整对话与提示缓存；交互会话里，非 teammate 的 subagent 默认在后台运行。共享上下文不等于隔离文件，派发前仍要明确文件职责；需要独立工作树时另行配置隔离。来源：官方 changelog。

⠀

v2.1.139→v2.1.158 关键更新：claude agents Agent View 已成为管理运行中、等待输入和已完成会话的重要入口；claude agents --json 可用于脚本化查看后台会话；--cwd、--add-dir、--settings、--mcp-config、--plugin-dir、--permission-mode、--model、--effort 等参数让后台会话更容易复用当前项目配置。v2.1.154 起还可以在 Agent View 输入 ! <command> 或用 claude --bg --exec '<command>' 跑可附着的后台 shell。v2.1.157 起 claude agents 会尊重 settings.json 里的 agent 字段，并可用 --agent <name> 覆盖；EnterWorktree 可以在会话中切换 Claude 管理的 worktree，完成后的 Claude worktree 也会保持解锁，方便 git worktree remove / prune 清理。Windows、worktree、stale daemon、pinned session、resume 后台子代理和 subagent 隔离场景也有多轮修复，团队教程里不要再默认把后台 agent 当成会写共享 checkout 的普通子进程。

⠀

概念

说明

类比

Team Lead

团队领导代理，负责分配任务和协调进度

项目经理

Teammate

团队成员代理，执行具体任务并汇报

开发工程师

TaskList

共享任务列表，所有成员可见进度和状态

看板 / Trello

SendMessage

代理间通信机制，支持直接消息和广播

团队群聊

⠀

与普通 Subagent（Agent 工具）的区别

⠀

特性

普通 Subagent（Agent 工具）

Agent Teams

协作模式

一对一（主代理 → 子代理）

多对多（团队协作）

任务管理

各自独立，互不感知

共享任务列表，实时同步

通信方式

子代理返回结果给主代理

团队成员间可互相通信

生命周期

任务完成即退出

持续运行直到团队解散

适用场景

独立子任务

复杂项目分工

⠀

典型使用场景

⠀

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

⠀

快速示例

⠀

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

⠀

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

⠀

💡 何时用哪个？

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

v2.1.133→v2.1.158 重要变更：worktree、Agent View 和子代理环境

⠀

worktree.baseRef（v2.1.133）

⠀

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

⠀

值

分叉来源