Claude多智能体协作实战教程

Claude多智能体协作实战教程

让 Claude、Codex、Gemini 像团队一样协作。

难度: ⭐⭐⭐⭐⭐
预计阅读: 15 分钟

---

TL;DR

• CCB（Claude Code Bridge）让多个 AI CLI 互相通信
• 核心命令：/ping、/ask、/pend
• Claude 做管理（规划+验收），Codex/Gemini 做执行

注意：CCB 社区扩展项目，不是 Claude Code 官方内置功能。/ping、/ask、/pend 是 CCB 提供的自定义命令。

为什么需要多AI协作？

单个 AI 模型有局限：

Claude Opus  → 推理最强，但贵、慢
Claude Sonnet → 平衡，日常首选
Codex        → 代码执行能力强
Gemini       → 长上下文、多模态

多AI协作的核心思路：让高成本模型负责决策，让执行型模型负责落地。

成本对比

模式	Claude Token 消耗	总成本	适用场景
纯 Claude	100%	高	简单任务
Claude + Codex	30-40%	中	前后端分离
Claude + Codex + Gemini	10-30%	低	大型项目

Claude 的 Token 消耗可降低 70-90%，因为重执行任务交给了成本更低的模型。

架构概览

Claude（管理者）
  ├── 分析需求，制定计划
  ├── /ask codex "后端任务..."  → Codex 执行
  ├── /ask gemini "前端任务..." → Gemini 执行
  ├── /pend codex → 回收结果
  ├── /pend gemini → 回收结果
  └── 交叉审计 + 最终验收

角色分工

角色	模型	职责	擅长
管理者	Claude	规划、审查、验收	推理、决策、质量把控
后端执行	Codex	实现、测试	代码生成、命令执行
前端执行	Gemini	实现、联调	长上下文、多模态理解

核心命令

# 连通检查
/ping codex
/ping gemini

# 委托任务
/ask codex "实现用户登录后端，输出 changedFiles/diffSummary"
/ask gemini "完成前端登录页面，输出 changedFiles/diffSummary"

# 回收结果
/pend codex
/pend gemini

命令详解

命令	作用	返回
/ping <provider>	检查连通性	在线/离线状态
/ask <provider> "..."	异步委托任务	任务 ID
/pend <provider>	查看最新结果	执行结果

完整协作流程

Step 1：连通检查

/ping codex
# → codex: online ✓

/ping gemini
# → gemini: online ✓

Step 2：需求分析与任务拆分

# Claude 分析需求
> 我需要实现一个用户注册功能，包含：
> - 后端：注册 API、邮箱验证、密码加密
> - 前端：注册表单、表单验证、成功页面
> - 数据库：users 表 migration
>
> 请拆分任务并分配给 Codex 和 Gemini

# Claude 输出任务拆分：
# Codex 任务：后端 API + 数据库 migration + 单元测试
# Gemini 任务：前端页面 + 表单验证 + E2E 测试

Step 3：委托执行

/ask codex "实现用户注册后端：
1. POST /api/auth/register 接口
2. 密码用 bcrypt 加密
3. 邮箱唯一性检查
4. users 表 migration
5. 单元测试
输出格式：changedFiles/diffSummary/testResults"

/ask gemini "实现用户注册前端：
1. 注册表单组件（邮箱、密码、确认密码）
2. 客户端表单验证
3. 调用 POST /api/auth/register
4. 成功/失败提示
输出格式：changedFiles/diffSummary"

Step 4：回收结果

# 等待执行完成后回收
/pend codex
# → 后端实现完成，5 个文件修改，测试全部通过

/pend gemini
# → 前端实现完成，3 个文件修改

Step 5：交叉审计

# 让 Codex 审查 Gemini 的前端代码
/ask codex "审查前端注册组件的代码质量和安全性"

# 让 Gemini 审查 Codex 的后端代码
/ask gemini "审查后端注册 API 的接口设计和错误处理"

Step 6：最终验收

# Claude 综合所有结果
> 汇总 Codex 和 Gemini 的实现结果和交叉审计意见，
> 做最终验收。检查：
> 1. 前后端接口是否对齐
> 2. 是否有安全风险
> 3. 测试是否充分

实战案例

案例 1：全栈功能开发

# Claude 规划
> 需求：实现商品搜索功能，支持关键词搜索和筛选

