Claude Code Agents 多代理协作实战——并行任务自动化

, , , , ,

Claude Code Agents 多代理协作实战——并行任务自动化

Claude Code Agents（子代理系统）是 Claude Code 的高级特性，允许你定义专用子代理来并行执行子任务。本文从基础概念到高级实战，带你全面掌握多代理协作技术。

目录

  1. 什么是 Agents？
  2. Agents 的工作原理
  3. 前置要求与环境准备
  4. 创建你的第一个 Agent
  5. Agent 定义详解
  6. 实战：项目级 Agent 体系搭建
  7. 并行任务编排技巧
  8. 调试与优化
  9. 常见问题

一、什么是 Agents？

Agents（子代理）是 Claude Code 中的专用子代理系统。你可以为特定任务类型（如代码审查、测试编写、文档生成）定义专门的子代理，每个子代理拥有独立的指令、工具权限和上下文窗口。

核心优势

特性 说明
并行执行 多个 Agent 可以同时处理不同任务
专用指令 每个 Agent 有自己的行为规范
隔离上下文 Agent 之间的上下文互不干扰
任务分派 用 @agent-name 语法分配任务
结果汇总 所有 Agent 结果会回到主会话

适用场景

  • 大型重构：将代码拆分为多个独立模块并行修改
  • 多文件测试：同时为多个组件编写单元测试
  • 全栈开发：前端/后端/数据库工作并行进行
  • 代码审查：多个 PR 同时审查
  • 文档生成：为多个模块同时生成文档

Agents vs Skills vs Hooks

特性 Agents Skills Hooks
执行方式 手动触发 @agent-name 自动匹配自然语言 自动触发事件
是否独立 ✅ 独立会话 ❌ 当前会话内 ❌ 当前会话内
并行能力 ✅ 支持 ❌ 不支持 ❌ 串行
指令定制 ✅ 详细定义 ✅ 详细定义 ❌ 简单脚本
上下文隔离 ✅ 完全隔离 ❌ 共享 ❌ 共享

二、Agents 的工作原理

执行流程

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
主会话
  │
  ├── @agent-1 "为 UserService 写测试"  ──→ 子代理 1（测试编写）
  │                                          ├─ 读取 UserService 源码
  │                                          ├─ 编写测试用例
  │                                          └─ 返回：已创建 5 个测试文件
  │
  ├── @agent-2 "重构 ProductService"    ──→ 子代理 2（代码重构）
  │                                          ├─ 分析 ProductService
  │                                          ├─ 执行重构
  │                                          └─ 返回：重构完成，通过测试
  │
  └── @agent-3 "更新 API 文档"          ──→ 子代理 3（文档编写）
                                             ├─ 扫描路由定义
                                             ├─ 生成 OpenAPI 文档
                                             └─ 返回：API 文档已更新

通信模型

1
2
3
主会话 ←→ Agent 1    （并行）
主会话 ←→ Agent 2    （并行）
主会话 ←→ Agent 3    （并行）

Agent 之间不直接通信，所有结果汇总到主会话。主会话负责协调和整合。

关键限制

  • Agent 数量限制：同时运行的 Agent 数量受 Claude Code 计划限制（通常 3-5 个）
  • Agent 无法创建子 Agent（不支持嵌套）
  • Agent 的上下文限制是独立的，不计入主会话

三、前置要求与环境准备

版本要求

1
2
3
4
5
# 检查 Claude Code 版本（确保 >= 0.2.0）
claude --version

# 如果版本过低，更新
npm update -g @anthropic-ai/claude-code

目录结构

Agents 定义存储在 .claude/agents/ 目录下：

1
2
3
4
5
6
7
8
9
10
11
项目根目录/
├── .claude/
│   ├── agents/           ← Agents 定义文件夹
│   │   ├── tester.md       ── 测试编写 Agent
│   │   ├── reviewer.md     ── 代码审查 Agent
│   │   ├── refactorer.md   ── 重构 Agent
│   │   └── documenter.md   ── 文档编写 Agent
│   ├── skills/           ← Skills 定义
│   ├── commands/         ← 自定义命令
│   └── rules/            ← 项目规则
└── ...

四、创建你的第一个 Agent

步骤 1：创建 Agents 目录

1
mkdir -p .claude/agents

步骤 2：编写 Agent 定义文件

