主题
使用示例：多代理协作编写单元测试
本文档通过一个实际场景，演示如何使用 Vibe Kanban 编排多个 AI 编程代理，高效地为项目编写单元测试。
场景背景
假设你有一个 Node.js API 项目，包含以下模块：
my-api-project/
├── src/
│ ├── controllers/
│ │ ├── userController.ts
│ │ ├── orderController.ts
│ │ └── productController.ts
│ ├── services/
│ │ ├── userService.ts
│ │ ├── orderService.ts
│ │ └── productService.ts
│ ├── utils/
│ │ ├── validator.ts
│ │ ├── formatter.ts
│ │ └── crypto.ts
│ └── models/
│ ├── User.ts
│ ├── Order.ts
│ └── Product.ts
├── tests/ # 当前为空，需要编写测试
├── package.json
└── tsconfig.json目标：为整个项目编写全面的单元测试，目标覆盖率 80%+。
挑战：
- 模块众多，单人编写耗时
- 不同模块可能需要不同的测试策略
- 需要保持测试风格一致性
安全约束：
- ⛔ 禁止修改
src/目录下的任何源代码 - ✅ 只允许在
tests/目录下创建和修改测试文件 - ✅ 只允许修改测试相关配置文件（jest.config.js、package.json 的 test 脚本）
- ⛔ 如发现源代码 bug，只记录不修复
解决方案：使用 Vibe Kanban 编排多个 AI 代理并行工作。
工作流设计
整体流程图
┌─────────────────────────────────────────────────────────────────────┐
│ Vibe Kanban 看板 │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ 阶段 1: 分析 阶段 2: 规划 阶段 3: 编写 │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ 代码结构 │──────▶│ 测试策略 │──────▶│ 并行编写 │ │
│ │ 分析 │ │ 设计 │ │ 测试 │ │
│ └──────────┘ └──────────┘ └────┬─────┘ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ Claude Code Claude Code ┌─────────────┐ │
│ (Plan 模式) (Plan 模式) │ Claude Code │ │
│ │ Gemini CLI │──┐ │
│ │ Codex CLI │ │ 并行 │
│ └─────────────┘ │ │
│ ▼ │
│ 阶段 4: 审查 阶段 5: 修复 │
│ ┌──────────┐ ┌──────────┐ │
│ │ 测试质量 │──────▶│ 运行测试 │ │
│ │ 审查 │ │ 修复失败 │ │
│ └──────────┘ └──────────┘ │
│ │ │ │
│ ▼ ▼ │
│ Claude Code Claude Code │
│ (审查专家) (Build 模式) │
│ │
└─────────────────────────────────────────────────────────────────────┘代理分工策略
| 阶段 | 任务 | 推荐代理 | 执行模式 | 理由 |
|---|---|---|---|---|
| 1. 分析 | 代码结构分析 | Claude Code | Plan | 强大的代码理解能力 |
| 2. 规划 | 测试策略设计 | Claude Code | Plan | 长上下文推理能力 |
| 3. 编写 | Services 层测试 | Claude Code | Build | 复杂业务逻辑 |
| 3. 编写 | Controllers 层测试 | Gemini CLI | Build | HTTP 测试模式 |
| 3. 编写 | Utils 工具测试 | Codex CLI | Build | 纯函数测试，快速 |
| 4. 审查 | 测试质量审查 | Claude Code | Review | 全面审查能力 |
| 5. 修复 | 运行测试并修复 | Claude Code | Build | 调试和修复能力 |
详细操作步骤
步骤 1：启动 Vibe Kanban
bash
# 确保已认证 AI 代理
claude auth login
gemini auth login
# 启动 Vibe Kanban
npx vibe-kanban步骤 2：创建测试项目看板
在 Vibe Kanban 界面中：
- 点击 "New Board" 创建新看板
- 命名为
Unit Testing - my-api-project - 创建以下列（Columns）：
- 待分析 (To Analyze)
- 规划中 (Planning)
- 编写中 (In Progress)
- 审查中 (In Review)
- 已完成 (Done)
步骤 3：配置 MCP 服务
在 Settings → MCP Configuration 中配置：
json
{
"mcp": {
"servers": {
"filesystem": {
"type": "local",
"command": ["mcp-server-filesystem"],
"args": ["--root", "/path/to/my-api-project"],
"enabled": true,
"permissions": {
"read": ["src/**/*", "tests/**/*", "package.json", "tsconfig.json"],
"write": ["tests/**/*", "jest.config.js"],
"deny_write": ["src/**/*"]
}
},
"jest-runner": {
"type": "local",
"command": ["mcp-server-shell"],
"args": ["--allowed-commands", "npm test,npx jest"],
"enabled": true
}
}
},
"constraints": {
"protected_paths": ["src/**/*"],
"writable_paths": ["tests/**/*", "*.config.js"],
"on_violation": "block_and_warn"
}
}⚠️ 关键配置：
deny_write: ["src/**/*"]确保 AI 代理无法修改源代码目录。
步骤 4：创建分析任务
创建第一个任务卡片：
任务：代码结构分析
markdown
## 任务描述
分析项目代码结构，识别所有需要测试的模块和函数。
## 交付物
1. 模块依赖关系图
2. 需要测试的函数清单
3. 每个模块的复杂度评估
4. 建议的测试优先级
## 提示词
请分析这个 Node.js 项目的代码结构：
1. 列出所有导出的函数和类
2. 识别模块间的依赖关系
3. 标注哪些函数是纯函数，哪些有副作用
4. 评估每个模块的测试复杂度（高/中/低）指派代理：Claude Code (Plan 模式)
步骤 5：创建测试策略任务
基于分析结果，创建策略规划任务：
任务：测试策略设计
markdown
## 任务描述
基于代码分析结果，设计完整的测试策略。
## 输入
- 代码结构分析报告（来自上一任务）
## 交付物
1. 测试框架选择（Jest/Vitest/Mocha）
2. 每个模块的测试方法建议
3. Mock 策略（哪些依赖需要 mock）
4. 测试用例设计模板
5. 预期的覆盖率目标
## ⚠️ 约束条件
- 禁止修改 src/ 目录下的任何文件
- 只能在 tests/ 目录下创建文件
- 只能读取源代码，不能编辑源代码
- 如发现源代码问题，记录到报告中但不修改
## 提示词
基于代码分析结果，为项目设计测试策略：
1. 推荐使用 Jest 作为测试框架
2. 为 Services 层设计集成测试策略
3. 为 Controllers 层设计 HTTP 请求测试策略
4. 为 Utils 层设计单元测试策略
5. 定义 Mock 边界（数据库、外部 API）
重要：你只能设计测试策略，不能修改任何源代码。指派代理：Claude Code (Plan 模式) 依赖：等待"代码结构分析"完成
步骤 6：创建并行编写任务
创建多个并行执行的测试编写任务：
任务 3.1：Services 层测试
markdown
## 任务描述
为 services/ 目录下的所有服务编写单元测试。
## 范围
- src/services/userService.ts
- src/services/orderService.ts
- src/services/productService.ts
## 测试要求
- 使用 Jest 框架
- Mock 数据库操作
- 覆盖正常流程和边界情况
- 覆盖率目标 85%
## ⚠️ 约束条件
- ⛔ 禁止修改 src/ 目录下的任何文件
- ✅ 只能在 tests/services/ 目录下创建测试文件
- ⛔ 即使测试失败也不能修改源代码
- 📝 如发现源代码 bug，记录到 BUG_REPORT.md
## 提示词
请为 userService.ts 编写单元测试：
1. 测试所有公开方法
2. Mock 数据库调用（使用 jest.mock）
3. 测试成功和失败场景
4. 测试边界条件（空输入、无效 ID 等）
5. 添加清晰的测试描述
重要约束：你只能创建测试文件，绝对不能修改 src/ 下的源代码。指派代理：Claude Code (Build 模式) 执行模式：可并行
任务 3.2：Controllers 层测试
markdown
## 任务描述
为 controllers/ 目录下的所有控制器编写 HTTP 测试。
## 范围
- src/controllers/userController.ts
- src/controllers/orderController.ts
- src/controllers/productController.ts
## 测试要求
- 使用 supertest 进行 HTTP 测试
- 测试所有 REST 端点
- 验证响应状态码和数据结构
- 测试认证和授权场景
## ⚠️ 约束条件
- ⛔ 禁止修改 src/ 目录下的任何文件
- ✅ 只能在 tests/controllers/ 目录下创建测试文件
- ⛔ 即使测试失败也不能修改源代码
- 📝 如发现源代码 bug，记录到 BUG_REPORT.md
## 提示词
请为 userController.ts 编写 HTTP 测试：
1. 使用 supertest 库
2. 测试 GET/POST/PUT/DELETE 端点
3. 验证请求验证逻辑
4. 测试认证失败场景
5. Mock service 层调用
重要约束：你只能创建测试文件，绝对不能修改 src/ 下的源代码。指派代理：Gemini CLI (Build 模式) 执行模式：可并行
任务 3.3：Utils 工具测试
markdown
## 任务描述
为 utils/ 目录下的工具函数编写单元测试。
## 范围
- src/utils/validator.ts
- src/utils/formatter.ts
- src/utils/crypto.ts
## 测试要求
- 纯函数测试，无需 mock
- 使用参数化测试覆盖多种输入
- 覆盖率目标 95%
## ⚠️ 约束条件
- ⛔ 禁止修改 src/ 目录下的任何文件
- ✅ 只能在 tests/utils/ 目录下创建测试文件
- ⛔ 即使测试失败也不能修改源代码
- 📝 如发现源代码 bug，记录到 BUG_REPORT.md
## 提示词
请为 validator.ts 编写单元测试：
1. 测试所有验证函数
2. 使用 test.each 进行参数化测试
3. 覆盖有效和无效输入
4. 测试边界值
5. 确保 100% 分支覆盖
重要约束：你只能创建测试文件，绝对不能修改 src/ 下的源代码。指派代理：Codex CLI (Build 模式) 执行模式：可并行
步骤 7：配置并行执行
在 Vibe Kanban 中设置并行执行：
- 选择任务 3.1、3.2、3.3
- 点击 "Configure Execution"
- 选择 "Parallel" 模式
- 设置 "Start When"：任务 2 完成后
┌─────────────────────────────────────────────────────────┐
│ 并行执行配置 │
├─────────────────────────────────────────────────────────┤
│ │
│ 任务 2: 测试策略设计 │
│ │ │
│ ▼ │
│ ┌───────┴───────┬───────────────┐ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ ┌─────┐ ┌─────┐ ┌─────┐ │
│ │3.1 │ │3.2 │ │3.3 │ 并行执行 │
│ │Svc │ │Ctrl │ │Util │ │
│ └──┬──┘ └──┬──┘ └──┬──┘ │
│ │ │ │ │
│ └─────────────┼─────────────┘ │
│ ▼ │
│ 任务 4: 测试审查 │
│ (等待所有并行任务完成) │
│ │
└─────────────────────────────────────────────────────────┘步骤 8：创建审查任务
任务：测试质量审查
markdown
## 任务描述
审查所有编写的测试代码，确保质量和一致性。
## 审查清单
- [ ] 测试命名规范一致
- [ ] 测试覆盖了关键业务逻辑
- [ ] Mock 使用正确
- [ ] 没有测试实现细节
- [ ] 测试独立性（无相互依赖）
- [ ] 错误场景覆盖充分
## 提示词
请审查所有测试文件：
1. 检查测试是否遵循 AAA 模式（Arrange-Act-Assert）
2. 验证 mock 是否正确重置
3. 检查是否有重复的测试逻辑
4. 确保测试描述清晰准确
5. 提出改进建议指派代理：Claude Code (Review 模式) 依赖：等待所有编写任务完成
步骤 9：创建修复任务
任务：运行测试并修复失败
markdown
## 任务描述
运行所有测试，分析并修复失败的测试用例。
## 执行步骤
1. 运行 npm test
2. 分析失败原因
3. 修复失败的测试
4. 重新运行直到全部通过
5. 生成覆盖率报告
## 提示词
请执行以下操作：
1. 运行 npx jest --coverage
2. 分析失败的测试用例
3. 判断是测试代码问题还是源代码 bug
4. 修复测试代码问题
5. 如发现源代码 bug，记录但不修改
6. 确保覆盖率达到 80%指派代理：Claude Code (Build 模式) 依赖：等待审查任务完成
实时监控与切换
任务状态监控
在 Vibe Kanban 界面中，你可以实时看到：
┌────────────────────────────────────────────────────────────────┐
│ Unit Testing - my-api-project │
├──────────┬──────────┬──────────┬──────────┬──────────┬────────┤
│ 待分析 │ 规划中 │ 编写中 │ 审查中 │ 已完成 │ 阻塞 │
├──────────┼──────────┼──────────┼──────────┼──────────┼────────┤
│ │ │ ┌──────┐ │ │ ┌──────┐ │ │
│ │ │ │3.1 │ │ │ │ 1 │ │ │
│ │ │ │Svc ⏳│ │ │ │分析 ✓│ │ │
│ │ │ │45% │ │ │ └──────┘ │ │
│ │ │ └──────┘ │ │ ┌──────┐ │ │
│ │ │ ┌──────┐ │ │ │ 2 │ │ │
│ │ │ │3.2 │ │ │ │策略 ✓│ │ │
│ │ │ │Ctrl⏳│ │ │ └──────┘ │ │
│ │ │ │30% │ │ │ │ │
│ │ │ └──────┘ │ │ │ │
│ │ │ ┌──────┐ │ │ │ │
│ │ │ │3.3 │ │ │ │ │
│ │ │ │Util✓ │ │ │ │ │
│ │ │ │Done │ │ │ │ │
│ │ │ └──────┘ │ │ │ │
└──────────┴──────────┴──────────┴──────────┴──────────┴────────┘
📊 进度：60% | 代理活跃：2 | 等待中：1 | 已完成：3代理切换示例
假设 Gemini CLI 在编写 Controllers 测试时遇到困难，你可以：
- 点击任务 3.2 卡片
- 选择 "Switch Agent"
- 选择 Claude Code 接管
- 上下文自动传递
┌─────────────────────────────────────────────┐
│ 切换代理 │
├─────────────────────────────────────────────┤
│ │
│ 当前代理：Gemini CLI │
│ 任务进度：30% │
│ 遇到问题：Mock 配置复杂 │
│ │
│ 切换到： │
│ ○ Claude Code (推荐 - 擅长复杂场景) │
│ ○ Codex CLI │
│ ○ Amp │
│ │
│ [保留上下文] ✓ │
│ │
│ [取消] [确认切换] │
│ │
└─────────────────────────────────────────────┘完整工作流配置文件
你可以将以下配置保存为模板，复用于其他项目：
yaml
# vibe-kanban-workflow.yaml
name: "Unit Testing Workflow"
description: "Multi-agent workflow for comprehensive unit testing"
# 全局约束配置
constraints:
protected_paths:
- "src/**/*" # 禁止修改源代码
- "package-lock.json" # 禁止修改锁文件
writable_paths:
- "tests/**/*" # 允许写入测试目录
- "jest.config.js" # 允许修改测试配置
- "BUG_REPORT.md" # 允许记录 bug
on_violation: "block_and_warn"
violation_message: "⛔ 禁止修改源代码！只能在 tests/ 目录下创建测试文件。"
stages:
- name: analyze
description: "代码结构分析"
agent: claude-code
mode: plan
timeout: 10m
constraints:
read_only: true # 分析阶段只读
- name: strategy
description: "测试策略设计"
agent: claude-code
mode: plan
depends_on: [analyze]
timeout: 15m
constraints:
read_only: true # 策略阶段只读
- name: write-tests
description: "并行编写测试"
parallel: true
depends_on: [strategy]
tasks:
- name: services
agent: claude-code
mode: build
scope: "src/services/**/*.ts"
output_dir: "tests/services/"
timeout: 30m
- name: controllers
agent: gemini-cli
mode: build
scope: "src/controllers/**/*.ts"
output_dir: "tests/controllers/"
timeout: 30m
fallback_agent: claude-code
- name: utils
agent: codex-cli
mode: build
scope: "src/utils/**/*.ts"
output_dir: "tests/utils/"
timeout: 20m
- name: review
description: "测试质量审查"
agent: claude-code
mode: review
depends_on: [write-tests]
timeout: 20m
constraints:
read_only: true # 审查阶段只读
- name: fix
description: "运行并修复测试"
agent: claude-code
mode: build
depends_on: [review]
timeout: 30m
constraints:
writable_paths: ["tests/**/*"] # 只能修复测试代码
commands:
- "npm test"
- "npx jest --coverage"
success_criteria:
coverage: 80
all_tests_pass: true
source_code_unchanged: true # 验证源代码未被修改最佳实践
1. 代码保护策略（重要）
在使用 AI 代理编写测试时，必须确保源代码不被意外修改：
yaml
# 三层防护机制
protection:
# 层级 1：MCP 文件系统权限
mcp_permissions:
deny_write: ["src/**/*"]
# 层级 2：工作流约束
workflow_constraints:
protected_paths: ["src/**/*"]
on_violation: "block_and_warn"
# 层级 3：Git 预检查
git_hooks:
pre_commit: "git diff --name-only | grep -q '^src/' && exit 1"为什么这很重要？
- AI 代理可能会"修复"它认为有问题的代码
- 测试失败时，代理可能倾向于修改源代码而非测试代码
- 防止意外引入回归问题
验证源代码未被修改：
bash
# 在工作流结束时运行
git diff --name-only src/ | wc -l
# 如果输出不为 0，说明源代码被修改了2. 代理选择策略
| 测试类型 | 推荐代理 | 原因 |
|---|---|---|
| 复杂业务逻辑 | Claude Code | 长上下文理解，复杂推理 |
| HTTP/API 测试 | Gemini CLI | 多模态能力，可理解 API 文档 |
| 纯函数测试 | Codex CLI | 快速生成，擅长算法 |
| 测试审查 | Claude Code | 全面分析能力 |
2. 并行度控制
推荐并行数 = min(模块数, 可用代理数, 3)- 不建议超过 3 个代理并行，避免上下文冲突
- 确保每个代理有独立的文件范围
3. 上下文共享
使用 MCP 服务共享关键上下文：
json
{
"shared_context": {
"test_conventions": "tests/conventions.md",
"mock_templates": "tests/mocks/templates/",
"coverage_config": "jest.config.js"
}
}4. 失败处理策略
yaml
failure_handling:
retry_count: 2
fallback_agent: claude-code
on_failure:
- notify: true
- pause_dependents: true
- create_issue: true5. 覆盖率门槛
yaml
coverage_gates:
statements: 80
branches: 75
functions: 85
lines: 80
fail_on_decrease: true预期成果
使用 Vibe Kanban 多代理协作编写测试后，你将获得：
| 指标 | 传统方式 | Vibe Kanban |
|---|---|---|
| 完成时间 | 8-12 小时 | 2-3 小时 |
| 覆盖率 | 60-70% | 80-90% |
| 测试风格一致性 | 中等 | 高 |
| 边界情况覆盖 | 容易遗漏 | 全面 |
最终测试结构
tests/
├── services/
│ ├── userService.test.ts # Claude Code
│ ├── orderService.test.ts # Claude Code
│ └── productService.test.ts # Claude Code
├── controllers/
│ ├── userController.test.ts # Gemini CLI
│ ├── orderController.test.ts # Gemini CLI
│ └── productController.test.ts# Gemini CLI
├── utils/
│ ├── validator.test.ts # Codex CLI
│ ├── formatter.test.ts # Codex CLI
│ └── crypto.test.ts # Codex CLI
├── mocks/
│ ├── database.ts
│ └── services.ts
└── setup.ts