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
273
.claude/README.md
Normal file
273
.claude/README.md
Normal file
@@ -0,0 +1,273 @@
|
||||
# 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`
|
||||
Reference in New Issue
Block a user