ColaFlow/.claude/README.md

# ColaFlow Agent System

This directory contains the sub agent configurations for the ColaFlow project.

## 📚 Documentation Index

| Document | Purpose |
|----------|---------|
| **README.md** (this file) | Overview and quick start |
| **[AGENT_CONFIGURATION_GUIDE.md](AGENT_CONFIGURATION_GUIDE.md)** | Complete agent configuration guide |
| **[AGENT_QUICK_REFERENCE.md](AGENT_QUICK_REFERENCE.md)** | Quick reference for agent setup |
| **[RESEARCH_REPORT_AGENT_CONFIGURATION.md](RESEARCH_REPORT_AGENT_CONFIGURATION.md)** | Research findings and technical details |
| **[verify-agents.md](verify-agents.md)** | Agent configuration validation checklist |
| **[USAGE_EXAMPLES.md](USAGE_EXAMPLES.md)** | Detailed usage examples |

## Structure

```
.claude/
├── agents/                                    # Sub agent configurations
│   ├── researcher.md                         # Technical Researcher agent
│   ├── product-manager.md                    # Product Manager agent
│   ├── architect.md                          # System Architect agent
│   ├── backend.md                            # Backend Engineer agent
│   ├── frontend.md                           # Frontend Engineer agent
│   ├── ai.md                                 # AI Engineer agent
│   ├── qa.md                                 # QA Engineer agent
│   ├── ux-ui.md                              # UX/UI Designer agent
│   └── progress-recorder.md                  # Progress Recorder agent
├── skills/                                    # Skills for quality assurance
│   └── code-reviewer.md                      # Code review and standards enforcement
├── AGENT_CONFIGURATION_GUIDE.md              # ⭐ Complete configuration guide
├── AGENT_QUICK_REFERENCE.md                  # ⭐ Quick reference card
├── RESEARCH_REPORT_AGENT_CONFIGURATION.md    # ⭐ Technical research report
├── verify-agents.md                          # ⭐ Validation checklist
├── USAGE_EXAMPLES.md                         # Detailed usage examples
└── README.md                                 # This file

../CLAUDE.md                                  # Main coordinator (project root)
```

## ⚡ Quick Start

### For Users

1. **Verify Agent Configuration**
   ```bash
   # Check if agents are properly configured
   ls .claude/agents/
   ```
   See [verify-agents.md](verify-agents.md) for detailed validation.

2. **Use Agents via Main Coordinator**
   Simply talk to Claude - it will automatically route tasks to the right agent:
   ```
   请研究 NestJS 最佳实践          → researcher agent
   实现用户登录 API                → backend agent
   设计看板界面                    → ux-ui + frontend agents
   ```

3. **Explicitly Call an Agent** (optional)
   ```
   请使用 researcher agent 查找最新的 React 文档
   ```

### For Developers

**New to Claude Code agents?** Start with:
1. Read [AGENT_QUICK_REFERENCE.md](AGENT_QUICK_REFERENCE.md) (5 min)
2. Review [AGENT_CONFIGURATION_GUIDE.md](AGENT_CONFIGURATION_GUIDE.md) (comprehensive)
3. Run validation: [verify-agents.md](verify-agents.md)

**Configuring a new agent?** Use this template:
```yaml
---
name: your-agent-name
description: Clear description of agent's purpose and when to invoke it
tools: Read, Write, Edit, Bash, TodoWrite
model: inherit
---

# Your Agent

Agent's system prompt content...
```

## Agent Roles

| Agent | File | Responsibilities |
|-------|------|------------------|
| **Main Coordinator** | `CLAUDE.md` | Understands requirements, routes tasks to appropriate agents, integrates results |
| **Researcher** | `agents/researcher.md` | Technical research, API documentation, best practices |
| **Product Manager** | `agents/product-manager.md` | Project planning, requirements management, progress tracking |
| **Architect** | `agents/architect.md` | System architecture, technology selection, scalability |
| **Backend Engineer** | `agents/backend.md` | Server-side code, API design, database, MCP integration |
| **Frontend Engineer** | `agents/frontend.md` | UI development, components, state management |
| **AI Engineer** | `agents/ai.md` | AI features, prompt engineering, model integration |
| **QA Engineer** | `agents/qa.md` | Test strategy, test cases, quality assurance |
| **UX/UI Designer** | `agents/ux-ui.md` | User experience, interface design, design system |
| **Progress Recorder** | `agents/progress-recorder.md` | Project memory management, progress tracking, information archiving |

## Skills

Skills are quality assurance mechanisms that automatically apply to agent outputs:

| Skill | File | Purpose |
|-------|------|---------|
| **Code Reviewer** | `skills/code-reviewer.md` | Ensures all code follows proper coding standards, best practices, and maintains high quality |

### How Skills Work

Skills are automatically applied by the main coordinator when:
- Backend or Frontend agents generate code
- Any code modifications are proposed
- Code refactoring is performed

