# ColaFlow Multi-Agent Development System

## 概述

ColaFlow 项目采用**多 Agent 协作系统**来进行开发，该系统由 1 个主协调器和 9 个专业 sub agent 组成，每个 agent 专注于特定领域，确保高质量的交付成果。

## 系统架构

```
                    ┌─────────────────────┐
                    │   主协调器           │
                    │   (CLAUDE.md)       │
                    │                     │
                    │ - 理解需求          │
                    │ - 路由任务          │
                    │ - 整合成果          │
                    └──────────┬──────────┘
                               │
        ┌──────────────────────┼──────────────────────┐
        │                      │                      │
    ┌───▼───┐            ┌─────▼─────┐         ┌────▼────┐
    │  PM   │            │ Architect │         │ Backend │
    └───────┘            └───────────┘         └─────────┘
        │                      │                      │
    ┌───▼───┐            ┌─────▼─────┐         ┌────▼────┐
    │Frontend│           │    AI     │         │   QA    │
    └───────┘            └───────────┘         └─────────┘
        │
    ┌───▼───┐
    │ UX/UI │
    └───────┘
```

## 文件结构

```
ColaFlow/
├── CLAUDE.md                      # 主协调器配置（项目根目录）
├── product.md                     # 项目需求文档
├── AGENT_SYSTEM.md               # 本文档
│
└── .claude/                       # Agent 配置目录
    ├── README.md                  # Agent 系统说明
    ├── USAGE_EXAMPLES.md          # 使用示例
    │
    ├── agents/                    # Sub Agent 配置
    │   ├── researcher.md          # 技术研究员
    │   ├── product-manager.md     # 产品经理
    │   ├── architect.md           # 架构师
    │   ├── backend.md             # 后端工程师
    │   ├── frontend.md            # 前端工程师
    │   ├── ai.md                  # AI 工程师
    │   ├── qa.md                  # QA 工程师
    │   ├── ux-ui.md               # UX/UI 设计师
    │   └── progress-recorder.md   # 进度记录员
    │
    └── skills/                    # 质量保证技能
        └── code-reviewer.md       # 代码审查
```

## Agent 角色说明

### 主协调器（Main Coordinator）
**文件**: `CLAUDE.md`（项目根目录）

**职责**:
- ✅ 理解用户需求并分析
- ✅ 识别涉及的领域
- ✅ 调用相应的专业 agent
- ✅ 整合各 agent 的工作成果
- ✅ 向用户汇报结果

**不做**:
- ❌ 直接编写代码
- ❌ 直接设计架构
- ❌ 直接做具体技术实现

### Sub Agents（专业代理）

| Agent | 文件 | 核心能力 |
|-------|------|----------|
| **技术研究员** | `.claude/agents/researcher.md` | API 文档查找、最佳实践研究、技术调研、问题方案研究 |
| **产品经理** | `.claude/agents/product-manager.md` | PRD 编写、需求管理、项目规划、进度跟踪 |
| **架构师** | `.claude/agents/architect.md` | 系统架构设计、技术选型、可扩展性保障 |
| **后端工程师** | `.claude/agents/backend.md` | API 开发、数据库设计、MCP 集成、后端代码 |
| **前端工程师** | `.claude/agents/frontend.md` | UI 组件、状态管理、用户交互、前端代码 |
| **AI 工程师** | `.claude/agents/ai.md` | Prompt 工程、模型集成、AI 安全机制 |
| **QA 工程师** | `.claude/agents/qa.md` | 测试策略、测试用例、质量保证、自动化测试 |
| **UX/UI 设计师** | `.claude/agents/ux-ui.md` | 用户体验设计、界面设计、设计系统 |
| **进度记录员** | `.claude/agents/progress-recorder.md` | 项目记忆管理、进度跟踪、信息归档、变更合并 |

## 使用方法

### 基本流程

1. **提出需求** → 直接向主协调器提出需求
2. **主协调器分析** → 识别需要哪些 agent 参与
3. **调用 Sub Agents** → 使用 Task tool 调用专业 agent
4. **整合成果** → 主协调器整合各 agent 的输出
5. **返回结果** → 向您汇报完整的解决方案

### 示例 1：实现新功能

**您的请求**:
```
实现 AI 自动生成任务的功能
```

**系统执行流程**:
```
主协调器分析：这是一个复杂功能，需要多个领域协作

1. 调用 architect agent
   → 设计 MCP Server 架构和安全机制

2. 调用 ai agent
   → 设计 Prompt 模板
   → 规划模型集成方案

3. 调用 backend agent
   → 实现 API 端点
   → 实现 Diff Preview 机制

4. 调用 frontend agent
   → 开发 AI 控制台界面
   → 实现审批流程 UI

5. 调用 qa agent
   → 设计测试用例
   → 执行集成测试

6. 主协调器整合
   → 汇总所有成果
   → 返回完整实现方案
```

### 示例 2：修复 Bug

**您的请求**:
```
看板页面加载很慢
```

**系统执行流程**:
```
主协调器分析：这是性能问题

1. 调用 qa agent
   → 性能测试和问题定位
   → 发现：渲染 100+ 任务时卡顿

2. 根据诊断结果，调用 frontend agent
   → 实现虚拟滚动优化
   → 使用 React.memo 减少重渲染

3. 再次调用 qa agent
   → 验证性能改善
   → 确认问题解决

4. 主协调器整合
   → 汇报问题原因、解决方案和验证结果
```

