Claude Code 多 Agent 协作开发

来源：code.claude.com/docs/en/agent-teams · sub-agents | 整理时间：2026-04-04

概述

Claude Code 支持多层次的 Agent 协作模式：

需要 Claude Code v2.1.32+ 以支持 Agent 团队功能。

子 Agent（Subagents）

基本用法

在对话中直接请求即可触发子 Agent：

Use subagents to investigate how our auth system handles token refresh

子 Agent 会：

1. 独立启动一个新的 Agent 会话
2. 搜索和阅读相关文件
3. 把摘要返回给主会话
4. 不会污染主会话的上下文窗口

为什么用子 Agent？

自定义 Agent

Agent 文件格式

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

<!-- .claude/agents/reviewer.md -->
---
name: reviewer
description: Code review specialist focusing on security and performance
tools:
  - Read
  - Grep
  - Glob
model: claude-sonnet-4-6
---

You are a code review specialist. When reviewing code:

1. Check for security vulnerabilities (injection, auth, data exposure)
2. Identify performance bottlenecks
3. Verify error handling is comprehensive
4. Check code style matches CLAUDE.md conventions
5. Rate each finding: 🔴 Critical / 🟡 Warning / 🔵 Suggestion

Always provide fix suggestions, not just problems.

字段说明

三种调用方式

方式 1：自然语言调用

Ask the reviewer agent to check the changes in src/auth/

方式 2：@ 提及调用

@reviewer Check the latest commit for security issues

方式 3：会话级指定

Use the reviewer agent for all code reviews in this session

实用 Agent 示例

测试 Agent

<!-- .claude/agents/tester.md -->
---
name: tester
description: Test generation and execution specialist
tools:
  - Read
  - Write
  - Edit
  - Bash
  - Glob
  - Grep
---

You are a testing specialist. For any code given to you:

1. Analyze the code to understand its functionality
2. Identify edge cases and boundary conditions
3. Write comprehensive test cases
4. Run the tests and fix any failures
5. Report coverage summary

Use the project's test framework (check package.json for test scripts).

文档 Agent

<!-- .claude/agents/documenter.md -->
---
name: documenter
description: Documentation generation specialist
tools:
  - Read
  - Write
  - Edit
  - Glob
  - Grep
---

You are a documentation specialist. For any code given to you:

1. Read the source code thoroughly
2. Generate clear, concise documentation
3. Include usage examples and parameter descriptions
4. Add JSDoc/TSDoc comments where appropriate
5. Update README if public API changes

Agent 团队（Multi-Agent Teams）

协调模式

模式 1：并行执行

I need to refactor the authentication module. 

Use agent teams to:
- Agent 1: Refactor the login flow
- Agent 2: Refactor the token management
- Agent 3: Refactor the session handling

Each agent works on a separate worktree branch.

模式 2：流水线

Build a new API endpoint for user preferences.

Phase 1: architect agent designs the schema and API contract
Phase 2: coder agent implements the endpoint
Phase 3: tester agent writes and runs tests
Phase 4: reviewer agent does final review

模式 3：科学辩论

We have a mysterious production bug where sessions expire randomly.

Set up a scientific debate:
- Agent A argues it's a race condition in the token refresh
- Agent B argues it's a clock sync issue across servers
- Agent C argues it's a cache invalidation problem

Each agent investigates independently, then present findings.

任务管理

Agent 团队使用共享任务列表和消息系统：

// 通过 SDK 程序化控制
import { query } from "@anthropic-ai/claude-code";

const team = await query({
  prompt: "Coordinate a team to review all open PRs",
  options: {
    agentTeams: true,
    maxAgents: 3,
  },
});

成本与性能考量

最佳实践

1. 明确分工：每个 Agent 有清晰的职责边界，避免重复工作
2. 限制工具：审查 Agent 不需要 Write 权限，文档 Agent 不需要 Bash 权限
3. 先小后大：从单个子 Agent 开始，确认效果后再扩展到团队
4. 结果汇总：指定一个 Agent 或在主会话中汇总所有结果
5. 用 Worktree 隔离：并行 Agent 在不同 Git Worktree 中工作，避免冲突

相关链接

• 技能与钩子
• MCP 集成
• 无头模式与 CI/CD
• 社区技巧精选
• Agent 团队文档：https://code.claude.com/docs/en/agent-teams
• 子 Agent 文档：https://code.claude.com/docs/en/sub-agents
• 社区 Agent 编排工具：https://github.com/hesreallyhim/awesome-claude-code