Project Init
🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Yaojia Wang
443
.claude/USAGE_EXAMPLES.md
Normal file
443
.claude/USAGE_EXAMPLES.md
Normal file
@@ -0,0 +1,443 @@
|
||||
# ColaFlow Agent System - Usage Examples
|
||||
|
||||
This document provides practical examples of how to use the ColaFlow multi-agent system.
|
||||
|
||||
## Table of Contents
|
||||
|
||||
1. [Simple Tasks](#simple-tasks)
|
||||
2. [Complex Features](#complex-features)
|
||||
3. [Parallel Execution](#parallel-execution)
|
||||
4. [Sequential Workflows](#sequential-workflows)
|
||||
5. [Code Generation](#code-generation)
|
||||
6. [Design and Planning](#design-and-planning)
|
||||
|
||||
---
|
||||
|
||||
## Simple Tasks
|
||||
|
||||
### Example 1: Generate a PRD
|
||||
|
||||
**Your Request**:
|
||||
```
|
||||
Generate a PRD for the "AI Task Auto-Creation" feature
|
||||
```
|
||||
|
||||
**What Happens**:
|
||||
```
|
||||
Main Coordinator → Calls product-manager agent
|
||||
|
||||
Sub Agent Response:
|
||||
- Analyzes the feature requirements
|
||||
- Generates complete PRD document with:
|
||||
- Background & Goals
|
||||
- Requirements
|
||||
- Acceptance Criteria
|
||||
- Timeline
|
||||
|
||||
Main Coordinator → Returns integrated PRD to you
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Example 2: Design System Architecture
|
||||
|
||||
**Your Request**:
|
||||
```
|
||||
Design the architecture for MCP Server integration
|
||||
```
|
||||
|
||||
**What Happens**:
|
||||
```
|
||||
Main Coordinator → Calls architect agent
|
||||
|
||||
Sub Agent Response:
|
||||
- Designs MCP Server architecture
|
||||
- Defines Resources and Tools
|
||||
- Plans security mechanisms (diff preview)
|
||||
- Recommends tech stack
|
||||
|
||||
Main Coordinator → Returns architecture design to you
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Complex Features
|
||||
|
||||
### Example 3: Implement Complete Feature
|
||||
|
||||
**Your Request**:
|
||||
```
|
||||
Implement the Kanban board drag-and-drop feature with the following requirements:
|
||||
- Users can drag tasks between columns
|
||||
- Status updates automatically
|
||||
- Optimistic UI updates with rollback on error
|
||||
- Works smoothly with 100+ tasks
|
||||
```
|
||||
|
||||
**What Happens**:
|
||||
```
|
||||
Main Coordinator analyzes and creates execution plan:
|
||||
|
||||
Step 1: Architecture (architect agent)
|
||||
→ Design component architecture
|
||||
→ Define state management approach
|
||||
→ Plan API contract
|
||||
|
||||
Step 2: Requirements (product-manager agent)
|
||||
→ Define acceptance criteria
|
||||
→ Specify edge cases
|
||||
→ Set performance requirements
|
||||
|
||||
Step 3: Backend (backend agent)
|
||||
→ Implement PATCH /api/issues/:id/status endpoint
|
||||
→ Add optimistic locking
|
||||
→ Write unit tests
|
||||
|
||||
Step 4: Frontend (frontend agent)
|
||||
→ Implement drag-and-drop with react-beautiful-dnd
|
||||
→ Add optimistic UI updates
|
||||
→ Handle error rollback
|
||||
→ Implement virtualization for performance
|
||||
|
||||
Step 5: Testing (qa agent)
|
||||
→ Write E2E tests for drag-and-drop
|
||||
→ Performance test with 100+ tasks
|
||||
→ Test error scenarios
|
||||
|
||||
Step 6: UX (ux-ui agent)
|
||||
→ Design drag feedback animations
|
||||
→ Define success/error states
|
||||
|
||||
Main Coordinator → Integrates all outputs and presents complete implementation
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Parallel Execution
|
||||
|
||||
### Example 4: Kickoff New Project Phase
|
||||
|
||||
**Your Request**:
|
||||
```
|
||||
We're starting M2 (MCP Server implementation). Prepare the team.
|
||||
```
|
||||
|
||||
**What Happens (Parallel Execution)**:
|
||||
```
|
||||
Main Coordinator calls multiple agents in PARALLEL:
|
||||
|
||||
┌─────────────────────────────────────────────────────┐
|
||||
│ Task 1: product-manager │
|
||||
│ → Create M2 project plan │
|
||||
│ → Define milestones and deliverables │
|
||||
│ │
|
||||
│ Task 2: architect │
|
||||
│ → Design detailed MCP Server architecture │
|
||||
│ → Define API specifications │
|
||||
│ │
|
||||
│ Task 3: backend │
|
||||
│ → Set up project structure for MCP Server │
|
||||
│ → Create initial boilerplate code │
|
||||
│ │
|
||||
│ Task 4: qa │
|
||||
│ → Draft M2 test strategy │
|
||||
│ → Define quality gates │
|
||||
└─────────────────────────────────────────────────────┘
|
||||
|
||||
All execute simultaneously ⚡
|
||||
|
||||
Main Coordinator → Waits for all to complete → Integrates results
|
||||
```
|
||||
|
||||
**How to trigger parallel execution**:
|
||||
Main coordinator makes multiple Task tool calls in a single message.
|
||||
|
||||
---
|
||||
|
||||
## Sequential Workflows
|
||||
|
||||
### Example 5: Bug Investigation and Fix
|
||||
|
||||
**Your Request**:
|
||||
```
|
||||
The login API is returning 500 errors intermittently
|
||||
```
|
||||
|
||||
**What Happens (Sequential Execution)**:
|
||||
```
|
||||
Step 1: qa agent
|
||||
→ Investigate error logs
|
||||
→ Identify error pattern
|
||||
→ Reproduce the issue
|
||||
→ Reports: "Race condition in session store"
|
||||
|
||||
↓ (Wait for results)
|
||||
|
||||
Step 2: backend agent (based on QA findings)
|
||||
→ Reviews session store implementation
|
||||
→ Identifies root cause
|
||||
→ Implements fix with proper locking
|
||||
→ Writes test to prevent regression
|
||||
|
||||
↓ (Wait for results)
|
||||
|
||||
Step 3: qa agent (verification)
|
||||
→ Runs regression tests
|
||||
→ Verifies fix works
|
||||
→ Confirms no new issues introduced
|
||||
→ Reports: "Fix verified, ready for deployment"
|
||||
|
||||
Main Coordinator → Reports complete investigation and fix
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Code Generation
|
||||
|
||||
### Example 6: Generate API Endpoint
|
||||
|
||||
**Your Request**:
|
||||
```
|
||||
Create a REST API endpoint for updating issue priority:
|
||||
- PATCH /api/issues/:id/priority
|
||||
- Validate priority (low, medium, high, urgent)
|
||||
- Log the change in audit trail
|
||||
- Return updated issue
|
||||
```
|
||||
|
||||
**What Happens**:
|
||||
```
|
||||
Main Coordinator → Calls backend agent
|
||||
|
||||
Backend Agent Generates:
|
||||
|
||||
1. Controller code:
|
||||
```typescript
|
||||
@Patch(':id/priority')
|
||||
async updatePriority(
|
||||
@Param('id') id: string,
|
||||
@Body() dto: UpdatePriorityDto,
|
||||
@CurrentUser() user: User
|
||||
): Promise<Issue> {
|
||||
return this.issueService.updatePriority(id, dto.priority, user.id);
|
||||
}
|
||||
```
|
||||
|
||||
2. Service code:
|
||||
```typescript
|
||||
async updatePriority(
|
||||
id: string,
|
||||
newPriority: Priority,
|
||||
userId: string
|
||||
): Promise<Issue> {
|
||||
const issue = await this.findById(id);
|
||||
const oldPriority = issue.priority;
|
||||
|
||||
issue.priority = newPriority;
|
||||
const updated = await this.issueRepository.save(issue);
|
||||
|
||||
await this.auditService.log({
|
||||
entityType: 'Issue',
|
||||
entityId: id,
|
||||
action: 'UPDATE_PRIORITY',
|
||||
userId,
|
||||
changes: { priority: { from: oldPriority, to: newPriority } },
|
||||
});
|
||||
|
||||
return updated;
|
||||
}
|
||||
```
|
||||
|
||||
3. DTO validation:
|
||||
```typescript
|
||||
export const UpdatePrioritySchema = z.object({
|
||||
priority: z.enum(['low', 'medium', 'high', 'urgent']),
|
||||
});
|
||||
|
||||
export type UpdatePriorityDto = z.infer<typeof UpdatePrioritySchema>;
|
||||
```
|
||||
|
||||
4. Unit tests:
|
||||
```typescript
|
||||
describe('updatePriority', () => {
|
||||
it('should update priority and log audit', async () => {
|
||||
const updated = await service.updatePriority('issue-1', 'urgent', 'user-1');
|
||||
expect(updated.priority).toBe('urgent');
|
||||
expect(auditService.log).toHaveBeenCalled();
|
||||
});
|
||||
});
|
||||
```
|
||||
|
||||
Main Coordinator → Returns complete, production-ready code
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Design and Planning
|
||||
|
||||
### Example 7: Design Sprint Planning UI
|
||||
|
||||
**Your Request**:
|
||||
```
|
||||
Design the Sprint Planning interface where PM can:
|
||||
- Create new sprint
|
||||
- Drag tasks from backlog to sprint
|
||||
- Set sprint goals and dates
|
||||
- View capacity vs planned work
|
||||
```
|
||||
|
||||
**What Happens**:
|
||||
```
|
||||
Main Coordinator coordinates design process:
|
||||
|
||||
Step 1: product-manager agent
|
||||
→ Define user stories
|
||||
→ Specify acceptance criteria
|
||||
→ Identify edge cases
|
||||
|
||||
Step 2: ux-ui agent
|
||||
→ Create user flow diagram
|
||||
→ Design wireframes
|
||||
→ Create high-fidelity mockups in Figma
|
||||
→ Define interaction states
|
||||
→ Specify animations
|
||||
|
||||
Delivers:
|
||||
- User persona analysis
|
||||
- User journey map
|
||||
- Low-fidelity wireframes
|
||||
- High-fidelity Figma mockups
|
||||
- Component specifications
|
||||
- Interaction guidelines
|
||||
|
||||
Step 3: frontend agent (optional, if implementation requested)
|
||||
→ Reviews designs
|
||||
→ Identifies technical considerations
|
||||
→ Suggests component architecture
|
||||
|
||||
Main Coordinator → Integrates design deliverables
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Example 8: Full Feature Development Lifecycle
|
||||
|
||||
**Your Request**:
|
||||
```
|
||||
Implement the "AI Daily Report Generation" feature from start to finish
|
||||
```
|
||||
|
||||
**What Happens** (Full lifecycle):
|
||||
|
||||
```
|
||||
Phase 1: PLANNING (Parallel)
|
||||
┌─────────────────────────────────────────────────────┐
|
||||
│ product-manager → Write PRD │
|
||||
│ architect → Design architecture │
|
||||
│ ux-ui → Design UI mockups │
|
||||
└─────────────────────────────────────────────────────┘
|
||||
|
||||
↓
|
||||
|
||||
Phase 2: IMPLEMENTATION (Sequential + Parallel)
|
||||
|
||||
Step 1: ai agent
|
||||
→ Design prompt template for daily reports
|
||||
→ Implement report generation logic
|
||||
→ Set up caching strategy
|
||||
|
||||
Step 2a: backend agent (parallel with 2b)
|
||||
→ Create POST /api/reports/daily endpoint
|
||||
→ Integrate AI service
|
||||
→ Implement diff preview for AI reports
|
||||
|
||||
Step 2b: frontend agent (parallel with 2a)
|
||||
→ Create DailyReport component
|
||||
→ Add "Generate Report" button
|
||||
→ Display AI-generated report with approval UI
|
||||
|
||||
↓
|
||||
|
||||
Phase 3: QUALITY ASSURANCE
|
||||
qa agent
|
||||
→ Write E2E tests for report generation
|
||||
→ Test AI prompt quality
|
||||
→ Verify approval workflow
|
||||
→ Performance test
|
||||
|
||||
↓
|
||||
|
||||
Phase 4: DELIVERY
|
||||
product-manager agent
|
||||
→ Update documentation
|
||||
→ Prepare release notes
|
||||
→ Update project timeline
|
||||
|
||||
Main Coordinator → Presents complete feature ready for deployment
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Tips for Effective Usage
|
||||
|
||||
### 1. Be Specific
|
||||
❌ Bad: "Make the app better"
|
||||
✅ Good: "Optimize the Kanban board rendering for 100+ tasks using virtualization"
|
||||
|
||||
### 2. Provide Context
|
||||
❌ Bad: "Add authentication"
|
||||
✅ Good: "Add JWT-based authentication to our NestJS backend, following the architecture in product.md"
|
||||
|
||||
### 3. Break Down Large Requests
|
||||
❌ Bad: "Build the entire ColaFlow system"
|
||||
✅ Good: "Let's start with M1. First, implement the core project/task data models"
|
||||
|
||||
### 4. Leverage Parallel Execution
|
||||
When tasks are independent, request them together:
|
||||
✅ "Prepare for M2: Create project plan, design MCP architecture, and draft test strategy"
|
||||
|
||||
### 5. Review and Iterate
|
||||
After receiving output from agents:
|
||||
- Review the deliverables
|
||||
- Ask for clarifications or modifications
|
||||
- Request additional details if needed
|
||||
|
||||
---
|
||||
|
||||
## Common Workflows
|
||||
|
||||
### Workflow 1: New Feature
|
||||
1. `product-manager` → PRD
|
||||
2. `architect` → Architecture design
|
||||
3. `backend` + `frontend` (parallel) → Implementation
|
||||
4. `qa` → Testing
|
||||
5. `product-manager` → Documentation
|
||||
|
||||
### Workflow 2: Bug Fix
|
||||
1. `qa` → Reproduce and diagnose
|
||||
2. `backend` or `frontend` → Fix implementation
|
||||
3. `qa` → Verify fix
|
||||
|
||||
### Workflow 3: Performance Optimization
|
||||
1. `qa` → Performance profiling
|
||||
2. `architect` → Optimization strategy
|
||||
3. `backend`/`frontend` → Implement optimizations
|
||||
4. `qa` → Verify improvements
|
||||
|
||||
### Workflow 4: UI/UX Enhancement
|
||||
1. `ux-ui` → Design improvements
|
||||
2. `frontend` → Implementation
|
||||
3. `qa` → Usability testing
|
||||
|
||||
---
|
||||
|
||||
## Getting Help
|
||||
|
||||
If you're unsure which agent to use, just ask the main coordinator:
|
||||
```
|
||||
"I need to [describe your goal]. Which agents should work on this?"
|
||||
```
|
||||
|
||||
The main coordinator will create an execution plan and route tasks appropriately.
|
||||
|
||||
Happy coding with the ColaFlow agent system! 🚀
|
||||
Reference in New Issue
Block a user