mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-02-05 01:50:27 +08:00
docs: add comprehensive project documentation
Add four new comprehensive documentation files and update READMEs: New Documentation: - ARCHITECTURE.md: High-level system architecture overview * Design philosophy and core principles * System components and data flow * Multi-agent system details * CLI tool integration strategy * Session and memory management * Performance optimizations and best practices - CONTRIBUTING.md: Contributor guidelines * Code of conduct * Development setup instructions * Coding standards and best practices * Testing guidelines * Documentation requirements * Pull request process * Release process - FAQ.md: Frequently asked questions * General questions about CCW * Installation and setup * Usage and workflows * Commands and syntax * Sessions and tasks * Agents and tools * Memory system * Troubleshooting * Advanced topics - EXAMPLES.md: Real-world use cases * Quick start examples * Web development (Express, React, e-commerce) * API development (REST, GraphQL) * Testing & quality assurance (TDD, test generation) * Refactoring (monolith to microservices) * UI/UX design (design systems, landing pages) * Bug fixes (simple and complex) * Documentation generation * DevOps & automation (CI/CD, Docker) * Complex projects (chat app, analytics dashboard) Updated Documentation: - README.md: Added comprehensive documentation section * Organized docs into categories * Links to all new documentation files * Improved navigation structure - README_CN.md: Added documentation section (Chinese) * Same organization as English version * Links to all documentation resources Benefits: - Provides clear entry points for new users - Comprehensive reference for all features - Real-world examples for practical learning - Complete contributor onboarding - Better project discoverability
This commit is contained in:
Claude
567
ARCHITECTURE.md
Normal file
567
ARCHITECTURE.md
Normal file
@@ -0,0 +1,567 @@
|
||||
# 🏗️ Claude Code Workflow (CCW) - Architecture Overview
|
||||
|
||||
This document provides a high-level overview of CCW's architecture, design principles, and system components.
|
||||
|
||||
---
|
||||
|
||||
## 📋 Table of Contents
|
||||
|
||||
- [Design Philosophy](#design-philosophy)
|
||||
- [System Architecture](#system-architecture)
|
||||
- [Core Components](#core-components)
|
||||
- [Data Flow](#data-flow)
|
||||
- [Multi-Agent System](#multi-agent-system)
|
||||
- [CLI Tool Integration](#cli-tool-integration)
|
||||
- [Session Management](#session-management)
|
||||
- [Memory System](#memory-system)
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Design Philosophy
|
||||
|
||||
CCW is built on several core design principles that differentiate it from traditional AI-assisted development tools:
|
||||
|
||||
### 1. **Context-First Architecture**
|
||||
- Pre-defined context gathering eliminates execution uncertainty
|
||||
- Agents receive the correct information *before* implementation
|
||||
- Context is loaded dynamically based on task requirements
|
||||
|
||||
### 2. **JSON-First State Management**
|
||||
- Task states live in `.task/IMPL-*.json` files as the single source of truth
|
||||
- Markdown documents are read-only generated views
|
||||
- Eliminates state drift and synchronization complexity
|
||||
- Enables programmatic orchestration
|
||||
|
||||
### 3. **Autonomous Multi-Phase Orchestration**
|
||||
- Commands chain specialized sub-commands and agents
|
||||
- Automates complex workflows with zero user intervention
|
||||
- Each phase validates its output before proceeding
|
||||
|
||||
### 4. **Multi-Model Strategy**
|
||||
- Leverages unique strengths of different AI models
|
||||
- Gemini for analysis and exploration
|
||||
- Codex for implementation
|
||||
- Qwen for architecture and planning
|
||||
|
||||
### 5. **Hierarchical Memory System**
|
||||
- 4-layer documentation system (CLAUDE.md files)
|
||||
- Provides context at the appropriate level of abstraction
|
||||
- Prevents information overload
|
||||
|
||||
### 6. **Specialized Role-Based Agents**
|
||||
- Suite of agents mirrors a real software team
|
||||
- Each agent has specific responsibilities
|
||||
- Agents collaborate to complete complex tasks
|
||||
|
||||
---
|
||||
|
||||
## 🏛️ System Architecture
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "User Interface Layer"
|
||||
CLI[Slash Commands]
|
||||
CHAT[Natural Language]
|
||||
end
|
||||
|
||||
subgraph "Orchestration Layer"
|
||||
WF[Workflow Engine]
|
||||
SM[Session Manager]
|
||||
TM[Task Manager]
|
||||
end
|
||||
|
||||
subgraph "Agent Layer"
|
||||
AG1[@code-developer]
|
||||
AG2[@test-fix-agent]
|
||||
AG3[@ui-design-agent]
|
||||
AG4[@cli-execution-agent]
|
||||
AG5[More Agents...]
|
||||
end
|
||||
|
||||
subgraph "Tool Layer"
|
||||
GEMINI[Gemini CLI]
|
||||
QWEN[Qwen CLI]
|
||||
CODEX[Codex CLI]
|
||||
BASH[Bash/System]
|
||||
end
|
||||
|
||||
subgraph "Data Layer"
|
||||
JSON[Task JSON Files]
|
||||
MEM[CLAUDE.md Memory]
|
||||
STATE[Session State]
|
||||
end
|
||||
|
||||
CLI --> WF
|
||||
CHAT --> WF
|
||||
WF --> SM
|
||||
WF --> TM
|
||||
SM --> STATE
|
||||
TM --> JSON
|
||||
WF --> AG1
|
||||
WF --> AG2
|
||||
WF --> AG3
|
||||
WF --> AG4
|
||||
AG1 --> GEMINI
|
||||
AG1 --> QWEN
|
||||
AG1 --> CODEX
|
||||
AG2 --> BASH
|
||||
AG3 --> GEMINI
|
||||
AG4 --> CODEX
|
||||
GEMINI --> MEM
|
||||
QWEN --> MEM
|
||||
CODEX --> JSON
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔧 Core Components
|
||||
|
||||
### 1. **Workflow Engine**
|
||||
|
||||
The workflow engine orchestrates complex development processes through multiple phases:
|
||||
|
||||
- **Planning Phase**: Analyzes requirements and generates implementation plans
|
||||
- **Execution Phase**: Coordinates agents to implement tasks
|
||||
- **Verification Phase**: Validates implementation quality
|
||||
- **Testing Phase**: Generates and executes tests
|
||||
- **Review Phase**: Performs code review and quality analysis
|
||||
|
||||
**Key Features**:
|
||||
- Multi-phase orchestration
|
||||
- Automatic session management
|
||||
- Context propagation between phases
|
||||
- Quality gates at each phase transition
|
||||
|
||||
### 2. **Session Manager**
|
||||
|
||||
Manages isolated workflow contexts:
|
||||
|
||||
```
|
||||
.workflow/
|
||||
├── active/ # Active sessions
|
||||
│ ├── WFS-user-auth/ # User authentication session
|
||||
│ ├── WFS-payment/ # Payment integration session
|
||||
│ └── WFS-dashboard/ # Dashboard redesign session
|
||||
└── archives/ # Completed sessions
|
||||
└── WFS-old-feature/ # Archived session
|
||||
```
|
||||
|
||||
**Capabilities**:
|
||||
- Directory-based session tracking
|
||||
- Session state persistence
|
||||
- Parallel session support
|
||||
- Session archival and resumption
|
||||
|
||||
### 3. **Task Manager**
|
||||
|
||||
Handles hierarchical task structures:
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "IMPL-1.2",
|
||||
"title": "Implement JWT authentication",
|
||||
"status": "pending",
|
||||
"meta": {
|
||||
"type": "feature",
|
||||
"agent": "code-developer"
|
||||
},
|
||||
"context": {
|
||||
"requirements": ["JWT authentication", "OAuth2 support"],
|
||||
"focus_paths": ["src/auth", "tests/auth"],
|
||||
"acceptance": ["JWT validation works", "OAuth flow complete"]
|
||||
},
|
||||
"flow_control": {
|
||||
"pre_analysis": [...],
|
||||
"implementation_approach": {...}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Features**:
|
||||
- JSON-first data model
|
||||
- Hierarchical task decomposition (max 2 levels)
|
||||
- Dynamic subtask creation
|
||||
- Dependency tracking
|
||||
|
||||
### 4. **Memory System**
|
||||
|
||||
Four-layer hierarchical documentation:
|
||||
|
||||
```
|
||||
CLAUDE.md (Project root - high-level overview)
|
||||
├── src/CLAUDE.md (Source layer - module summaries)
|
||||
│ ├── auth/CLAUDE.md (Module layer - component details)
|
||||
│ │ └── jwt/CLAUDE.md (Component layer - implementation details)
|
||||
```
|
||||
|
||||
**Memory Commands**:
|
||||
- `/memory:update-full` - Complete project rebuild
|
||||
- `/memory:update-related` - Incremental updates for changed modules
|
||||
- `/memory:load` - Quick context loading for specific tasks
|
||||
|
||||
---
|
||||
|
||||
## 🔄 Data Flow
|
||||
|
||||
### Typical Workflow Execution Flow
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant User
|
||||
participant CLI
|
||||
participant Workflow
|
||||
participant Agent
|
||||
participant Tool
|
||||
participant Data
|
||||
|
||||
User->>CLI: /workflow:plan "Feature description"
|
||||
CLI->>Workflow: Initialize planning workflow
|
||||
Workflow->>Data: Create session
|
||||
Workflow->>Agent: @action-planning-agent
|
||||
Agent->>Tool: gemini-wrapper analyze
|
||||
Tool->>Data: Update CLAUDE.md
|
||||
Agent->>Data: Generate IMPL-*.json
|
||||
Workflow->>User: Plan complete
|
||||
|
||||
User->>CLI: /workflow:execute
|
||||
CLI->>Workflow: Start execution
|
||||
Workflow->>Data: Load tasks from JSON
|
||||
Workflow->>Agent: @code-developer
|
||||
Agent->>Tool: Read context
|
||||
Agent->>Tool: Implement code
|
||||
Agent->>Data: Update task status
|
||||
Workflow->>User: Execution complete
|
||||
```
|
||||
|
||||
### Context Flow
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
A[User Request] --> B[Context Gathering]
|
||||
B --> C[CLAUDE.md Memory]
|
||||
B --> D[Task JSON]
|
||||
B --> E[Session State]
|
||||
C --> F[Agent Context]
|
||||
D --> F
|
||||
E --> F
|
||||
F --> G[Tool Execution]
|
||||
G --> H[Implementation]
|
||||
H --> I[Update State]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🤖 Multi-Agent System
|
||||
|
||||
### Agent Specialization
|
||||
|
||||
CCW uses specialized agents for different types of tasks:
|
||||
|
||||
| Agent | Responsibility | Tools Used |
|
||||
|-------|---------------|------------|
|
||||
| **@code-developer** | Code implementation | Gemini, Qwen, Codex, Bash |
|
||||
| **@test-fix-agent** | Test generation and fixing | Codex, Bash |
|
||||
| **@ui-design-agent** | UI design and prototyping | Gemini, Claude Vision |
|
||||
| **@action-planning-agent** | Task planning and decomposition | Gemini |
|
||||
| **@cli-execution-agent** | Autonomous CLI task handling | Codex, Gemini, Qwen |
|
||||
| **@cli-explore-agent** | Codebase exploration | ripgrep, find |
|
||||
| **@context-search-agent** | Context gathering | Grep, Glob |
|
||||
| **@doc-generator** | Documentation generation | Gemini, Qwen |
|
||||
| **@memory-bridge** | Memory system updates | Gemini, Qwen |
|
||||
| **@universal-executor** | General task execution | All tools |
|
||||
|
||||
### Agent Communication
|
||||
|
||||
Agents communicate through:
|
||||
1. **Shared Session State**: All agents can read/write session JSON
|
||||
2. **Task JSON Files**: Tasks contain context for agent handoffs
|
||||
3. **CLAUDE.md Memory**: Shared project knowledge base
|
||||
4. **Flow Control**: Pre-analysis and implementation approach definitions
|
||||
|
||||
---
|
||||
|
||||
## 🛠️ CLI Tool Integration
|
||||
|
||||
### Three CLI Tools
|
||||
|
||||
CCW integrates three external AI tools, each optimized for specific tasks:
|
||||
|
||||
#### 1. **Gemini CLI** - Deep Analysis
|
||||
- **Strengths**: Pattern recognition, architecture understanding, comprehensive analysis
|
||||
- **Use Cases**:
|
||||
- Codebase exploration
|
||||
- Architecture analysis
|
||||
- Bug diagnosis
|
||||
- Memory system updates
|
||||
|
||||
#### 2. **Qwen CLI** - Architecture & Planning
|
||||
- **Strengths**: System design, code generation, architectural planning
|
||||
- **Use Cases**:
|
||||
- Architecture design
|
||||
- System planning
|
||||
- Code generation
|
||||
- Refactoring strategies
|
||||
|
||||
#### 3. **Codex CLI** - Autonomous Development
|
||||
- **Strengths**: Self-directed implementation, error fixing, test generation
|
||||
- **Use Cases**:
|
||||
- Feature implementation
|
||||
- Bug fixes
|
||||
- Test generation
|
||||
- Autonomous development
|
||||
|
||||
### Tool Selection Strategy
|
||||
|
||||
CCW automatically selects the best tool based on task type:
|
||||
|
||||
```
|
||||
Analysis Task → Gemini CLI
|
||||
Planning Task → Qwen CLI
|
||||
Implementation Task → Codex CLI
|
||||
```
|
||||
|
||||
Users can override with `--tool` parameter:
|
||||
```bash
|
||||
/cli:analyze --tool codex "Analyze authentication flow"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📦 Session Management
|
||||
|
||||
### Session Lifecycle
|
||||
|
||||
```mermaid
|
||||
stateDiagram-v2
|
||||
[*] --> Creating: /workflow:session:start
|
||||
Creating --> Active: Session initialized
|
||||
Active --> Paused: User pauses
|
||||
Paused --> Active: /workflow:session:resume
|
||||
Active --> Completed: /workflow:session:complete
|
||||
Completed --> Archived: Move to archives/
|
||||
Archived --> [*]
|
||||
```
|
||||
|
||||
### Session Structure
|
||||
|
||||
```
|
||||
.workflow/active/WFS-feature-name/
|
||||
├── workflow-session.json # Session metadata
|
||||
├── .task/ # Task JSON files
|
||||
│ ├── IMPL-1.json
|
||||
│ ├── IMPL-1.1.json
|
||||
│ └── IMPL-2.json
|
||||
├── .chat/ # Chat logs
|
||||
├── brainstorming/ # Brainstorm artifacts
|
||||
│ ├── guidance-specification.md
|
||||
│ └── system-architect/analysis.md
|
||||
└── artifacts/ # Generated files
|
||||
├── IMPL_PLAN.md
|
||||
└── verification-report.md
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 💾 Memory System
|
||||
|
||||
### Hierarchical CLAUDE.md Structure
|
||||
|
||||
The memory system maintains project knowledge across four layers:
|
||||
|
||||
#### **Layer 1: Project Root**
|
||||
```markdown
|
||||
# Project Overview
|
||||
- High-level architecture
|
||||
- Technology stack
|
||||
- Key design decisions
|
||||
- Entry points
|
||||
```
|
||||
|
||||
#### **Layer 2: Source Directory**
|
||||
```markdown
|
||||
# Source Code Structure
|
||||
- Module summaries
|
||||
- Dependency relationships
|
||||
- Common patterns
|
||||
```
|
||||
|
||||
#### **Layer 3: Module Directory**
|
||||
```markdown
|
||||
# Module Details
|
||||
- Component responsibilities
|
||||
- API interfaces
|
||||
- Internal structure
|
||||
```
|
||||
|
||||
#### **Layer 4: Component Directory**
|
||||
```markdown
|
||||
# Component Implementation
|
||||
- Function signatures
|
||||
- Implementation details
|
||||
- Usage examples
|
||||
```
|
||||
|
||||
### Memory Update Strategies
|
||||
|
||||
#### Full Update (`/memory:update-full`)
|
||||
- Rebuilds entire project documentation
|
||||
- Uses layer-based execution (Layer 3 → 1)
|
||||
- Batch processing (4 modules/agent)
|
||||
- Fallback mechanism (gemini → qwen → codex)
|
||||
|
||||
#### Incremental Update (`/memory:update-related`)
|
||||
- Updates only changed modules
|
||||
- Analyzes git changes
|
||||
- Efficient for daily development
|
||||
|
||||
#### Quick Load (`/memory:load`)
|
||||
- No file updates
|
||||
- Task-specific context gathering
|
||||
- Returns JSON context package
|
||||
- Fast context injection
|
||||
|
||||
---
|
||||
|
||||
## 🔐 Quality Assurance
|
||||
|
||||
### Quality Gates
|
||||
|
||||
CCW enforces quality at multiple levels:
|
||||
|
||||
1. **Planning Phase**:
|
||||
- Requirements coverage check
|
||||
- Dependency validation
|
||||
- Task specification quality assessment
|
||||
|
||||
2. **Execution Phase**:
|
||||
- Context validation before implementation
|
||||
- Pattern consistency checks
|
||||
- Test generation
|
||||
|
||||
3. **Review Phase**:
|
||||
- Code quality analysis
|
||||
- Security review
|
||||
- Architecture review
|
||||
|
||||
### Verification Commands
|
||||
|
||||
- `/workflow:action-plan-verify` - Validates plan quality before execution
|
||||
- `/workflow:tdd-verify` - Verifies TDD cycle compliance
|
||||
- `/workflow:review` - Post-implementation review
|
||||
|
||||
---
|
||||
|
||||
## 🚀 Performance Optimizations
|
||||
|
||||
### 1. **Lazy Loading**
|
||||
- Files created only when needed
|
||||
- On-demand document generation
|
||||
- Minimal upfront cost
|
||||
|
||||
### 2. **Parallel Execution**
|
||||
- Independent tasks run concurrently
|
||||
- Multi-agent parallel brainstorming
|
||||
- Batch processing for memory updates
|
||||
|
||||
### 3. **Context Caching**
|
||||
- CLAUDE.md acts as knowledge cache
|
||||
- Reduces redundant analysis
|
||||
- Faster context retrieval
|
||||
|
||||
### 4. **Atomic Session Management**
|
||||
- Ultra-fast session switching (<10ms)
|
||||
- Simple file marker system
|
||||
- No database overhead
|
||||
|
||||
---
|
||||
|
||||
## 📊 Scalability
|
||||
|
||||
### Horizontal Scalability
|
||||
|
||||
- **Multiple Sessions**: Run parallel workflows for different features
|
||||
- **Team Collaboration**: Session-based isolation prevents conflicts
|
||||
- **Incremental Updates**: Only update affected modules
|
||||
|
||||
### Vertical Scalability
|
||||
|
||||
- **Hierarchical Tasks**: Efficient task decomposition (max 2 levels)
|
||||
- **Selective Context**: Load only relevant context for each task
|
||||
- **Batch Processing**: Process multiple modules per agent invocation
|
||||
|
||||
---
|
||||
|
||||
## 🔮 Extensibility
|
||||
|
||||
### Adding New Agents
|
||||
|
||||
Create agent definition in `.claude/agents/`:
|
||||
|
||||
```markdown
|
||||
# Agent Name
|
||||
|
||||
## Role
|
||||
Agent description
|
||||
|
||||
## Tools Available
|
||||
- Tool 1
|
||||
- Tool 2
|
||||
|
||||
## Prompt
|
||||
Agent instructions...
|
||||
```
|
||||
|
||||
### Adding New Commands
|
||||
|
||||
Create command in `.claude/commands/`:
|
||||
|
||||
```bash
|
||||
#!/usr/bin/env bash
|
||||
# Command implementation
|
||||
```
|
||||
|
||||
### Custom Workflows
|
||||
|
||||
Combine existing commands to create custom workflows:
|
||||
|
||||
```bash
|
||||
/workflow:brainstorm:auto-parallel "Topic"
|
||||
/workflow:plan
|
||||
/workflow:action-plan-verify
|
||||
/workflow:execute
|
||||
/workflow:review
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🎓 Best Practices
|
||||
|
||||
### For Users
|
||||
|
||||
1. **Keep Memory Updated**: Run `/memory:update-related` after major changes
|
||||
2. **Use Quality Gates**: Run `/workflow:action-plan-verify` before execution
|
||||
3. **Session Management**: Complete sessions with `/workflow:session:complete`
|
||||
4. **Tool Selection**: Let CCW auto-select tools unless you have specific needs
|
||||
|
||||
### For Developers
|
||||
|
||||
1. **Follow JSON-First**: Never modify markdown documents directly
|
||||
2. **Agent Context**: Provide complete context in task JSON
|
||||
3. **Error Handling**: Implement graceful fallbacks
|
||||
4. **Testing**: Test agents independently before integration
|
||||
|
||||
---
|
||||
|
||||
## 📚 Further Reading
|
||||
|
||||
- [Getting Started Guide](GETTING_STARTED.md) - Quick start tutorial
|
||||
- [Command Reference](COMMAND_REFERENCE.md) - All available commands
|
||||
- [Command Specification](COMMAND_SPEC.md) - Detailed command specs
|
||||
- [Workflow Diagrams](WORKFLOW_DIAGRAMS.md) - Visual workflow representations
|
||||
- [Contributing Guide](CONTRIBUTING.md) - How to contribute
|
||||
- [Examples](EXAMPLES.md) - Real-world use cases
|
||||
|
||||
---
|
||||
|
||||
**Last Updated**: 2025-11-20
|
||||
**Version**: 5.8.1
|
||||
Reference in New Issue
Block a user