创建一个代码审查 Agent：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
cat > .claude/agents/reviewer.md << 'EOF'
---
name: Reviewer
description: 专业的代码审查员，擅长发现 bug、安全漏洞和性能问题
---

# Reviewer Agent

你是代码审查专家。你的职责是对代码进行彻底审查。

## 审查流程

1. **理解代码**：先阅读完整文件，理解业务逻辑
2. **逐行检查**：逐行审查代码，关注以下方面：
   - 逻辑错误和边界条件
   - 安全漏洞（SQL 注入、XSS、权限问题等）
   - 性能问题（不必要的循环、内存泄漏等）
   - 代码风格和可读性
   - 测试覆盖度
3. **提供反馈**：按优先级分类输出：

   ### 🔴 严重问题（必须修复）
   ### 🟡 建议优化
   ### ⚪ 次要问题（风格相关）
   ### ✅ 好的实践

## 输出格式要求

使用 Markdown 列表，每个问题附带：
- 文件路径和行号
- 问题描述
- 修复建议（含代码示例）
- 优先级标签

## 禁止行为

- 不要修改代码（只审查）
- 不要添加自己的风格偏好（除非项目规范要求）
- 不要过度审查（只关注实际问题）
EOF

步骤 3：使用 Agent

在主会话中调用：

1
2
3
4
5
# 让审查 Agent 审查某个文件
@reviewer 请审查 src/user-service.ts

# 也可以传递多个文件
@reviewer 请审查 API 层的所有文件

五、Agent 定义详解

完整的 Agent 定义文件结构

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
---
name: Agent名称            # 必填，唯一标识，用于 @引用
description: 简短描述      # 必填，帮助 Claude 理解何时使用
model: sonnet             # 可选，指定模型（默认继承主会话）
temperature: 0.3          # 可选，温度参数（0-1）
max_tokens: 4096          # 可选，最大输出 tokens
tools:                    # 可选，限制可用工具
  - Read                # 只读工具（推荐用于审查类 Agent）
  # 完整工具列表见下文
---

# Agent 名称

完整的指令内容...

## 行为规范

定义 Agent 的行为准则...

## 输出格式

定义 Agent 的输出规范...

工具权限配置

Agent 的 tools 字段可以限制其可用的工具集：

工具 说明 适用于
Read 读取文件 审查、分析类 Agent
Edit 创建和编辑文件 开发、重构类 Agent
Command 执行 shell 命令 测试、构建类 Agent
Search 搜索文件和内容 分析类 Agent
Browser 访问网页 文档、调研类 Agent

工具权限组合示例

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
# 只读 Agent（审查员）
tools:
  - Read
  - Search

# 全功能 Agent（开发者）
tools:
  - Read
  - Edit
  - Command
  - Search

# 测试 Agent
tools:
  - Read
  - Edit
  - Command

完整的 Agent 示例合集

测试编写 Agent：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
---
name: Tester
description: 专业测试工程师，擅长编写单元测试和集成测试
tools:
  - Read
  - Edit
  - Command
---

# Tester Agent

你是测试专家。按照以下流程编写测试：

## 测试策略

1. 阅读目标文件，理解其功能和接口
2. 检查已有测试文件，避免重复
3. 编写测试用例，覆盖以下场景：
   - 正常路径（Happy Path）
   - 边界条件（Edge Cases）
   - 错误处理（Error Cases）
4. 运行测试确保通过

## 测试规范

- 使用项目已有的测试框架（Jest/Vitest/Pytest）
- 遵循项目的测试命名规范
- 每个测试函数只测试一个行为
- 使用 Arrange-Act-Assert 模式
- 避免测试实现细节

重构 Agent：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
---
name: Refactorer
description: 代码重构专家，擅长提取函数、优化结构和消除重复
tools:
  - Read
  - Edit
  - Search
  - Command
---

# Refactorer Agent

你是代码重构专家。遵循以下原则：

## 重构原则

1. **不改变功能**：重构前后功能必须完全一致
2. **小步提交**：每次只做一种重构操作
3. **测试保障**：重构前确保有测试覆盖
4. **可逆操作**：每个修改都可以回滚

## 重构流程

1. 分析代码结构，识别重构机会
2. 运行现有测试，确保 baseline
3. 执行重构（每次一步）
4. 运行测试验证
5. 重复直到完成

