ColaFlow/.claude

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	Complete agent configuration guide
AGENT_QUICK_REFERENCE.md	Quick reference for agent setup
RESEARCH_REPORT_AGENT_CONFIGURATION.md	Research findings and technical details
verify-agents.md	Agent configuration validation checklist
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

   # Check if agents are properly configured
   ls .claude/agents/
   

   See 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 (5 min)
2. Review AGENT_CONFIGURATION_GUIDE.md (comprehensive)
3. Run validation: verify-agents.md

Configuring a new agent? Use this template:

---
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:

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:

// 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