The Code Reviewer skill checks for:
- ✅ Naming conventions (camelCase, PascalCase, etc.)
- ✅ TypeScript best practices
- ✅ Error handling patterns
- ✅ Security vulnerabilities
- ✅ Performance considerations
- ✅ Common anti-patterns

If issues are found, the coordinator will request fixes before presenting the code to you.

## How It Works

### 1. Main Coordinator Routes Tasks

The main coordinator (defined in `CLAUDE.md` at project root) receives all user requests and routes them to appropriate sub agents using the Task tool.

Example:
```
User: "I need to implement the MCP Server"

Main Coordinator analyzes the request and determines:
- Needs architecture design
- Needs backend implementation
- Needs testing strategy

Main Coordinator calls:
1. Task tool with subagent_type="architect"
2. Task tool with subagent_type="backend"
3. Task tool with subagent_type="qa"
```

### 2. Sub Agents Execute Tasks

Each sub agent is specialized in their domain and produces high-quality, domain-specific outputs:

- **Product Manager**: PRD documents, project plans, progress reports
- **Architect**: Architecture designs, technology recommendations
- **Backend**: Clean, tested backend code
- **Frontend**: Beautiful, performant UI components
- **AI**: AI features with safety mechanisms
- **QA**: Comprehensive test cases and test strategies
- **UX/UI**: User-friendly interface designs

### 3. Main Coordinator Integrates Results

The main coordinator collects outputs from all sub agents and presents a unified response to the user.

## Usage Examples

### Example 1: Implement New Feature

**User Request**: "Implement AI-powered task creation feature"

**Main Coordinator Flow**:
1. Calls `architect` agent → Get technical architecture
2. Calls `product-manager` agent → Define requirements and acceptance criteria
3. Calls `ai` agent → Design prompts and model integration
4. Calls `backend` agent → Implement API and MCP Server
5. Calls `frontend` agent → Build UI and AI console
6. Calls `qa` agent → Create test cases
7. Integrates all results and reports to user

### Example 2: Fix Performance Issue

**User Request**: "Kanban board loads slowly with many tasks"

**Main Coordinator Flow**:
1. Calls `qa` agent → Performance testing and profiling
2. Based on findings, calls `frontend` agent → Optimize rendering
3. Or calls `backend` agent → Optimize API queries
4. Calls `qa` agent again → Verify performance improvement

### Example 3: Design New UI

**User Request**: "Design the sprint planning interface"

**Main Coordinator Flow**:
1. Calls `product-manager` agent → Define sprint planning requirements
2. Calls `ux-ui` agent → Design user flows and mockups
3. Calls `frontend` agent → Implement the design
4. Calls `qa` agent → Usability testing

## Calling Sub Agents

Sub agents are called using the Task tool with the `subagent_type` parameter:

```typescript
Task({
  subagent_type: "architect",  // or "product-manager", "backend", etc.
  description: "Short task description",
  prompt: "Detailed instructions for the agent..."
})
```

### Parallel Execution

For independent tasks, you can call multiple agents in parallel by using multiple Task calls in a single message:

```typescript
// Single message with multiple Task calls
Task({ subagent_type: "architect", ... })
Task({ subagent_type: "product-manager", ... })
```

### Sequential Execution

For dependent tasks, call agents sequentially (wait for first agent's response before calling the next).

## Best Practices

1. **Clear Instructions**: Provide detailed, specific prompts to sub agents
2. **Right Agent**: Route tasks to the most appropriate agent
3. **Context**: Include relevant project context (see `product.md`)
4. **Integration**: Integrate results before presenting to user
5. **Parallel Work**: Use parallel execution for independent tasks

## Agent Collaboration

Agents suggest when other agents should be involved:

- Product Manager needs technical feasibility → Suggests calling Architect
- Backend needs API contract → Suggests calling Frontend
- Frontend needs design specs → Suggests calling UX/UI
- Any agent needs testing → Suggests calling QA

The main coordinator handles these routing decisions.

## Project Context

All agents have access to:
- `product.md`: Complete ColaFlow project plan
- `CLAUDE.md`: Main coordinator guidelines
- `.claude/agents/*.md`: Other agent configurations

## Quality Standards

Each agent follows strict quality standards:

- **Code Quality**: Clean, maintainable, well-tested code
- **Documentation**: Clear documentation and comments
- **Best Practices**: Industry best practices and standards
- **Testing**: Comprehensive test coverage
- **Security**: Security-first approach (especially for AI operations)

## Getting Started

1. Read `CLAUDE.md` in the project root to understand the main coordinator
2. Review `product.md` to understand the ColaFlow project
3. Check individual agent files in `.claude/agents/` to understand each role
4. Start by asking the main coordinator (not individual agents directly)

## Support

For questions about the agent system, refer to:
- Main coordinator: `CLAUDE.md`
- Project details: `product.md`
- Agent specifics: `.claude/agents/[agent-name].md`