# 分配任务
/ask codex "实现搜索后端：
- GET /api/products/search?q=xxx&category=xxx
- 支持分页
- 用 Elasticsearch 或数据库 LIKE 查询
- 性能要求：200ms 内返回"

/ask gemini "实现搜索前端：
- 搜索框组件（支持防抖）
- 筛选面板（分类、价格区间）
- 搜索结果列表（支持无限滚动）
- 加载状态和空结果提示"

# 回收 + 验收
/pend codex
/pend gemini
> 检查前后端接口是否对齐，合并代码

案例 2：大型重构

# Claude 规划重构方案
> 把项目从 REST API 迁移到 GraphQL

# 分阶段执行
/ask codex "Phase 1：搭建 GraphQL schema 和 resolver
- 定义 User、Product、Order 类型
- 实现基本的 Query 和 Mutation
- 保留原有 REST API（双轨运行）"

/ask gemini "Phase 1：前端适配 GraphQL
- 安装 Apollo Client
- 把 fetch 调用改为 GraphQL query
- 先改首页和商品列表页"

# Phase 2...

案例 3：Bug 修复 + 回归测试

# Claude 定位问题
> 用户反馈：登录后偶尔会被踢出

# 分配修复和测试
/ask codex "修复 token 刷新逻辑：
- 检查 src/auth/token.ts 的刷新时机
- 修复竞态条件
- 添加重试机制
- 写回归测试"

/ask gemini "验证修复效果：
- 模拟高并发登录场景
- 检查 token 过期边界情况
- 验证前端 token 刷新拦截器"

降级策略

必须有降级方案，不能因为某个模型不可用就卡住：

模型不可用

# Gemini 不可用时，Codex 接管前端任务
/ask codex "Gemini 不可用，请同时完成前后端任务"

# Codex 不可用时，Claude 直接执行
> Codex 离线，我来直接实现后端逻辑

结论冲突

# Codex 说"用方案 A"，Gemini 说"用方案 B"
# 以测试结果和验收标准裁决

> Codex 和 Gemini 对缓存策略有分歧。
> 请分别用两种方案跑基准测试，
> 以 p99 延迟和内存占用为标准选择。

超时处理

# 设置合理的等待时间
# 如果 5 分钟没有结果，降级为单模型执行

> Codex 执行超时，改为 Claude 直接实现

环境搭建（从零开始）

以下是完整的搭建步骤，按顺序执行即可。

Step 0：Windows 用户先装 WSL

tmux 和 CCB 在 Linux 环境下兼容性最好，Windows 用户建议先装 WSL：

# PowerShell（管理员模式）
wsl --install

# 安装完成后重启电脑，重启后自动弹出 Ubuntu 终端，之后就按照linux安装方式
# 设置用户名和密码，后续所有操作都在 WSL 终端中执行

macOS / Linux 用户跳过此步。

Step 1：验证三件套

确保 Claude Code、Codex CLI、Gemini CLI 都已安装：

# 安装（如果还没装）
npm install -g @anthropic-ai/claude-code
npm install -g @openai/codex
npm install -g @google/gemini-cli

# 验证——三个都要有版本号输出
claude --version
codex --version
gemini --version

任何一个报错的，先装好再继续。

Step 2：安装 tmux

CCB 依赖终端复用器 tmux 实现多模型之间的通信，必装：

# macOS
brew install tmux

# Ubuntu / Debian / WSL
sudo apt update && sudo apt install -y tmux

# CentOS / RHEL
sudo yum install -y tmux

# 验证
tmux -V

Step 3：编写 CLAUDE.md

在 ~/.claude/CLAUDE.md 写好协作规范，Claude 启动时自动读取。以下是完整模板：

# Claude Code 核心规范

## 工作模式：Superpowers + AI 协作

### 角色分工

**Claude（我）——架构师 / 项目经理**：
- 需求分析、架构设计、任务拆分
- 使用 Superpowers 进行规划、审查、调试
- 代码审核、最终验收、Git 提交管理
- **绝对不亲自编写代码**，所有编码任务必须委派给 Codex 或 Gemini

**Codex——后端开发**：
- 服务端代码、API、数据库、Migration
- 单元测试、集成测试
- 通过 `/ask codex "..."` 调用

**Gemini——前端开发**：
- 前端组件、页面、样式、交互逻辑
- 代码审查、安全审计
- 通过 `/ask gemini "..."` 调用

