**Behind the apparent complexity, SuperClaude is actually simple to use.**
You don't need to learn all the commands, flags, and personas. Just start using it! 🎈
SuperClaude has an **intelligent routing system** that figures out what you need automatically:
- Type `/analyze some-code/` → It picks the right analysis tools
- Ask about security → Security expert auto-activates
- Work on frontend → UI specialist takes over
- Debug something → Investigation mode kicks in
**Learning emerges during use** - you'll naturally discover what works without studying manuals first.
The detailed guides below? They're here **when you want to understand** what just happened or dive deeper. But honestly? Most of the time you can just wing it. 😊
---
**TL;DR**: Install it, try `/analyze` or `/build` on your code, watch the magic happen.
---
A comprehensive guide to understanding and using SuperClaude v3.0 effectively. But remember - you can skip straight to trying it out!
SuperClaude makes Claude Code smarter for development work. Instead of generic responses, you get specialized help from different experts (security, performance, frontend, etc.) who know their stuff.
**The honest truth**: We just released v3.0 and it's fresh out of beta. It works pretty well for what it does, but you should expect some rough edges as we continue improving things. We built this because we wanted Claude Code to be more helpful for real software development workflows.
**The magic part?** You don't need to manage any of this complexity. Just use normal commands like `/analyze` or `/build` and SuperClaude automatically figures out which experts to involve and what tools to use. 🪄
The beauty is that most of this happens automatically. You make a request, SuperClaude figures out the best approach, and executes with appropriate tools and expertise. No configuration, no setup, no learning curve - just better results. ✨
SuperClaude is built from several interconnected systems that work together. Here's how each component fits into the bigger picture.
### Commands: Your Toolkit 🛠️
Commands are specialized tools that handle specific types of development work. Instead of generic "help me with this," you get purpose-built tools for different scenarios.
-`/dev-setup` - Development environment configuration
-`/design` - System architecture and component design
**Analysis** 🔍
-`/analyze` - Comprehensive code and system analysis
-`/review` - Code review and quality assessment
-`/troubleshoot` - Problem investigation and debugging
**Quality** ✨
-`/improve` - Code enhancement and optimization
-`/scan` - Security and quality scanning
-`/test` - Testing and coverage analysis
**Utilities** 🔧
-`/document` - Documentation creation
-`/deploy` - Deployment operations
-`/git` - Enhanced git workflows
-`/migrate` - Migration management
-`/estimate` - Project estimation
-`/task` - Long-term project management
Each command has its own flags, auto-activates appropriate personas, and integrates with relevant MCP servers. For detailed examples and usage patterns, see the [Commands Guide](commands-guide.md).
### Flags: Behavior Modifiers 🏁
Flags change how SuperClaude processes your requests. They're like command-line options that modify behavior, add capabilities, or change output style.
**Key Flag Categories:**
**Planning & Analysis** 🧠
-`--think` / `--think-hard` / `--ultrathink` - Control thinking depth
-`--plan` - Show execution plan before running
**Efficiency & Control** ⚡
-`--uc` - Ultra-compressed output for large operations
-`--safe-mode` - Conservative execution with validation
-`--validate` - Pre-operation risk assessment
**MCP Server Control** 🔧
-`--c7` - Enable Context7 for documentation
-`--seq` - Enable Sequential for complex analysis
-`--magic` - Enable Magic for UI components
-`--play` - Enable Playwright for testing
**Advanced Orchestration** 🎭
-`--delegate` - Enable sub-agent delegation for parallel processing
-`--wave-mode` - Multi-stage execution with compound intelligence
-`--loop` - Iterative improvement mode
**Focus & Scope** 🎯
-`--focus security` - Focus on specific domains
-`--scope project` - Set analysis scope
-`--persona-[name]` - Activate specific personas
Flags often auto-activate based on context. For example, security-related requests automatically get `--persona-security` and `--focus security`. See the [Flags Guide](flags-guide.md) for comprehensive details and patterns.
### Personas: AI Specialists 🎭
Personas are like having a team of specialists available on demand. Each brings different expertise, priorities, and approaches to problems.
**11 Personas Organized by Domain:**
**Technical Specialists** 🔧
- 🏗️ **architect** - Systems design, long-term architecture
Personas auto-activate based on request patterns but you can override with `--persona-[name]` flags. Each has different priorities (e.g., security persona prioritizes security over speed). See the [Personas Guide](personas-guide.md) for detailed descriptions and examples.
5.**Orchestrator**: Routes everything for optimal execution
**Result**: Security-focused analysis with threat modeling perspective, systematic methodology, and comprehensive coverage.
This coordination happens for all requests - SuperClaude figures out the best combination of tools and expertise for your specific need.
---
## The Three Operational Modes 🎭
SuperClaude operates in three distinct modes that optimize different aspects of the development workflow. Understanding these modes helps you get the most out of the framework.
### Task Management Mode 📋
**What it is**: Structured workflow execution with progress tracking and validation.
**When it's used**: Any multi-step operation that needs tracking and coordination.
**How it works**: SuperClaude breaks work into manageable tasks, tracks progress, and ensures quality through validation gates.
/improve legacy-system/ --uc --delegate auto # Efficient large operations
```
**Performance Metrics**:
- Target: 30-50% token reduction
- Quality: ≥95% information preservation
- Speed: <100ms compression decisions
- Integration: Seamless framework compliance
#### Mode Integration
The three modes often work together:
```bash
/improve large-legacy-system/ --wave-mode auto --uc --introspect
```
**What happens**:
- **Task Management**: Creates structured improvement plan with progress tracking
- **Token Efficiency**: Compresses output for large-scale operation
- **Introspection**: Analyzes improvement strategy and validates approach
---
## The Orchestrator System 🎯
The orchestrator is SuperClaude's intelligent routing system that analyzes your requests and coordinates the optimal combination of tools, personas, and integrations. It's what makes SuperClaude feel smart and responsive rather than just a collection of separate tools.
### How the Orchestrator Works 🔄
**Think of it as a smart dispatcher** that:
1.**Analyzes** your request to understand intent and complexity
2.**Routes** to the best combination of commands, flags, personas, and MCP servers
3.**Coordinates** execution for optimal results
4.**Validates** through quality gates to ensure good outcomes
5.**Optimizes** performance and resource usage
### Detection Engine 🧠
The detection engine analyzes every request through multiple lenses:
#### Pattern Recognition
**Complexity Detection**:
- **Simple**: Single file operations, basic tasks (<3 steps) → Direct execution
**Quality Gates**: Performance-focused validation with benchmarking
#### Example 3: Large Codebase Analysis
```bash
/analyze enterprise-monorepo/
```
**Orchestrator Analysis**:
- Scope: Large (>50 files detected)
- Complexity: High (enterprise-scale)
- Resources: High token usage predicted
**Auto-Coordination**:
- --delegate auto flag (parallel processing)
- --uc flag (token optimization)
- 🏗️ architect persona (system-level analysis)
- Sequential MCP (structured analysis)
**Quality Gates**: Distributed validation across sub-agents
### Orchestrator Configuration ⚙️
**Performance Settings**:
```yaml
orchestrator_config:
enable_caching: true
parallel_operations: true
max_parallel: 3
token_reserve: 10%
emergency_threshold: 90%
```
**Intelligence Settings**:
```yaml
learning_enabled: true
confidence_threshold: 0.7
pattern_detection: aggressive
wave_score_threshold: 0.7
```
The orchestrator continuously learns from successful patterns and optimizes future routing decisions based on outcomes.
---
## Rules & Principles 📏
SuperClaude operates according to core rules and principles that ensure consistent, reliable, and helpful behavior. Understanding these helps you predict how SuperClaude will approach problems and why it makes certain decisions.
### Core Operational Rules ⚖️
These are the non-negotiable rules that SuperClaude always follows:
#### File Operation Security 🔐
- **Always Read before Write/Edit** - SuperClaude never modifies files without understanding current content
- **Outcome analysis** - Successful patterns are reinforced
- **Technology changes** - Principles adapt to new development practices
- **User needs** - Rules balance flexibility with consistency
The goal is to maintain helpful, predictable behavior while adapting to the changing landscape of software development.
---
## Getting Started Workflows 🛣️
Now that you understand SuperClaude's components, let's look at practical workflows for different development scenarios. These patterns will help you get productive quickly.
### First-Time Setup 🎬
If you haven't installed SuperClaude yet, see the [Installation Guide](installation-guide.md). Once installed, here's how to get started:
#### Quick Verification
```bash
# Test basic functionality
/help # Should show SuperClaude commands
/analyze README.md # Try analyzing a simple file
/build --help # Check command options
```
#### Understanding Auto-Activation
Try these commands to see how SuperClaude automatically chooses the right tools:
```bash
# Frontend work → frontend persona + Magic MCP
/build src/components/
# Security analysis → security persona + Sequential MCP
/scan auth/ --focus security
# Performance investigation → performance persona + Playwright MCP
/analyze --focus performance slow-endpoints/
```
Watch for auto-activated flags and personas in the output. This shows SuperClaude's intelligent routing in action.
### Development Workflow Patterns 🔄
#### New Project Onboarding
When starting work on an unfamiliar project:
```bash
# 1. Load project context
/load --deep --summary
# → Gives overview of structure, dependencies, patterns
# 2. Analyze architecture
/analyze --focus architecture
# → 🏗️ architect persona provides system understanding
# 3. Check code quality
/scan --focus quality
# → 🧪 qa persona identifies potential issues
# 4. Review documentation
/document README --type guide
# → ✍️ scribe persona improves project documentation
```
#### Feature Development Cycle
For developing new features:
```bash
# 1. Design phase
/design user-dashboard --type component
# → 🏗️ architect + 🎨 frontend personas coordinate
# 2. Implementation
/build dashboard-components/
# → 🎨 frontend persona + Magic MCP for UI generation
# 3. Testing
/test --type e2e dashboard/
# → 🧪 qa persona + Playwright MCP for testing
# 4. Documentation
/document dashboard/ --type api
# → ✍️ scribe persona creates comprehensive docs
```
#### Bug Investigation & Resolution
For systematic debugging:
```bash
# 1. Problem investigation
/troubleshoot "login randomly fails" --think
# → 🔍 analyzer persona + Sequential MCP for methodology
# 2. Root cause analysis
/analyze auth-flow/ --focus debugging
# → Systematic investigation with evidence collection
# 3. Fix implementation
/improve auth/ --safe-mode --validate
# → Safe improvements with validation
# 4. Verification testing
/test auth-flow/ --coverage
# → Comprehensive testing to ensure fix works
```
#### Code Quality Improvement
For improving existing code:
```bash
# 1. Quality assessment
/analyze legacy-code/ --focus quality
# → 🔄 refactorer persona identifies improvement opportunities
# For efficiency: compressed output with parallel processing
/analyze big-project/ --uc --delegate auto --concurrency 3
```
Remember: SuperClaude learns from successful patterns, so the more you use effective combinations, the better it gets at auto-activating the right approach for your needs.
---
## Integration & Coordination 🤝
Understanding how SuperClaude's components work together is key to using the framework effectively. This section shows you how commands, flags, personas, and MCP servers coordinate automatically - and how to control that coordination when needed.
### Auto-Coordination Examples 🤖
SuperClaude automatically coordinates components based on context. Here's how it works in practice:
#### Frontend Development Request
```bash
/build react-dashboard/
```
**Automatic coordination**:
- **Command**: `/build` handles compilation and bundling
# → Shows decision-making process and tool selection reasoning
```
### Best Practices for Integration 💡
#### Let Auto-Coordination Work First
- Trust SuperClaude's automatic tool selection
- Override only when you need specific perspectives
- Start with simple commands and add flags as needed
#### Understand Flag Interactions
- Some flags override others (`--no-mcp` overrides `--c7`, `--seq`)
- Safety flags take precedence over optimization flags
- Persona flags can be overridden by more specific persona requests
#### Use Appropriate Scope
- File-level: Single persona + minimal MCP
- Module-level: Domain personas + relevant MCP
- System-level: Multiple personas + full MCP coordination
#### Monitor Resource Usage
- Large operations → Use `--uc` and `--delegate`
- Simple tasks → Use `--no-mcp` and `--answer-only`
- Critical operations → Use `--safe-mode` and `--validate`
The key is understanding that SuperClaude's intelligence comes from the coordination between its components. The automatic coordination works well most of the time, but knowing how to control it gives you the flexibility to handle any situation.
---
## Practical Examples 💡
Real-world scenarios showing SuperClaude in action. These examples demonstrate how different components work together to solve common development problems.
### Scenario 1: New Team Member Onboarding 👋
**Situation**: You're starting work on an unfamiliar React/Node.js e-commerce project.
#### Step 1: Project Understanding
```bash
/load --deep --summary
```
**What happens**:
- 🔍 analyzer persona activates (investigation needed)
- Sequential MCP structures the analysis
- Context7 MCP identifies framework patterns
- Creates comprehensive project overview
**Output**: Project structure, tech stack, dependencies, and architecture summary.
#### Step 2: Code Quality Assessment
```bash
/scan --focus quality
```
**Auto-coordination**:
- 🧪 qa persona activates (quality focus)
- Sequential MCP provides systematic analysis
- Scans for code quality, security, and performance issues
Starting simple and adding complexity as needed (`--think` → `--think-hard` → `--ultrathink`).
#### Safety-First Approach
Critical operations automatically include validation and safety checks (`--safe-mode`, `--validate`).
#### Context-Aware Tool Selection
SuperClaude automatically chooses appropriate MCP servers and flags based on detected context.
These examples demonstrate that SuperClaude's value comes from intelligent coordination of its components rather than any single capability. The framework adapts to your needs while maintaining consistent quality and safety standards.
---
## Tips & Best Practices 🎯
Based on real-world usage patterns and successful workflows, here are practical tips for getting the most out of SuperClaude.
### Starting Out Successfully 🚀
#### Begin with Simple Commands
```bash
# Start here - basic functionality
/help
/analyze README.md
/build --help
# Not here - complex orchestration
/improve entire-codebase/ --wave-mode force --all-mcp --delegate auto
```
**Why**: Understanding basic behavior before adding complexity prevents confusion and helps you learn the framework gradually.
#### Trust Auto-Activation First
```bash
# Let SuperClaude choose tools
/analyze auth-system/
# → Watch what auto-activates (likely security persona + validation)
# Then experiment with manual control
/analyze auth-system/ --persona-performance
# → See different perspective on same code
```
**Why**: Auto-activation usually gets it right and shows you optimal tool combinations for different scenarios.
**Why**: Evidence-based development leads to better decisions and easier debugging when issues arise.
### Learning and Growth 📚
#### Use Mentor Persona for Learning
```bash
# Learn new concepts
/explain GraphQL --persona-mentor --verbose
# Understand complex code
/analyze complex-algorithm.js --persona-mentor
# Get step-by-step guidance
/build new-feature/ --persona-mentor --plan
```
**Why**: Mentor persona optimizes for understanding and knowledge transfer rather than just task completion.
#### Experiment with Different Approaches
```bash
# Try different personas on same problem
/analyze api-design/ --persona-architect
/analyze api-design/ --persona-security
/analyze api-design/ --persona-performance
# Compare tool combinations
/build app/ --magic --c7
/build app/ --no-mcp --uc # Faster but simpler
```
**Why**: Understanding different approaches helps you choose the best tools for different situations.
#### Build Your Own Patterns
```bash
# Identify what works for your workflow
# Security-focused API development
/design api --persona-security --validate
/build api --persona-backend --c7
/test api --type security --play
# Create your own efficient combinations
/analyze code/ --think --c7 --safe-mode # Your personal "thorough analysis"
```
**Why**: Developing your own proven patterns increases productivity and ensures consistent quality.
### Common Pitfalls to Avoid ⚠️
#### Don't Over-Engineer Simple Tasks
```bash
# ❌ Overkill for simple tasks
/analyze simple-utility.js --ultrathink --all-mcp --wave-mode force
# ✅ Appropriate for simple tasks
/analyze simple-utility.js --focus quality
```
#### Don't Ignore Auto-Activation Wisdom
```bash
# ❌ Fighting the system
/build react-app/ --persona-backend --no-magic # Wrong tools for the job
# ✅ Working with the system
/build react-app/ # Let frontend persona and Magic activate automatically
```
#### Don't Skip Safety for Speed
```bash
# ❌ Risky for important code
/improve production-auth/ --force --no-validate
# ✅ Balanced approach
/improve production-auth/ --safe-mode --validate # Safer but still efficient
```
#### Don't Use Flags You Don't Understand
```bash
# ❌ Cargo cult flag usage
/command --random-flags-that-look-important
# ✅ Understand what each flag does
/command --think # Because I need deeper analysis
/command --c7 # Because I'm working with external libraries
```
### Measuring Success 📊
Track what works well for your specific needs:
- **Speed**: How quickly do different flag combinations complete?
- **Quality**: Which approaches produce better results for your type of work?
- **Learning**: Which combinations help you understand problems better?
- **Safety**: Which patterns prevent issues in your environment?
Remember: SuperClaude learns from successful patterns, so using effective combinations consistently helps the framework get better at auto-activation for your specific workflow.
---
## Troubleshooting & Common Issues 🚨
When SuperClaude doesn't work as expected, here's how to diagnose and fix common problems.
### Command Issues 🛠️
#### Commands Not Working as Expected
**Problem**: Command produces unexpected results or seems to ignore your request.
**Diagnosis**:
```bash
# Check what auto-activated
/analyze code.js --introspect
# → Shows decision-making process
# Try with explicit control
/analyze code.js --persona-analyzer --think --seq
# → Override auto-activation
```
**Solutions**:
```bash
# Be more specific about what you want
/improve code.js --focus performance --safe-mode
# Use preview to understand what will happen
/improve code.js --preview
# Start simple and add complexity
/analyze code.js # Basic
/analyze code.js --think # Add depth
/analyze code.js --think --c7 # Add documentation
```
**Common Causes**:
- Auto-activation chose different tools than you expected
- Request was too vague for SuperClaude to understand intent
- Complexity mismatch (simple request with complex flags or vice versa)
#### Commands Running Too Slowly
**Problem**: Operations take much longer than expected.
Remember: When in doubt, start simple and add complexity gradually. Use `--introspect` to understand what SuperClaude is thinking, and don't hesitate to override auto-activation when you need specific behavior.
---
## What's Next 🔮
SuperClaude v3.0 is fresh out of beta, and we're honest about what that means: it works pretty well for what it does, but there are rough edges and room for improvement. Here's what you can expect as the framework evolves.
### Current Limitations (Let's Be Honest) ⚠️
#### Known Issues We're Working On
**Performance Optimization**
- Some operations are slower than we'd like, especially with all MCP servers active
- Token usage could be more efficient for large-scale operations
- Memory usage spikes on very large codebases (>1000 files)
**MCP Server Integration**
- Server connections occasionally timeout or become unresponsive
- Error handling between MCP servers could be smoother
- Some advanced MCP features are experimental and may not work reliably
**Quality Gates**
- The 8-step validation process sometimes misses edge cases
- Quality metrics could be more granular and actionable
- **Perfect AI**: SuperClaude will continue to have limitations and edge cases
- **One-Size-Fits-All**: Different projects and teams will need different approaches
- **Zero Learning Curve**: New features will require learning and experimentation
- **Magical Solutions**: Complex problems still require human expertise and judgment
### Contributing to SuperClaude 🤝
#### Ways to Help
- **Bug Reports**: Detailed reports help improve stability and reliability
- **Feature Requests**: Real-world needs drive development priorities
- **Documentation**: Examples, guides, and clarifications help the community
- **Community Support**: Helping other users builds a stronger ecosystem
#### What We Value Most
- **Honest Feedback**: Both positive experiences and frustrations help improve the framework
- **Real-World Usage**: How SuperClaude works (or doesn't work) in actual development workflows
- **Specific Examples**: Concrete scenarios are more valuable than abstract feature requests
- **Patience**: Remember that v3.0 is fresh out of beta - improvement takes time
### The Bottom Line 🎯
SuperClaude v3.0 is a solid foundation with room to grow. We're committed to:
- **Honest Communication**: No overpromising, clear about limitations and timelines
- **User-Driven Development**: Prioritizing features that solve real problems
- **Quality Over Features**: Making existing capabilities excellent before adding new ones
- **Community Focus**: Building a framework that serves the development community
We believe SuperClaude can become significantly more helpful for software development workflows, but it will take time, feedback, and iteration to get there. We appreciate your patience, feedback, and continued use as we improve the framework together.
**Want to stay involved?** Watch the GitHub repository, try new features when they're released, and let us know what works (and what doesn't) in your development workflows. Your real-world usage and feedback are what will make SuperClaude truly valuable for the development community.
---
## Conclusion 🎉
You've now got a comprehensive understanding of SuperClaude v3.0 - its components, capabilities, and how to use them effectively. Let's wrap up with the key takeaways that will help you get the most out of the framework.
### Key Takeaways 🎯
#### SuperClaude's Core Value
SuperClaude transforms Claude Code from a general-purpose AI assistant into a specialized development partner through:
- **15 specialized commands** that understand development workflows
- **11 expert personas** that bring domain-specific knowledge
- **Intelligent orchestration** that coordinates tools automatically
- **Quality-first approach** that maintains safety and reliability
#### The Magic is in the Coordination
SuperClaude's power comes not from any single feature, but from how components work together:
- Commands activate appropriate personas and MCP servers automatically
- Personas coordinate with each other for multi-domain problems
- The orchestrator optimizes tool selection and resource usage
- **General research**: Topics outside software development
- **Brainstorming**: Open-ended ideation without specific implementation needs
### The SuperClaude Philosophy 💭
#### Human-AI Collaboration
SuperClaude is designed to augment human expertise, not replace it:
- **You provide context and goals** - SuperClaude provides execution and expertise
- **You make decisions** - SuperClaude provides evidence and recommendations
- **You understand your constraints** - SuperClaude respects and works within them
- **You own the outcomes** - SuperClaude helps you achieve better results
#### Continuous Improvement
The framework gets better through:
- **Usage patterns**: Learning what combinations work well in practice
- **User feedback**: Real-world experiences drive development priorities
- **Evidence-based optimization**: Data-driven improvements to tools and workflows
- **Community contributions**: Shared knowledge and best practices
### Looking Forward 🔮
#### Short-Term (Next 6 Months)
- Performance optimizations making operations 30-50% faster
- Improved MCP server reliability reducing failures by 80%
- Enhanced quality gates providing more actionable feedback
- Better documentation based on user questions and feedback
#### Medium-Term (6-18 Months)
- Redesigned hooks system with better architecture and performance
- Smarter auto-activation based on learning from usage patterns
- Extended MCP ecosystem with community-contributed servers
- Advanced orchestration with true parallel processing
#### Long-Term Vision
- Deep contextual understanding of projects and team workflows
- Proactive assistance based on code analysis and project patterns
- Team-aware features for collaborative development
- Rich integration ecosystem with IDEs, CI/CD, and cloud platforms
### Final Thoughts 🎉
SuperClaude v3.0 represents a solid foundation for enhanced software development workflows. While it's not perfect and still has room for improvement, it demonstrates how AI can be thoughtfully integrated into development practices without disrupting existing workflows or replacing human expertise.
The framework succeeds when it makes you more productive, helps you learn new things, or catches issues you might have missed. It's designed to be a helpful colleague rather than a replacement for understanding your craft.
#### Thank You 🙏
Thanks for taking the time to understand SuperClaude thoroughly. Your thoughtful usage, honest feedback, and patience with rough edges are what will make this framework truly valuable for the development community.
Whether you use SuperClaude occasionally for specific tasks or integrate it deeply into your daily workflow, we hope it makes your development experience a bit better. And when it doesn't work as expected, please let us know - that feedback is invaluable for making improvements.
**Happy coding!** 🚀 We're excited to see what you build with SuperClaude as your development partner.
---
*Last updated: July 2024*
*SuperClaude v3.0 User Guide*
*For questions, feedback, or contributions, visit our GitHub repository or join the community discussions. We're always happy to hear from users and learn about your experiences with the framework.*