六、实战：项目级 Agent 体系搭建

场景：全栈 Web 应用功能开发

假设你要实现一个”用户管理”模块的前后端功能。传统方式需要一步步执行，使用 Agents 可以并行加速。

步骤 1：准备 Agent 定义

创建 .claude/agents/ 目录下的 3 个 Agent：

frontend.md：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
---
name: Frontend
description: 前端开发工程师，擅长 React/Vue 组件开发
tools:
  - Read
  - Edit
  - Search
  - Command
---

# Frontend Agent

你是资深前端工程师。按照以下规范开发：

## 开发规范

- 使用项目已有的组件库和样式系统
- 遵循项目的目录结构约定
- 使用 TypeScript 类型定义
- 添加错误边界和加载状态
- 编写组件的单元测试

## 工作流程

1. 阅读后端 API 定义
2. 创建类型定义文件
3. 实现业务逻辑 hooks/utilities
4. 编写 UI 组件
5. 添加单元测试
6. 确保 TypeScript 编译通过

backend.md：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
---
name: Backend
description: 后端开发工程师，擅长 API 设计和数据库操作
tools:
  - Read
  - Edit
  - Search
  - Command
---

# Backend Agent

你是资深后端工程师。项目使用 Express.js + Prisma ORM。

## 开发规范

- 遵循 RESTful API 设计原则
- 所有路由使用 try-catch 错误处理
- 使用 Zod 进行请求体验证
- 数据库迁移使用 Prisma Migrate
- 编写集成测试

## 工作流程

1. 定义数据模型和数据库迁移
2. 实现数据访问层（Repository）
3. 实现业务逻辑层（Service）
4. 实现 API 路由（Controller）
5. 添加请求体验证
6. 编写测试

database.md：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
---
name: Database
description: 数据库管理员，擅长 Schema 设计和数据迁移
tools:
  - Read
  - Edit
  - Command
---

# Database Agent

你是数据库专家。项目使用 PostgreSQL + Prisma。

## 工作规范

- 所有数据模型需要考虑索引优化
- 大表需要设计合适的索引
- 外键关系必须明确定义
- 考虑数据增长和查询性能
- 软删除实现使用 deletedAt 字段

## 工作流程

1. 分析业务需求的数据模型
2. 更新 Prisma Schema
3. 生成迁移文件
4. 编写种子数据
5. 验证迁移可以正常执行

步骤 2：在主会话中并行调度

1
2
3
4
5
6
7
我在项目中需要实现"用户管理"模块，包含基本的 CRUD 功能。

@Database 请定义 User 模型，包含：id、name、email、role（枚举：ADMIN/USER）、status、createdAt、updatedAt、deletedAt。以及角色相关的 Role 模型。

@Backend 请实现用户管理的完整 API：GET /users（分页）、GET /users/:id、POST /users、PUT /users/:id、DELETE /users/:id（软删除）。使用 Express + Prisma，参考 database 的 schema。

@Frontend 请实现用户管理页面：用户列表表格（分页、搜索）、创建用户表单、编辑用户表单、删除确认对话框。等待 backend API 就绪后对接。

步骤 3：整合结果

三个 Agent 并行工作，完成后主会话汇总结果：

1
2
3
4
5
✅ @Database 完成：创建了 User 模型，生成了迁移文件
✅ @Backend 完成：实现了 5 个 API 端点，所有测试通过
✅ @Frontend 完成：创建了 4 个组件，TypeScript 编译通过

下一步：运行端到端测试验证完整功能。

场景：大型代码库重构

1
2
3
4
5
6
7
8
9
10
@Refactorer 请将 utils/helpers.ts 中的工具函数按职责拆分到 utils/ 目录下：
- string-helpers.ts（字符串处理）
- array-helpers.ts（数组处理）
- date-helpers.ts（日期处理）
- validation.ts（验证逻辑）
保留原来的 helpers.ts 作为入口重新导出。

@Tester 请为 utils/ 目录下的所有工具函数编写单元测试。

@Reviewer 重构完成后，审查新的目录结构。完成后运行 `npm test`。

七、并行任务编排技巧

1. 依赖管理

任务之间存在依赖关系时，使用主会话编排：

1
2
3
4
5
6
7
8
9
# 第一步：并行执行独立任务
@Database 定义数据模型
@Backend 准备基础框架

