子代理与 Agent Teams

子代理（Subagents）和 Agent Teams 是 Claude Code 最强大的高级功能。子代理让你在独立上下文中做调查和验证，Agent Teams 让多个 Claude 实例真正并行协作完成复杂项目。

你将学到

• 子代理的三种内置类型及使用场景
• 自定义子代理的创建方法
• Agent Teams 的架构和工作方式
• 子代理 vs Agent Teams 的选择标准
• Git Worktrees 与 Agent 的配合

适合谁

• 处理大型项目或复杂重构的高级开发者
• 需要并行推进多个子任务的团队
• 对 AI Agent 协作感兴趣的技术人员

1. 子代理（Subagents）

子代理是由主会话派生的独立工作实例。它在单独的上下文中执行任务，完成后将结果摘要返回给主会话。

核心优势

• 上下文隔离：子代理的探索不会填满主对话上下文
• 并行执行：多个子代理可以同时工作
• 专注输出：返回精炼的摘要，而不是原始数据

三种内置类型

使用子代理

直接用自然语言请求：

Use subagents to investigate how our authentication system handles
token refresh, and whether we have any existing OAuth utilities.

use a subagent to review this code for edge cases

Launch 3 subagents in parallel:
1. One to search for all database queries
2. One to analyze the middleware stack
3. One to check test coverage

2. 自定义子代理

在 .claude/agents/ 目录下创建 Markdown 文件：

安全审查代理

.claude/agents/security-reviewer.md：

---
name: security-reviewer
description: Reviews code for security vulnerabilities
tools: Read, Grep, Glob, Bash
model: opus
---

You are a senior security engineer. Review code for:
- Injection vulnerabilities (SQL, XSS, command injection)
- Authentication and authorization flaws
- Secrets or credentials in code
- Insecure data handling

Provide specific line references and suggested fixes.

性能分析代理

.claude/agents/performance-analyzer.md：

---
name: performance-analyzer
description: Analyzes code for performance bottlenecks
tools: Read, Grep, Glob, Bash
---

You are a performance engineer. Analyze code for:
- N+1 query patterns
- Missing indexes in database queries
- Memory leaks
- Unnecessary re-renders in React components
- Large bundle sizes

Provide specific recommendations with estimated impact.

Frontmatter 配置

3. Agent Teams

Agent Teams 是更高级的并行协作模式——多个独立的 Claude Code 实例组成团队，通过共享任务列表和消息系统协调工作。

启用

export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

架构

Team Lead (你的主 Claude Code 会话)
    ├── Teammate 1 (独立 Claude 实例)
    ├── Teammate 2 (独立 Claude 实例)
    └── Teammate 3 (独立 Claude 实例)

共享基础设施：
    ├── Task List (共享任务列表)
    └── Mailbox (Agent 间消息)

• Team Lead：主会话，负责创建团队、分配任务、协调
• Teammates：独立 Claude 实例，处理分配的任务
• Task List：共享工作项列表，队友认领和完成
• Mailbox：Agent 间通信

创建团队

用自然语言描述任务和分工：

I'm building a REST API for a todo app. Create a team:
- One teammate designs the database schema
- One teammate implements the API endpoints
- One teammate writes integration tests

Claude 会自动：

1. 生成必要的队友
2. 建立共享任务列表
3. 协调工作流

4. Agent Teams 最佳场景

研究与评审

Create a team to evaluate our codebase:
- Teammate 1: Security audit
- Teammate 2: Performance analysis
- Teammate 3: Code quality review

新功能开发

Build the user notification system:
- Teammate 1: Backend API and database
- Teammate 2: Frontend components
- Teammate 3: Email/Push notification service

多假设并行调试

The checkout flow is broken. Create a team:
- Teammate 1: Check if it's a payment gateway issue
- Teammate 2: Check if it's a session/auth issue
- Teammate 3: Check if it's a database/inventory issue

大规模重构

Migrate from Express to Fastify:
- Teammate 1: Route handlers
- Teammate 2: Middleware
- Teammate 3: Tests

5. 子代理 vs Agent Teams

选择指南

用子代理当你需要：

• 快速调查某个问题
• 代码审查
• 不需要修改代码的分析任务
• 保护主对话上下文

用 Agent Teams当你需要：

• 多个 Agent 修改不同部分的代码
• 任务之间有依赖关系需要协调
• 大规模并行开发
• Agent 需要互相讨论方案

过渡点：如果你运行多个子代理但遇到上下文限制，或子代理需要互相通信，Agent Teams 是自然的下一步。

6. Git Worktrees

Worktrees 让每个 Agent 在独立的代码副本中工作，避免修改冲突：

> work in a worktree

Claude Code 会：

1. 在 .claude/worktrees/ 创建新的 git worktree
2. 基于 HEAD 创建新分支
3. 切换工作目录到 worktree

优势

• 不同 Agent 的修改互不干扰
• 轻松合并或丢弃变更
• 类似 Git 分支但更轻量、更快

Agent Teams 中每个队友自动使用独立的 worktree。

7. 自定义团队工作流

控制团队

通过自然语言指示 Team Lead：

Tell teammate 2 to focus on error handling first

Reassign the database task from teammate 1 to teammate 3

Everyone pause - I need to review the current progress

查看进度

在终端中可以在队友之间切换查看进度或提供直接反馈。

小结

• 子代理：轻量级并行，独立上下文，返回摘要，保护主对话
• Agent Teams：重量级协作，独立实例，共享任务列表，互相通信
• 三种内置子代理：Explore（高速只读）、Plan（研究规划）、General-purpose（完整能力）
• 在 .claude/agents/ 创建自定义代理，指定工具和模型
• Worktrees 为并行开发提供代码隔离
• 子代理 → Agent Teams 的过渡点：上下文不够或需要互相通信

延伸阅读

• Claude Code 官方文档 - Subagents
• Anthropic Engineering - Building a C Compiler with Agent Teams

内容来源：Anthropic 官方文档