### 降级机制

当某个 AI 提供者不可用时，按以下规则降级：

Codex 不可用 → Gemini 接管后端任务
Gemini 不可用 → Codex 接管前端任务
两者都不可用 → 暂停编码，等待恢复（Claude 不代写代码）

降级时在任务描述中注明"降级接管"，便于后续追溯。

### 协作方式

**使用 Superpowers skills 进行**：
- 规划：superpowers:writing-plans
- 执行：superpowers:executing-plans
- 审查：superpowers:requesting-code-review
- 调试：superpowers:systematic-debugging
- 完成：superpowers:finishing-a-development-branch

**调用 AI 提供者执行代码任务**：
# 指派 Codex 实现后端
/ask codex "实现 XXX 后端功能，涉及文件：..."

# 指派 Gemini 实现前端
/ask gemini "实现 XXX 前端功能，涉及文件：..."

# 查看执行结果
/pend codex
/pend gemini

---

## Linus 三问（决策前必问）

1. **这是现实问题还是想象问题？** → 拒绝过度设计
2. **有没有更简单的做法？** → 始终寻找最简方案
3. **会破坏什么？** → 向后兼容是铁律

---

## Git 规范

- 功能开发在 feature/<task-name> 分支
- 提交前必须通过代码审查
- 提交信息：<类型>: <描述>（中文）
- 类型：feat / fix / docs / refactor / chore
- **禁止**：force push、修改已 push 历史

把规则写好，Claude 就会严格按照规则执行，不需要每次手动告诉它。

Step 4：安装 Superpowers 插件

启动 Claude Code 后，在 REPL 中执行：

/plugin marketplace add https://github.com/obra/superpowers-marketplace                                                                    
/plugin install superpowers@superpowers-marketplace

出现 successfully 就证明安装成功。安装完成后 Claude 就具备了标准化的规划、审查、调试能力。

Step 5：安装 CCB（Claude Code Bridge）

CCB 是让三个 AI 互相通信的桥接器。社区开源项目，感谢 bfly123 作者的贡献。

# 确认 Python 版本（需要 3.10+）
python3 --version

# 克隆 CCB 项目
git clone https://github.com/bfly123/claude_code_bridge.git

# 进入项目目录并安装
claude_code_bridge
bash install.sh install

# Windows PowerShell 用户（非 WSL）：
# powershell -ExecutionPolicy Bypass -File install.ps1

安装过程中，CCB 会自动配置通信组件，并在 ~/.claude/CLAUDE.md 里注册 /ask、/pend、/ping 命令。

Step 6：启动协作系统

#执行tmux新建tmux窗口
tmux new -s ccb
# 启动多模型协作（自动创建 tmux 窗格）
ccb codex gemini claude

启动后会自动创建多个 tmux 窗格，分别运行 Claude、Codex、Gemini。

工具链层级关系

理解三层工具链的先后关系：

第一层：CLAUDE.md（规则层）
  → Claude 启动时自动读取，定义协作规范和角色分工

第二层：Superpowers（能力层）
  → 提供标准化的规划、审查、调试流程

第三层：CCB（通信层）
  → 让 Claude 通过 /ask、/pend、/ping 指挥 Codex 和 Gemini

搭建步骤速查

1. [Windows] 安装 WSL → wsl --install
2. 验证三件套 → claude/codex/gemini --version
3. 安装 tmux → apt install tmux / brew install tmux
4. 编写 ~/.claude/CLAUDE.md → 定义协作规则
5. 安装 Superpowers 
6. 安装 CCB → git clone + bash install.sh install
7. 启动协作 → ccb codex gemini claude

最佳实践

1. 任务拆分原则

 好的拆分：
- 前端 vs 后端（天然隔离）
- 不同模块（用户模块 vs 订单模块）
- 实现 vs 测试（可并行）

不好的拆分：
- 同一个文件的不同部分（会冲突）
- 有强依赖的任务（必须串行）
- 需要频繁沟通的任务（协调成本高）

2. 统一输出格式

所有模型的输出必须统一，否则无法整合：

changedFiles    - 修改的文件列表
diffSummary     - 变更摘要
testResults     - 测试结果
risks           - 风险点

3. 交叉审计

让模型互相审查，比自己审查自己更有效：

Codex 写的代码 → Gemini 审查
Gemini 写的代码 → Codex 审查
最终结果 → Claude 验收