# 第二步（等待第一步完成）：执行依赖任务
@Backend 实现 API（使用已定义的数据模型）

# 第三步（等待第二步完成）：执行依赖任务
@Frontend 实现页面（对接 backend API）

2. 分治法

将大型任务拆分为可并行的小任务：

1
2
3
4
5
6
7
# 不推荐：一个大任务
@Agent 请重构整个项目

# 推荐：拆分为多个并行子任务
@Refactorer 请重构 auth 模块
@Refactorer 请重构 user 模块
@Refactorer 请重构 payment 模块

3. 结果验证

Agent 返回结果后，验证其工作质量：

1
@Reviewer 请审查 @Refactorer 对 auth 模块的重构结果

4. 批量处理模式

1
2
3
4
# 为 5 个组件并行编写测试
@Tester 为 components/Button 编写单元测试
@Tester 为 components/Modal 编写单元测试
@Tester 为 components/Table 编写单元测试

八、调试与优化

监控 Agent 运行状态

1
2
3
# 在 Claude Code 会话中使用
/agents
# 显示所有 Agent 的运行状态和结果

常见问题排查

问题 可能原因 解决方案
Agent 不响应 Agent 名称拼写错误 检查 @ 后的名称是否与 Agent 定义的 name 一致
Agent 权限不足 tools 配置限制 检查 Agent 的 tools 字段是否包含所需工具
Agent 结果不理想 指令不够明确 细化 Agent 定义中的行为规范和输出格式
Agent 运行超时 任务过于复杂 拆分为更小的子任务
并行数受限 计划限制 减少同时运行的 Agent 数量

优化技巧

  1. 精确定义描述：description 字段帮助 Claude 判断何时调用 Agent
  2. 限制工具集：只读 Agent 不要给 Edit 权限，降低风险
  3. 指定输出格式：结构化输出（JSON/YAML）方便主会话处理
  4. 设置合理温度：代码任务用 temperature: 0.2-0.3，创意任务用 0.5-0.7

九、常见问题

Q1：Agent 可以调用其他 Agent 吗？

不可以。Agent 不能创建或调用其他 Agent（不支持嵌套）。所有并行 Agent 从主会话触发。

Q2：Agent 运行期间主会话可以做什么？

Agent 在后台异步运行，主会话可以继续工作或发出更多 Agent 请求。所有 Agent 的结果最终回到主会话。

Q3：Agent 之间的上下文会互相干扰吗？

不会。每个 Agent 拥有独立的会话和上下文窗口。一个 Agent 的操作不会影响另一个 Agent 的状态。

Q4：Agent 超出上下文限制怎么办？

每个 Agent 有自己的上下文限制（取决于模型和计划）。如果超出，可以：

  • 缩短 Agent 的指令
  • 减少 Agent 一次处理的文件数
  • 使用更高效的提示词

Q5：如何确保 Agent 的工作一致性？

建立统一的项目规范和约束文件：

1
2
3
4
5
6
7
8
9
10
11
12
# .claude/rules/project-standards.md
# 项目级规则，所有 Agent 都会遵循

## 前端规范
- 使用 Tailwind CSS，不使用内联样式
- 所有组件使用 TypeScript
- 使用 React Query 管理服务端状态

## 后端规范
- 使用 Zod 进行输入验证
- 所有 API 响应统一格式 { success, data, error }
- 使用 Prisma 作为 ORM

Q6：Agent 的 token 消耗如何计算？

Agent 的 token 消耗独立于主会话。每个 Agent 有独立的输入/输出计数。批量使用 Agent 时要注意总 token 消耗。

Q7：如何为不同项目共享 Agent 定义？

1
2
3
# 创建全局 Agent（所有项目可用）
mkdir -p ~/.claude/agents/
ln -s ~/.claude/agents/tester.md .claude/agents/tester.md

总结

Claude Code Agents 是实现并行开发工作流的核心工具。合理运用多代理协作可以显著提升开发效率：

  • 单 Agent 模式：适合明确的专业化任务（审查、测试）
  • 多 Agent 并行：适合大型功能的模块化开发
  • Agent + 主会话编排：适合包含依赖链路的复杂项目

记住最佳实践：精确定义 → 合理拆分 → 验证结果，逐步将你的开发工作流推向新高度。

CaoZHProgrammer

学习使我快乐。