## 核心优势

### 1. 专业分工
每个 agent 专注于自己的领域，确保专业性和质量

### 2. 高效协作
主协调器智能路由，避免重复工作

### 3. 质量保证
- 产品经理确保需求清晰
- 架构师确保设计合理
- 工程师遵循最佳实践
- QA 确保质量达标
- UX/UI 确保用户体验

### 4. 并行执行
独立任务可以并行处理，提高效率

### 5. 可追溯性
每个决策都有明确的负责 agent，便于追溯

## 最佳实践

### ✅ 推荐做法

1. **明确需求**: 清晰描述您的需求和期望
   ```
   好：实现看板的拖拽功能，支持 100+ 任务流畅操作
   差：让看板更好用
   ```

2. **提供上下文**: 引用相关文档或代码
   ```
   好：根据 product.md 中的 M2 规划，实现 MCP Server
   差：做 MCP
   ```

3. **信任系统**: 让主协调器决定调用哪些 agent
   ```
   好：实现用户登录功能
   差：用 backend agent 写登录 API
   ```

4. **迭代改进**: 根据反馈持续优化
   ```
   好：这个 API 设计不错，但能否增加限流功能？
   ```

### ❌ 避免做法

1. **不要直接调用 Sub Agent**
   - ❌ 不要说"backend agent 帮我写代码"
   - ✅ 应该说"实现这个功能"，让主协调器决定

2. **不要过于宽泛**
   - ❌ "把整个系统做出来"
   - ✅ "先实现 M1 的核心数据模型"

3. **不要跳过规划**
   - ❌ "直接写代码"
   - ✅ "先设计架构，然后实现"

## 特殊场景

### 场景 1：需要多个 Agent 并行工作

**请求**:
```
为 M2 阶段做准备工作
```

**系统响应**:
```
主协调器在单个消息中并行调用：
- product-manager: 创建 M2 项目计划
- architect: 设计 MCP Server 详细架构
- qa: 制定 M2 测试策略

所有 agent 同时工作，提高效率
```

### 场景 2：需要顺序执行

**请求**:
```
调查并修复登录 500 错误
```

**系统响应**:
```
顺序执行：
1. qa agent → 诊断问题（发现是数据库连接池耗尽）
2. backend agent → 修复问题（优化连接池配置）
3. qa agent → 验证修复（确认问题解决）
```

## 项目上下文

所有 agent 都可以访问：
- **product.md**: ColaFlow 完整项目计划
- **CLAUDE.md**: 主协调器指南
- **各 agent 配置**: 了解其他 agent 的能力

## 代码规范

### 后端代码规范
- 语言：TypeScript
- 框架：NestJS
- ORM：TypeORM 或 Prisma
- 验证：Zod
- 测试：Jest
- 覆盖率：80%+

### 前端代码规范
- 语言：TypeScript
- 框架：React 18+ 或 Vue 3
- 状态：Zustand 或 Pinia
- UI 库：Ant Design 或 Material-UI
- 测试：React Testing Library, Playwright
- 构建：Vite

### 质量标准
- P0/P1 Bug = 0
- 测试通过率 ≥ 95%
- 代码覆盖率 ≥ 80%
- API 响应时间 P95 < 500ms

## 快速开始

### 第一次使用

1. **阅读项目背景**
   ```
   查看 product.md 了解 ColaFlow 项目
   ```

2. **理解 Agent 系统**
   ```
   阅读 CLAUDE.md（主协调器）
   浏览 .claude/README.md（系统说明）
   ```

3. **查看示例**
   ```
   阅读 .claude/USAGE_EXAMPLES.md（使用示例）
   ```

4. **开始使用**
   ```
   直接提出需求，让主协调器为您协调工作
   ```

### 示例起步任务

**简单任务**:
```
生成"用户认证"功能的 PRD
```

**中等任务**:
```
设计并实现看板组件的拖拽功能
```

**复杂任务**:
```
实现 MCP Server 的完整功能，包括架构设计、代码实现和测试
```

## 获取帮助

### 文档资源
- **系统说明**: `.claude/README.md`
- **使用示例**: `.claude/USAGE_EXAMPLES.md`
- **主协调器**: `CLAUDE.md`
- **项目计划**: `product.md`
- **各 Agent 详情**: `.claude/agents/[agent-name].md`

### 常见问题

**Q: 我应该直接调用 sub agent 吗？**
A: 不，应该向主协调器提出需求，让它决定调用哪些 agent。

**Q: 如何让多个 agent 并行工作？**
A: 主协调器会自动判断哪些任务可以并行，您只需提出需求即可。

**Q: Agent 之间如何协作？**
A: 主协调器负责协调，agent 会建议需要哪些其他 agent 参与。

**Q: 如何确保代码质量？**
A: 每个 agent 都遵循严格的代码规范和质量标准，QA agent 会进行质量把关。

## 总结

ColaFlow 多 Agent 系统通过专业分工和智能协作，确保：
- ✅ 高质量的代码和设计
- ✅ 清晰的需求和架构
- ✅ 完善的测试覆盖
- ✅ 优秀的用户体验
- ✅ 高效的开发流程

开始使用时，只需向主协调器提出您的需求，系统会自动为您协调最合适的 agent 团队！

**准备好了吗？开始您的 ColaFlow 开发之旅吧！** 🚀