mirror of
https://github.com/SuperClaude-Org/SuperClaude_Framework.git
synced 2025-12-29 16:16:08 +00:00
Restructure documentation: Create focused guide ecosystem from oversized user guide
- Transform 28K+ token superclaude-user-guide.md into 4.5K token overview (84% reduction) - Extract specialized guides: examples-cookbook.md, troubleshooting-guide.md, best-practices.md, session-management.md, technical-architecture.md - Add comprehensive cross-references between all guides for improved navigation - Maintain professional documentation quality with technical-writer agent approach - Remove template files and consolidate agent naming (backend-engineer → backend-architect, etc.) - Update all existing guides with cross-references and related guides sections - Create logical learning paths from beginner to advanced users - Eliminate content duplication while preserving all valuable information 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
NomenAK
@@ -25,7 +25,7 @@ The SuperClaude Framework features 13 specialized domain expert agents that auto
|
||||
/brainstorm "task manager app" # → Requirements analyst guides discovery
|
||||
```
|
||||
|
||||
**See the pattern?** You focus on what you want to do, SuperClaude figures out who should help.
|
||||
**See the pattern?** You focus on what you want to do, SuperClaude figures out who should help. See [Examples Cookbook](examples-cookbook.md) for many more examples like these.
|
||||
|
||||
---
|
||||
|
||||
@@ -518,4 +518,30 @@ Agents seamlessly integrate with SuperClaude's command system:
|
||||
|
||||
---
|
||||
|
||||
## Related Guides
|
||||
|
||||
**🚀 Getting Started (Essential)**
|
||||
- [SuperClaude User Guide](superclaude-user-guide.md) - Framework overview and philosophy
|
||||
- [Examples Cookbook](examples-cookbook.md) - See agents in action with real examples
|
||||
|
||||
**🛠️ Working with Agents (Recommended)**
|
||||
- [Commands Guide](commands-guide.md) - Commands that activate specific agents
|
||||
- [Behavioral Modes Guide](behavioral-modes-guide.md) - How agents work within different modes
|
||||
- [Session Management Guide](session-management.md) - Agent coordination across sessions
|
||||
|
||||
**⚙️ Control and Optimization (Advanced)**
|
||||
- [Flags Guide](flags-guide.md) - Manual agent control with --agent flags
|
||||
- [Best Practices Guide](best-practices.md) - Proven patterns for agent coordination
|
||||
- [Technical Architecture Guide](technical-architecture.md) - Agent system implementation
|
||||
|
||||
**🔧 When Things Go Wrong**
|
||||
- [Troubleshooting Guide](troubleshooting-guide.md) - Agent activation and coordination issues
|
||||
|
||||
**📖 Recommended Learning Path:**
|
||||
1. [Examples Cookbook](examples-cookbook.md) - See auto-activation in action
|
||||
2. [Commands Guide](commands-guide.md) - Understand agent triggers
|
||||
3. [Best Practices Guide](best-practices.md) - Master agent coordination patterns
|
||||
|
||||
---
|
||||
|
||||
*Behind this sophisticated team of 13 specialists, the SuperClaude Framework remains simple to use. Just start coding and the right experts show up when needed! 🚀*
|
||||
@@ -38,7 +38,7 @@
|
||||
/sc:improve --uc legacy-code/ # → Uses symbols, abbreviations, stays clear
|
||||
```
|
||||
|
||||
**See the pattern?** You just say what you want to do. SuperClaude figures out the best way to help. The modes are the "how" - you focus on the "what". 🎯
|
||||
**See the pattern?** You just say what you want to do. SuperClaude figures out the best way to help. The modes are the "how" - you focus on the "what". See [Examples Cookbook](examples-cookbook.md) for more working examples. 🎯
|
||||
|
||||
---
|
||||
|
||||
@@ -688,8 +688,26 @@ Modes determine the behavioral approach, agents provide domain expertise. A secu
|
||||
|
||||
---
|
||||
|
||||
**Related Guides:**
|
||||
- 🤖 [Agent System Guide](agents-guide.md) - Understanding the 13 specialized agents
|
||||
- 🛠️ [Commands Guide](commands-guide.md) - All 21 commands with mode integration
|
||||
- 🏳️ [Flags Guide](flags-guide.md) - Manual mode control and behavioral flags
|
||||
- 📖 [SuperClaude User Guide](superclaude-user-guide.md) - Complete framework overview
|
||||
## Related Guides
|
||||
|
||||
**🚀 Getting Started (Essential)**
|
||||
- [SuperClaude User Guide](superclaude-user-guide.md) - Framework overview and philosophy
|
||||
- [Examples Cookbook](examples-cookbook.md) - See modes in action with real examples
|
||||
|
||||
**🛠️ Working with Modes (Recommended)**
|
||||
- [Commands Guide](commands-guide.md) - Commands that trigger different modes
|
||||
- [Agents Guide](agents-guide.md) - How agents work within different modes
|
||||
- [Session Management Guide](session-management.md) - Mode persistence across sessions
|
||||
|
||||
**⚙️ Control and Optimization (Advanced)**
|
||||
- [Flags Guide](flags-guide.md) - Manual mode control with flags like --brainstorm, --uc
|
||||
- [Best Practices Guide](best-practices.md) - Proven patterns for mode utilization
|
||||
- [Technical Architecture Guide](technical-architecture.md) - Mode detection and activation system
|
||||
|
||||
**🔧 When Modes Don't Work as Expected**
|
||||
- [Troubleshooting Guide](troubleshooting-guide.md) - Mode activation and behavioral issues
|
||||
|
||||
**📖 Recommended Learning Path:**
|
||||
1. [Examples Cookbook](examples-cookbook.md) - See auto-activation in practice
|
||||
2. [Commands Guide](commands-guide.md) - Understand mode triggers
|
||||
3. [Best Practices Guide](best-practices.md) - Master mode coordination patterns
|
||||
945
Guides/best-practices.md
Normal file
945
Guides/best-practices.md
Normal file
@@ -0,0 +1,945 @@
|
||||
# SuperClaude Best Practices Guide
|
||||
|
||||
*A comprehensive guide to maximizing your effectiveness with SuperClaude through proven patterns and optimization strategies*
|
||||
|
||||
## Table of Contents
|
||||
|
||||
1. [Getting Started Right](#getting-started-right)
|
||||
2. [Command Mastery](#command-mastery)
|
||||
3. [Flag Optimization](#flag-optimization)
|
||||
4. [Agent Coordination](#agent-coordination)
|
||||
5. [MCP Server Strategy](#mcp-server-strategy)
|
||||
6. [Workflow Patterns](#workflow-patterns)
|
||||
7. [Performance Optimization](#performance-optimization)
|
||||
8. [Quality & Safety](#quality--safety)
|
||||
9. [Advanced Patterns](#advanced-patterns)
|
||||
10. [Learning & Growth](#learning--growth)
|
||||
|
||||
---
|
||||
|
||||
## Getting Started Right
|
||||
|
||||
### The SuperClaude Mindset
|
||||
|
||||
**Core Principle**: SuperClaude is designed to handle complexity for you. Focus on expressing your intent clearly, and let the system optimize execution. For working examples of these principles, see [Examples Cookbook](examples-cookbook.md).
|
||||
|
||||
**✅ DO**: Trust the intelligent routing system
|
||||
- Just type `/analyze auth.js` - SuperClaude picks appropriate tools
|
||||
- Use basic commands first, learn advanced features gradually
|
||||
- Let behavioral modes activate automatically
|
||||
|
||||
**❌ DON'T**: Try to micromanage every detail
|
||||
- Don't memorize all flags and agents upfront
|
||||
- Don't specify tools unless you need to override defaults
|
||||
- Don't overcomplicate simple tasks
|
||||
|
||||
### Essential First Session Pattern
|
||||
|
||||
```bash
|
||||
# The proven startup sequence
|
||||
/sc:load # Initialize session with project context
|
||||
/sc:analyze . # Understand project structure and patterns
|
||||
/sc:brainstorm "goals" # Interactive discovery for unclear requirements
|
||||
/sc:implement feature # Development with auto-optimization
|
||||
/sc:save # Persist session insights
|
||||
```
|
||||
|
||||
**Why this works**: Establishes persistent context, gathers intelligence, enables cross-session learning.
|
||||
|
||||
### Foundation Practices
|
||||
|
||||
**Session Initialization**
|
||||
```bash
|
||||
# Always start sessions properly
|
||||
/sc:load --deep # Deep project understanding
|
||||
/sc:load --summary # Quick context for familiar projects
|
||||
```
|
||||
|
||||
**Evidence-Based Development**
|
||||
```bash
|
||||
# Validate before building
|
||||
/sc:analyze existing-code # Understand patterns first
|
||||
/sc:test --coverage # Verify current state
|
||||
/sc:implement feature # Build on solid foundation
|
||||
/sc:test feature # Validate implementation
|
||||
```
|
||||
|
||||
**Progressive Enhancement**
|
||||
```bash
|
||||
# Start simple, add complexity intelligently
|
||||
/sc:build # Basic implementation
|
||||
/sc:improve --performance # Targeted optimization
|
||||
/sc:test --comprehensive # Full validation
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Command Mastery
|
||||
|
||||
### Essential Command Patterns
|
||||
|
||||
**Analysis Commands** - Understanding before action
|
||||
```bash
|
||||
/sc:analyze path --focus domain # Targeted analysis
|
||||
/sc:explain complex-code.js # Educational breakdown
|
||||
/sc:troubleshoot "specific issue" # Problem investigation
|
||||
```
|
||||
|
||||
**Development Commands** - Building with intelligence
|
||||
```bash
|
||||
/sc:implement feature-name # Smart feature creation
|
||||
/sc:build --optimize # Optimized builds
|
||||
/sc:design component --type ui # Architecture/UI design
|
||||
```
|
||||
|
||||
**Quality Commands** - Maintaining excellence
|
||||
```bash
|
||||
/sc:improve legacy-code/ # Systematic improvement
|
||||
/sc:cleanup technical-debt/ # Targeted cleanup
|
||||
/sc:test --with-coverage # Quality validation
|
||||
```
|
||||
|
||||
### Command Combination Strategies
|
||||
|
||||
**Analysis → Implementation Pattern**
|
||||
```bash
|
||||
/sc:analyze auth/ --focus security # Understand security landscape
|
||||
/sc:implement user-auth --secure # Build with security insights
|
||||
/sc:test auth --security # Validate security implementation
|
||||
```
|
||||
|
||||
**Brainstorm → Design → Implement Pattern**
|
||||
```bash
|
||||
/sc:brainstorm "user dashboard" # Requirements discovery
|
||||
/sc:design dashboard --type component # Architecture planning
|
||||
/sc:implement dashboard # Informed implementation
|
||||
```
|
||||
|
||||
**Load → Analyze → Improve Pattern**
|
||||
```bash
|
||||
/sc:load --deep # Establish context
|
||||
/sc:analyze . --focus quality # Identify improvement areas
|
||||
/sc:improve problematic-areas/ # Systematic enhancement
|
||||
```
|
||||
|
||||
### Command Selection Matrix
|
||||
|
||||
| Task Type | Primary Command | Secondary Commands | Expected Outcome |
|
||||
|-----------|----------------|-------------------|------------------|
|
||||
| **New Feature** | `/sc:implement` | `/sc:design`, `/sc:test` | Complete working feature |
|
||||
| **Code Issues** | `/sc:troubleshoot` | `/sc:analyze`, `/sc:improve` | Root cause + solution |
|
||||
| **Quality Problems** | `/sc:improve` | `/sc:cleanup`, `/sc:test` | Enhanced code quality |
|
||||
| **Architecture Review** | `/sc:analyze --focus architecture` | `/sc:reflect`, `/sc:document` | System understanding |
|
||||
| **Unclear Requirements** | `/sc:brainstorm` | `/sc:estimate`, `/sc:task` | Clear specifications |
|
||||
|
||||
---
|
||||
|
||||
## Flag Optimization
|
||||
|
||||
### Flag Selection Strategy
|
||||
|
||||
**Core Principle**: Flags should enhance, not complicate. Most flags activate automatically - use manual flags only for overrides or specific needs.
|
||||
|
||||
### High-Impact Flag Combinations
|
||||
|
||||
**Deep Analysis Pattern**
|
||||
```bash
|
||||
/sc:analyze codebase/ --think-hard --focus architecture --validate
|
||||
# Triggers: Sequential MCP + Context7 + Architecture agent + validation gates
|
||||
# Result: Comprehensive system analysis with safety checks
|
||||
```
|
||||
|
||||
**Performance Optimization Pattern**
|
||||
```bash
|
||||
/sc:improve app/ --focus performance --loop --iterations 3
|
||||
# Triggers: Performance engineer + iterative improvement cycles
|
||||
# Result: Systematically optimized performance with measurement
|
||||
```
|
||||
|
||||
**Security Assessment Pattern**
|
||||
```bash
|
||||
/sc:analyze auth/ --focus security --ultrathink --safe-mode
|
||||
# Triggers: Security engineer + Sequential MCP + maximum validation
|
||||
# Result: Comprehensive security analysis with conservative execution
|
||||
```
|
||||
|
||||
### Flag Efficiency Rules
|
||||
|
||||
**Flag Priority Hierarchy**
|
||||
1. **Safety flags** (`--safe-mode`, `--validate`) - Always take precedence
|
||||
2. **Scope flags** (`--scope project`) - Define boundaries first
|
||||
3. **Focus flags** (`--focus security`) - Target expertise second
|
||||
4. **Optimization flags** (`--loop`, `--uc`) - Enhance performance last
|
||||
|
||||
**Automatic vs Manual Flags**
|
||||
- **Let auto-activate**: `--brainstorm`, `--introspect`, `--orchestrate`
|
||||
- **Manually specify**: `--focus`, `--scope`, `--think-hard`
|
||||
- **Rarely needed**: `--concurrency`, `--iterations`
|
||||
|
||||
### Flag Combination Templates
|
||||
|
||||
**For Complex Debugging**
|
||||
```bash
|
||||
/sc:troubleshoot issue --think-hard --focus root-cause --validate
|
||||
```
|
||||
|
||||
**For Large Codebase Analysis**
|
||||
```bash
|
||||
/sc:analyze . --delegate auto --scope project --uc
|
||||
```
|
||||
|
||||
**For Production Changes**
|
||||
```bash
|
||||
/sc:implement feature --safe-mode --validate --with-tests
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Agent Coordination
|
||||
|
||||
### Understanding Agent Auto-Activation
|
||||
|
||||
**How Agent Selection Works**
|
||||
1. **Request Analysis**: SuperClaude analyzes your request for domain keywords
|
||||
2. **Context Evaluation**: Considers project type, files involved, previous session history
|
||||
3. **Agent Matching**: Activates appropriate specialist based on expertise mapping
|
||||
4. **Multi-Agent Coordination**: Enables multiple agents for cross-domain issues
|
||||
|
||||
### Strategic Agent Usage
|
||||
|
||||
**Single-Domain Tasks** - Let auto-activation work
|
||||
```bash
|
||||
/sc:analyze auth.js # → Security Engineer
|
||||
/sc:implement responsive-navbar # → Frontend Architect
|
||||
/sc:troubleshoot performance-issue # → Performance Engineer
|
||||
```
|
||||
|
||||
**Multi-Domain Tasks** - Strategic combinations
|
||||
```bash
|
||||
/sc:implement payment-system # → Backend + Security + Quality Engineers
|
||||
/sc:analyze system-architecture # → System + Performance + Security Architects
|
||||
/sc:improve legacy-application # → Quality + Refactoring + System experts
|
||||
```
|
||||
|
||||
### Agent Coordination Patterns
|
||||
|
||||
**Security-First Development**
|
||||
```bash
|
||||
/sc:analyze codebase --focus security # Security Engineer analyzes
|
||||
/sc:implement auth --secure # Security Engineer oversees implementation
|
||||
/sc:test auth --security # Security + Quality Engineers validate
|
||||
```
|
||||
|
||||
**Performance-Driven Optimization**
|
||||
```bash
|
||||
/sc:analyze performance-bottlenecks # Performance Engineer identifies issues
|
||||
/sc:improve slow-components # Performance + Quality Engineers optimize
|
||||
/sc:test performance --benchmarks # Performance Engineer validates improvements
|
||||
```
|
||||
|
||||
**Architecture Evolution**
|
||||
```bash
|
||||
/sc:analyze current-architecture # System Architect reviews existing design
|
||||
/sc:design new-architecture # System + Domain Architects collaborate
|
||||
/sc:implement migration-plan # Multiple specialists coordinate transition
|
||||
```
|
||||
|
||||
### Agent Specialization Matrix
|
||||
|
||||
| Domain | Primary Agent | Supporting Agents | Best Commands |
|
||||
|--------|---------------|------------------|---------------|
|
||||
| **Security** | Security Engineer | Quality Engineer, Root Cause Analyst | `/sc:analyze --focus security` |
|
||||
| **Performance** | Performance Engineer | System Architect, Quality Engineer | `/sc:improve --focus performance` |
|
||||
| **Frontend** | Frontend Architect | Quality Engineer, Learning Guide | `/sc:design --type component` |
|
||||
| **Backend** | Backend Architect | Security Engineer, Performance Engineer | `/sc:implement --type api` |
|
||||
| **Architecture** | System Architect | Performance Engineer, Security Engineer | `/sc:analyze --focus architecture` |
|
||||
| **Quality** | Quality Engineer | Refactoring Expert, Root Cause Analyst | `/sc:improve --with-tests` |
|
||||
|
||||
---
|
||||
|
||||
## MCP Server Strategy
|
||||
|
||||
### MCP Server Selection Matrix
|
||||
|
||||
**Choose MCP servers based on task complexity and domain requirements**
|
||||
|
||||
| Task Type | Recommended MCP | Alternative | Trigger Conditions |
|
||||
|-----------|----------------|-------------|-------------------|
|
||||
| **UI Components** | Magic | Manual coding | UI keywords, React/Vue mentions |
|
||||
| **Complex Analysis** | Sequential | Native reasoning | >3 components, architectural questions |
|
||||
| **Documentation Lookup** | Context7 | Web search | Import statements, framework questions |
|
||||
| **Code Editing** | Morphllm | Individual edits | >3 files, pattern-based changes |
|
||||
| **Symbol Operations** | Serena | Manual search | Refactoring, large codebase navigation |
|
||||
| **Browser Testing** | Playwright | Unit tests | E2E scenarios, visual validation |
|
||||
|
||||
### High-Performance MCP Combinations
|
||||
|
||||
**Frontend Development Stack**
|
||||
```bash
|
||||
# Magic + Context7 + Sequential
|
||||
/sc:implement dashboard component --magic --c7 --seq
|
||||
# Magic generates UI → Context7 provides framework patterns → Sequential coordinates
|
||||
```
|
||||
|
||||
**Backend Analysis Stack**
|
||||
```bash
|
||||
# Sequential + Context7 + Serena
|
||||
/sc:analyze api-architecture --seq --c7 --serena
|
||||
# Sequential structures analysis → Context7 provides docs → Serena maps dependencies
|
||||
```
|
||||
|
||||
**Quality Improvement Stack**
|
||||
```bash
|
||||
# Morphllm + Serena + Sequential
|
||||
/sc:improve legacy-codebase --morph --serena --seq
|
||||
# Sequential plans improvements → Serena maps symbols → Morphllm applies changes
|
||||
```
|
||||
|
||||
### MCP Optimization Strategies
|
||||
|
||||
**Token Efficiency with MCP**
|
||||
- Use `--uc` flag with complex MCP operations
|
||||
- Sequential + Morphllm combination provides compressed analysis
|
||||
- Magic components reduce UI implementation tokens significantly
|
||||
|
||||
**Parallel MCP Processing**
|
||||
```bash
|
||||
# Enable concurrent MCP server usage
|
||||
/sc:analyze frontend/ --magic --c7 --concurrency 5
|
||||
```
|
||||
|
||||
**MCP Server Resource Management**
|
||||
```bash
|
||||
# Conservative MCP usage for production
|
||||
/sc:implement feature --safe-mode --validate
|
||||
# Auto-enables appropriate MCP servers with safety constraints
|
||||
```
|
||||
|
||||
### When NOT to Use MCP Servers
|
||||
|
||||
**Simple tasks that don't benefit from external tools:**
|
||||
- Basic explanations: "explain this function"
|
||||
- Single file edits: "fix this typo"
|
||||
- General questions: "what is React?"
|
||||
- Quick analysis: "is this code correct?"
|
||||
|
||||
**Use `--no-mcp` flag when:**
|
||||
- Performance is critical and you need fastest response
|
||||
- Working in air-gapped environments
|
||||
- Simple tasks where MCP overhead isn't justified
|
||||
- Debugging MCP-related issues
|
||||
|
||||
---
|
||||
|
||||
## Workflow Patterns
|
||||
|
||||
### The Universal SuperClaude Workflow
|
||||
|
||||
**Phase 1: Context Establishment**
|
||||
```bash
|
||||
/sc:load --deep # Initialize project understanding
|
||||
/sc:analyze . --scope project # Map current state
|
||||
```
|
||||
|
||||
**Phase 2: Requirement Clarification**
|
||||
```bash
|
||||
/sc:brainstorm "unclear requirements" # Interactive discovery
|
||||
/sc:estimate task-scope # Resource planning
|
||||
```
|
||||
|
||||
**Phase 3: Implementation**
|
||||
```bash
|
||||
/sc:implement features # Development with auto-optimization
|
||||
/sc:test implementation # Quality validation
|
||||
```
|
||||
|
||||
**Phase 4: Iteration & Persistence**
|
||||
```bash
|
||||
/sc:improve --loop # Continuous enhancement
|
||||
/sc:save --checkpoint # Preserve insights
|
||||
```
|
||||
|
||||
### Domain-Specific Workflows
|
||||
|
||||
**New Project Setup**
|
||||
```bash
|
||||
/sc:load --deep # Understand project structure
|
||||
/sc:analyze . --focus architecture # Map existing patterns
|
||||
/sc:brainstorm "development goals" # Clarify objectives
|
||||
/sc:task "setup development env" # Plan setup tasks
|
||||
/sc:build --optimize # Establish build pipeline
|
||||
/sc:document --type guide "setup" # Create setup documentation
|
||||
/sc:save # Preserve project insights
|
||||
```
|
||||
|
||||
**Feature Development**
|
||||
```bash
|
||||
/sc:load # Load project context
|
||||
/sc:brainstorm "feature idea" # Requirements discovery
|
||||
/sc:design feature --type component # Architecture planning
|
||||
/sc:implement feature # Development with validation
|
||||
/sc:test feature --comprehensive # Quality assurance
|
||||
/sc:improve feature --performance # Optimization
|
||||
/sc:document feature # Documentation
|
||||
/sc:save --checkpoint # Save session state
|
||||
```
|
||||
|
||||
**Bug Investigation & Resolution**
|
||||
```bash
|
||||
/sc:load --summary # Quick context loading
|
||||
/sc:troubleshoot "bug description" # Root cause analysis
|
||||
/sc:analyze affected-areas # Impact assessment
|
||||
/sc:implement fix --validate # Safe fix implementation
|
||||
/sc:test fix --comprehensive # Comprehensive validation
|
||||
/sc:reflect --type completion # Verify resolution
|
||||
/sc:save # Persist insights
|
||||
```
|
||||
|
||||
**Code Quality Improvement**
|
||||
```bash
|
||||
/sc:load # Establish context
|
||||
/sc:analyze . --focus quality # Identify quality issues
|
||||
/sc:improve problem-areas/ # Systematic improvements
|
||||
/sc:cleanup technical-debt/ # Debt reduction
|
||||
/sc:test --coverage # Validation with coverage
|
||||
/sc:reflect --type quality # Quality assessment
|
||||
/sc:save # Preserve improvements
|
||||
```
|
||||
|
||||
### Workflow Optimization Principles
|
||||
|
||||
**Parallelization Opportunities**
|
||||
```bash
|
||||
# Parallel analysis
|
||||
/sc:analyze frontend/ & # Background frontend analysis
|
||||
/sc:analyze backend/ & # Background backend analysis
|
||||
/sc:analyze tests/ & # Background test analysis
|
||||
wait && /sc:reflect --type summary # Consolidate findings
|
||||
```
|
||||
|
||||
**Checkpoint Strategy**
|
||||
- **Every 30 minutes**: `/sc:save --checkpoint`
|
||||
- **Before risky operations**: `/sc:save --backup`
|
||||
- **After major completions**: `/sc:save --milestone`
|
||||
- **End of sessions**: `/sc:save --final`
|
||||
|
||||
**Context Preservation**
|
||||
```bash
|
||||
# Start of each session
|
||||
/sc:load --recent # Load recent context
|
||||
/sc:reflect --type session-start # Understand current state
|
||||
|
||||
# End of each session
|
||||
/sc:reflect --type completion # Assess achievements
|
||||
/sc:save --insights # Preserve learnings
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Performance Optimization
|
||||
|
||||
### Token Efficiency Strategies
|
||||
|
||||
**Automatic Token Optimization**
|
||||
SuperClaude automatically enables token efficiency when:
|
||||
- Context usage >75%
|
||||
- Large-scale operations (>50 files)
|
||||
- Complex multi-step workflows
|
||||
|
||||
**Manual Token Optimization**
|
||||
```bash
|
||||
/sc:analyze large-codebase --uc # Ultra-compressed analysis
|
||||
/sc:implement complex-feature --token-efficient # Compressed implementation
|
||||
```
|
||||
|
||||
**Symbol Communication Patterns**
|
||||
When token efficiency mode activates, expect:
|
||||
- `✅ ❌ ⚠️` for status indicators
|
||||
- `→ ⇒ ⇄` for logic flow
|
||||
- `🔍 🔧 ⚡ 🛡️` for domain indicators
|
||||
- Abbreviated technical terms: `cfg`, `impl`, `perf`, `arch`
|
||||
|
||||
### Execution Speed Optimization
|
||||
|
||||
**Parallel Processing Templates**
|
||||
```bash
|
||||
# Multiple file analysis
|
||||
/sc:analyze src/ tests/ docs/ --concurrency 8
|
||||
|
||||
# Batch operations
|
||||
/sc:improve file1.js file2.js file3.js --batch
|
||||
|
||||
# Delegated processing for large projects
|
||||
/sc:analyze . --delegate auto --scope project
|
||||
```
|
||||
|
||||
**Resource-Aware Processing**
|
||||
```bash
|
||||
# Conservative resource usage
|
||||
/sc:build --safe-mode # Auto-limits resource usage
|
||||
|
||||
# Controlled concurrency
|
||||
/sc:test --concurrency 3 # Explicit concurrency limits
|
||||
|
||||
# Priority-based processing
|
||||
/sc:improve critical/ --priority high
|
||||
```
|
||||
|
||||
### Memory and Context Optimization
|
||||
|
||||
**Session Context Management**
|
||||
```bash
|
||||
# Lightweight context for familiar projects
|
||||
/sc:load --summary
|
||||
|
||||
# Deep context for complex projects
|
||||
/sc:load --deep
|
||||
|
||||
# Context compression for large projects
|
||||
/sc:load --uc
|
||||
```
|
||||
|
||||
**Progressive Context Building**
|
||||
```bash
|
||||
# Start minimal, build context progressively
|
||||
/sc:load --minimal # Basic project loading
|
||||
/sc:analyze core-areas # Focus on essential components
|
||||
/sc:load --expand critical-paths # Expand context as needed
|
||||
```
|
||||
|
||||
### Performance Measurement
|
||||
|
||||
**Built-in Performance Tracking**
|
||||
```bash
|
||||
# Commands automatically track performance metrics:
|
||||
/sc:analyze . --performance-metrics
|
||||
/sc:build --timing
|
||||
/sc:test --benchmark
|
||||
```
|
||||
|
||||
**Performance Validation Patterns**
|
||||
```bash
|
||||
# Before optimization
|
||||
/sc:analyze performance-bottlenecks --baseline
|
||||
|
||||
# After optimization
|
||||
/sc:test performance --compare-baseline
|
||||
|
||||
# Continuous monitoring
|
||||
/sc:reflect --type performance --trend
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Quality & Safety
|
||||
|
||||
### Safety-First Development
|
||||
|
||||
**Core Safety Principles**
|
||||
1. **Validate before execution** - Always run analysis before changes
|
||||
2. **Incremental changes** - Small, verifiable steps over large changes
|
||||
3. **Rollback capability** - Maintain ability to undo changes
|
||||
4. **Evidence-based decisions** - All claims must be verifiable
|
||||
|
||||
**Critical Safety Patterns**
|
||||
```bash
|
||||
# Always check git status first
|
||||
git status && git branch
|
||||
|
||||
# Read before any file operations
|
||||
/sc:analyze file.js # Understand before changing
|
||||
|
||||
# Use safe mode for production changes
|
||||
/sc:implement feature --safe-mode
|
||||
|
||||
# Create checkpoints before risky operations
|
||||
/sc:save --backup && /sc:implement risky-change
|
||||
```
|
||||
|
||||
### Quality Assurance Patterns
|
||||
|
||||
**Quality Gates Framework**
|
||||
```bash
|
||||
# Analysis quality gate
|
||||
/sc:analyze code --validate # Validates analysis accuracy
|
||||
|
||||
# Implementation quality gate
|
||||
/sc:implement feature --with-tests # Includes quality validation
|
||||
|
||||
# Deployment quality gate
|
||||
/sc:build --quality-check # Pre-deployment validation
|
||||
```
|
||||
|
||||
**Comprehensive Testing Strategy**
|
||||
```bash
|
||||
# Unit testing
|
||||
/sc:test components/ --unit
|
||||
|
||||
# Integration testing
|
||||
/sc:test api/ --integration
|
||||
|
||||
# E2E testing (triggers Playwright MCP)
|
||||
/sc:test user-flows/ --e2e
|
||||
|
||||
# Security testing
|
||||
/sc:test auth/ --security
|
||||
|
||||
# Performance testing
|
||||
/sc:test critical-paths/ --performance
|
||||
```
|
||||
|
||||
### Error Prevention & Recovery
|
||||
|
||||
**Proactive Error Prevention**
|
||||
```bash
|
||||
# Validate before risky operations
|
||||
/sc:analyze risky-area --focus safety --validate
|
||||
|
||||
# Use conservative execution for critical systems
|
||||
/sc:implement critical-feature --safe-mode --validate
|
||||
|
||||
# Enable comprehensive testing
|
||||
/sc:test critical-feature --comprehensive --security
|
||||
```
|
||||
|
||||
**Error Recovery Patterns**
|
||||
```bash
|
||||
# Systematic debugging approach
|
||||
/sc:troubleshoot error --think-hard --root-cause
|
||||
|
||||
# Multi-perspective analysis
|
||||
/sc:analyze error-context --focus debugging --ultrathink
|
||||
|
||||
# Validated fix implementation
|
||||
/sc:implement fix --validate --with-tests --safe-mode
|
||||
```
|
||||
|
||||
### Code Quality Standards
|
||||
|
||||
**Quality Enforcement Rules**
|
||||
- **No partial features** - Complete everything you start
|
||||
- **No TODO comments** - Finish implementations, don't leave placeholders
|
||||
- **No mock implementations** - Build real, working code
|
||||
- **Evidence-based claims** - All technical statements must be verifiable
|
||||
|
||||
**Quality Validation Commands**
|
||||
```bash
|
||||
# Code quality assessment
|
||||
/sc:analyze . --focus quality --comprehensive
|
||||
|
||||
# Technical debt identification
|
||||
/sc:analyze . --focus debt --report
|
||||
|
||||
# Quality improvement planning
|
||||
/sc:improve low-quality-areas/ --plan
|
||||
|
||||
# Quality trend analysis
|
||||
/sc:reflect --type quality --trend
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Advanced Patterns
|
||||
|
||||
### Multi-Layer Orchestration
|
||||
|
||||
**Complex Project Coordination**
|
||||
```bash
|
||||
# Enable advanced orchestration for large projects
|
||||
/sc:task "modernize legacy system" --orchestrate --delegate auto
|
||||
|
||||
# Multi-agent coordination for cross-domain problems
|
||||
/sc:implement payment-system --all-mcp --think-hard --safe-mode
|
||||
|
||||
# Systematic refactoring with multiple specialists
|
||||
/sc:improve legacy-codebase/ --delegate folders --loop --iterations 5
|
||||
```
|
||||
|
||||
**Resource-Constrained Optimization**
|
||||
```bash
|
||||
# Maximum efficiency for large operations
|
||||
/sc:analyze enterprise-codebase --uc --delegate auto --concurrency 15
|
||||
|
||||
# Token-optimized multi-step workflows
|
||||
/sc:task complex-migration --token-efficient --orchestrate
|
||||
|
||||
# Performance-optimized batch processing
|
||||
/sc:improve multiple-modules/ --batch --performance-mode
|
||||
```
|
||||
|
||||
### Session Lifecycle Mastery
|
||||
|
||||
**Advanced Session Management**
|
||||
```bash
|
||||
# Intelligent session initialization
|
||||
/sc:load --adaptive # Adapts loading strategy to project complexity
|
||||
|
||||
# Cross-session learning
|
||||
/sc:reflect --type learning # Extract insights for future sessions
|
||||
|
||||
# Session comparison and evolution
|
||||
/sc:reflect --type evolution --compare-previous
|
||||
|
||||
# Advanced checkpointing
|
||||
/sc:save --milestone "major feature complete" --analytics
|
||||
```
|
||||
|
||||
**Session Intelligence Patterns**
|
||||
```bash
|
||||
# Context-aware session resumption
|
||||
/sc:load --context-aware # Resumes with intelligent context
|
||||
|
||||
# Predictive session planning
|
||||
/sc:task session-goals --predict-resources --estimate-time
|
||||
|
||||
# Session optimization recommendations
|
||||
/sc:reflect --type optimization --recommendations
|
||||
```
|
||||
|
||||
### Expert-Level Command Combinations
|
||||
|
||||
**Architecture Evolution Workflow**
|
||||
```bash
|
||||
/sc:load --deep
|
||||
/sc:analyze current-architecture --ultrathink --focus architecture
|
||||
/sc:design target-architecture --think-hard --validate
|
||||
/sc:task migration-plan --orchestrate --delegate auto
|
||||
/sc:implement migration --safe-mode --validate --loop
|
||||
/sc:test migration --comprehensive --performance
|
||||
/sc:reflect --type architecture --evolution
|
||||
/sc:save --milestone "architecture evolved"
|
||||
```
|
||||
|
||||
**Security Hardening Workflow**
|
||||
```bash
|
||||
/sc:load --security-focused
|
||||
/sc:analyze . --focus security --ultrathink --all-mcp
|
||||
/sc:troubleshoot security-vulnerabilities --think-hard --root-cause
|
||||
/sc:implement security-fixes --safe-mode --validate --with-tests
|
||||
/sc:test security/ --security --comprehensive --e2e
|
||||
/sc:reflect --type security --assessment
|
||||
/sc:save --security-audit-complete
|
||||
```
|
||||
|
||||
**Performance Optimization Workflow**
|
||||
```bash
|
||||
/sc:load --performance-focused
|
||||
/sc:analyze performance-bottlenecks --focus performance --think-hard
|
||||
/sc:implement optimizations --validate --loop --iterations 3
|
||||
/sc:test performance --benchmark --compare-baseline
|
||||
/sc:reflect --type performance --improvement-metrics
|
||||
/sc:save --performance-optimized
|
||||
```
|
||||
|
||||
### Custom Workflow Development
|
||||
|
||||
**Creating Repeatable Patterns**
|
||||
```bash
|
||||
# Define custom workflow templates
|
||||
/sc:task "define code-review workflow" --template
|
||||
|
||||
# Parameterized workflow execution
|
||||
/sc:execute code-review-workflow --target auth/ --depth comprehensive
|
||||
|
||||
# Workflow optimization and refinement
|
||||
/sc:improve workflow-template --based-on results
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Learning & Growth
|
||||
|
||||
### Progressive Learning Strategy
|
||||
|
||||
**Phase 1: Foundation (Weeks 1-2)**
|
||||
- Master basic commands: `/sc:load`, `/sc:analyze`, `/sc:implement`, `/sc:save`
|
||||
- Trust auto-activation - don't manually manage flags and agents
|
||||
- Establish consistent session patterns
|
||||
- Focus on quality workflows over advanced features
|
||||
|
||||
**Phase 2: Specialization (Weeks 3-6)**
|
||||
- Experiment with domain-specific commands for your primary work
|
||||
- Learn flag combinations that enhance your specific workflows
|
||||
- Understand when different agents activate and why
|
||||
- Develop personal workflow templates
|
||||
|
||||
**Phase 3: Optimization (Weeks 7-12)**
|
||||
- Master advanced flag combinations for complex scenarios
|
||||
- Leverage MCP servers for specialized tasks
|
||||
- Develop multi-session workflows with persistent context
|
||||
- Create custom orchestration patterns
|
||||
|
||||
**Phase 4: Expertise (Months 4+)**
|
||||
- Design sophisticated multi-agent coordination workflows
|
||||
- Optimize for token efficiency and performance at scale
|
||||
- Mentor others using proven patterns you've developed
|
||||
- Contribute workflow innovations back to the community
|
||||
|
||||
### Learning Acceleration Techniques
|
||||
|
||||
**Experimentation Framework**
|
||||
```bash
|
||||
# Try unfamiliar commands in safe environments
|
||||
/sc:analyze sample-project --think-hard # Observe how deep analysis works
|
||||
/sc:brainstorm "imaginary project" # See requirements discovery in action
|
||||
/sc:reflect --type learning # Review what you learned
|
||||
```
|
||||
|
||||
**Pattern Recognition Development**
|
||||
- **Notice auto-activations**: Pay attention to which agents and flags activate automatically
|
||||
- **Compare approaches**: Try the same task with different commands/flags
|
||||
- **Measure outcomes**: Use reflection commands to assess effectiveness
|
||||
- **Document discoveries**: Save insights about what works best for your projects
|
||||
|
||||
**Knowledge Reinforcement Patterns**
|
||||
```bash
|
||||
# Weekly learning review
|
||||
/sc:reflect --type learning --timeframe week
|
||||
|
||||
# Monthly skill assessment
|
||||
/sc:reflect --type skills --improvement-areas
|
||||
|
||||
# Quarterly workflow optimization
|
||||
/sc:reflect --type workflows --optimization-opportunities
|
||||
```
|
||||
|
||||
### Building Expertise
|
||||
|
||||
**Advanced Skill Development Areas**
|
||||
|
||||
**1. Agent Coordination Mastery**
|
||||
- Learn to predict which agents will activate for different requests
|
||||
- Understand cross-domain collaboration patterns
|
||||
- Develop skills in manual agent coordination for edge cases
|
||||
|
||||
**2. MCP Server Optimization**
|
||||
- Master the decision matrix for when to use each MCP server
|
||||
- Learn optimal MCP combinations for complex workflows
|
||||
- Understand performance implications of different MCP strategies
|
||||
|
||||
**3. Performance Engineering**
|
||||
- Develop intuition for token efficiency opportunities
|
||||
- Master parallel processing and resource optimization
|
||||
- Learn to balance quality vs. speed based on context
|
||||
|
||||
**4. Quality Assurance Excellence**
|
||||
- Internalize quality gate patterns for different project types
|
||||
- Develop systematic testing strategies using SuperClaude
|
||||
- Master error prevention and recovery patterns
|
||||
|
||||
### Continuous Improvement Framework
|
||||
|
||||
**Self-Assessment Questions**
|
||||
- Which SuperClaude patterns save you the most time?
|
||||
- What types of problems do you still solve manually that could be automated?
|
||||
- How has your code quality improved since using SuperClaude systematically?
|
||||
- Which advanced features haven't you explored yet that might benefit your work?
|
||||
|
||||
**Measurement Strategies**
|
||||
```bash
|
||||
# Track productivity improvements
|
||||
/sc:reflect --type productivity --baseline vs-current
|
||||
|
||||
# Assess code quality trends
|
||||
/sc:reflect --type quality --trend-analysis
|
||||
|
||||
# Measure learning velocity
|
||||
/sc:reflect --type learning --skill-development
|
||||
```
|
||||
|
||||
**Community Engagement**
|
||||
- Share effective workflow patterns you discover
|
||||
- Learn from others' optimization strategies
|
||||
- Contribute to SuperClaude documentation improvements
|
||||
- Mentor newcomers using proven teaching patterns
|
||||
|
||||
---
|
||||
|
||||
## Quick Reference
|
||||
|
||||
### Essential Commands Cheat Sheet
|
||||
```bash
|
||||
# Session Management
|
||||
/sc:load # Initialize session context
|
||||
/sc:save # Persist session insights
|
||||
/sc:reflect # Review session outcomes
|
||||
|
||||
# Core Development
|
||||
/sc:analyze path # Intelligent analysis
|
||||
/sc:implement feature # Smart implementation
|
||||
/sc:improve code # Systematic enhancement
|
||||
/sc:test target # Comprehensive testing
|
||||
|
||||
# Problem Solving
|
||||
/sc:brainstorm topic # Requirements discovery
|
||||
/sc:troubleshoot issue # Root cause analysis
|
||||
/sc:explain concept # Educational breakdown
|
||||
```
|
||||
|
||||
### High-Impact Flag Combinations
|
||||
```bash
|
||||
--think-hard --focus domain --validate # Deep domain analysis with safety
|
||||
--safe-mode --with-tests --quality-check # Production-ready implementation
|
||||
--uc --orchestrate --delegate auto # Large-scale efficient processing
|
||||
--loop --iterations 3 --performance # Iterative optimization cycles
|
||||
```
|
||||
|
||||
### Emergency Troubleshooting
|
||||
```bash
|
||||
# When things go wrong
|
||||
/sc:troubleshoot issue --ultrathink --safe-mode --root-cause
|
||||
|
||||
# When performance is critical
|
||||
/sc:analyze problem --uc --no-mcp --focus performance
|
||||
|
||||
# When you need maximum safety
|
||||
/sc:implement fix --safe-mode --validate --with-tests --quality-check
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Conclusion
|
||||
|
||||
SuperClaude's power lies in its intelligent automation of complex development workflows. The key to mastery is:
|
||||
|
||||
1. **Trust the automation** - Let SuperClaude handle complexity while you focus on intent
|
||||
2. **Start simple** - Master basic patterns before exploring advanced features
|
||||
3. **Learn progressively** - Add sophistication as your understanding deepens
|
||||
4. **Measure outcomes** - Use reflection to validate that your patterns actually improve results
|
||||
5. **Stay curious** - Experiment with new approaches and contribute discoveries back to the community
|
||||
|
||||
Remember: These best practices emerge from real usage. The most valuable patterns are often discovered through experimentation and adapted to your specific context. Use this guide as a foundation, but don't hesitate to develop your own optimized workflows based on your unique needs and discoveries.
|
||||
|
||||
**Start with the essentials, trust the intelligence, and let your expertise emerge through practice.**
|
||||
|
||||
## Related Guides
|
||||
|
||||
**🚀 Foundation (Essential Before Best Practices)**
|
||||
- [Installation Guide](installation-guide.md) - Get SuperClaude set up properly
|
||||
- [SuperClaude User Guide](superclaude-user-guide.md) - Understanding the framework philosophy
|
||||
- [Examples Cookbook](examples-cookbook.md) - Working examples to practice with
|
||||
|
||||
**📚 Core Knowledge (Apply These Practices)**
|
||||
- [Commands Guide](commands-guide.md) - All 21 commands with optimization opportunities
|
||||
- [Session Management Guide](session-management.md) - Session lifecycle mastery
|
||||
- [Agents Guide](agents-guide.md) - Agent coordination best practices
|
||||
|
||||
**⚙️ Advanced Optimization (Power User Techniques)**
|
||||
- [Flags Guide](flags-guide.md) - Advanced flag combinations and control
|
||||
- [Behavioral Modes Guide](behavioral-modes-guide.md) - Mode coordination patterns
|
||||
- [Technical Architecture Guide](technical-architecture.md) - System understanding for optimization
|
||||
|
||||
**🔧 Quality and Safety (Prevention Strategies)**
|
||||
- [Troubleshooting Guide](troubleshooting-guide.md) - Prevention patterns and issue avoidance
|
||||
|
||||
**📖 How to Use This Guide:**
|
||||
1. Start with [Getting Started Right](#getting-started-right) for foundational patterns
|
||||
2. Apply [Command Mastery](#command-mastery) to your daily workflow
|
||||
3. Use [Workflow Patterns](#workflow-patterns) for specific development scenarios
|
||||
4. Graduate to [Advanced Patterns](#advanced-patterns) for complex projects
|
||||
|
||||
**🎯 Implementation Strategy:**
|
||||
- **Week 1-2**: Focus on [Getting Started Right](#getting-started-right) and basic [Command Mastery](#command-mastery)
|
||||
- **Week 3-4**: Implement [Workflow Patterns](#workflow-patterns) for your common tasks
|
||||
- **Month 2**: Explore [Agent Coordination](#agent-coordination) and [MCP Server Strategy](#mcp-server-strategy)
|
||||
- **Month 3+**: Master [Advanced Patterns](#advanced-patterns) and [Performance Optimization](#performance-optimization)
|
||||
@@ -37,7 +37,7 @@ SuperClaude commands work by:
|
||||
/sc:save --checkpoint # Save your work and progress
|
||||
```
|
||||
|
||||
**That's honestly enough to get started.** Everything else below is here when you get curious about what other tools are available. 🛠️
|
||||
**That's honestly enough to get started.** Everything else below is here when you get curious about what other tools are available. For step-by-step examples, see [Examples Cookbook](examples-cookbook.md). 🛠️
|
||||
|
||||
---
|
||||
|
||||
@@ -53,14 +53,14 @@ A practical guide to all 21 SuperClaude v4.0.0 slash commands. We'll be honest a
|
||||
| `/sc:build` | Intelligent building | Frontend/backend specialists | Compilation, bundling, deployment prep |
|
||||
| `/sc:implement` | Feature implementation | Domain-specific experts | Creating features, components, APIs, services |
|
||||
| `/sc:improve` | Automatic code cleanup | Quality experts | Refactoring, optimization, quality fixes |
|
||||
| `/sc:troubleshoot` | Problem investigation | Debug specialists | Debugging, issue investigation |
|
||||
| `/sc:troubleshoot` | Problem investigation | Debug specialists | Debugging, issue investigation ([Troubleshooting Guide](troubleshooting-guide.md)) |
|
||||
| `/sc:test` | Smart testing | QA experts | Running tests, coverage analysis |
|
||||
| `/sc:document` | Auto documentation | Writing specialists | README files, code comments, guides |
|
||||
| `/sc:git` | Enhanced git workflows | DevOps specialists | Smart commits, branch management |
|
||||
| `/sc:design` | System design help | Architecture experts | Architecture planning, API design |
|
||||
| `/sc:explain` | Learning assistant | Teaching specialists | Learning concepts, understanding code |
|
||||
| `/sc:cleanup` | Debt reduction | Refactoring experts | Removing dead code, organizing files |
|
||||
| `/sc:load` | Context understanding | Analysis experts | Project analysis, codebase understanding |
|
||||
| `/sc:load` | Context understanding | Analysis experts | Project analysis, session initialization ([Session Management Guide](session-management.md)) |
|
||||
| `/sc:estimate` | Smart estimation | Planning experts | Time/effort planning, complexity analysis |
|
||||
| `/sc:spawn` | Complex workflows | Orchestration system | Multi-step operations, workflow automation |
|
||||
| `/sc:task` | Project management | Planning system | Long-term feature planning, task tracking |
|
||||
@@ -948,7 +948,34 @@ A practical guide to all 21 SuperClaude v4.0.0 slash commands. We'll be honest a
|
||||
- Commands suggest what they can do when you use `--help`
|
||||
- The intelligent routing handles most of the complexity
|
||||
|
||||
**Need help?** Check the GitHub issues or create a new one if you're stuck! 🚀
|
||||
**Need help?** Check the [Troubleshooting Guide](troubleshooting-guide.md) or GitHub issues if you're stuck! 🚀
|
||||
|
||||
## Related Guides
|
||||
|
||||
**🚀 Getting Started (Essential)**
|
||||
- [Installation Guide](installation-guide.md) - Get SuperClaude set up first
|
||||
- [Examples Cookbook](examples-cookbook.md) - Copy-paste working examples for all commands
|
||||
- [SuperClaude User Guide](superclaude-user-guide.md) - Complete framework overview
|
||||
|
||||
**🤝 Understanding the Team (Recommended)**
|
||||
- [Agents Guide](agents-guide.md) - The 13 specialists that work with commands
|
||||
- [Behavioral Modes Guide](behavioral-modes-guide.md) - How commands adapt automatically
|
||||
- [Session Management Guide](session-management.md) - Persistent context with /sc:load and /sc:save
|
||||
|
||||
**⚙️ Control and Optimization (Advanced)**
|
||||
- [Flags Guide](flags-guide.md) - All the --flags that modify command behavior
|
||||
- [Best Practices Guide](best-practices.md) - Proven command combinations and workflows
|
||||
|
||||
**🔧 When Commands Don't Work**
|
||||
- [Troubleshooting Guide](troubleshooting-guide.md) - Common command issues and solutions
|
||||
|
||||
**🏗️ Technical Deep Dive (Optional)**
|
||||
- [Technical Architecture Guide](technical-architecture.md) - How the command system works internally
|
||||
|
||||
**📖 Recommended Learning Path:**
|
||||
1. [Examples Cookbook](examples-cookbook.md) - Try commands with working examples
|
||||
2. [Session Management Guide](session-management.md) - Learn /sc:load and /sc:save workflow
|
||||
3. [Best Practices Guide](best-practices.md) - Master effective command patterns
|
||||
|
||||
## Command Flags & Options
|
||||
|
||||
|
||||
808
Guides/examples-cookbook.md
Normal file
808
Guides/examples-cookbook.md
Normal file
@@ -0,0 +1,808 @@
|
||||
# SuperClaude Examples Cookbook 🍳
|
||||
|
||||
*A practical guide to real-world SuperClaude usage with hands-on examples*
|
||||
|
||||
## How to Use This Cookbook
|
||||
|
||||
This cookbook is your **practical reference** for using SuperClaude effectively. Unlike comprehensive guides, this focuses entirely on **working examples** and **real scenarios** you can try immediately.
|
||||
|
||||
**Structure:**
|
||||
- **Quick Examples** - One-liner commands for common tasks
|
||||
- **Development Scenarios** - Complete workflows for typical development situations
|
||||
- **Troubleshooting Scenarios** - Real problem-solving examples
|
||||
- **Advanced Patterns** - Complex multi-step workflows
|
||||
- **Command Combinations** - Effective flag and agent combinations
|
||||
- **Best Practices in Action** - Examples showing optimal SuperClaude usage
|
||||
|
||||
**How to read this:**
|
||||
- 📋 **Copy-paste commands** - All examples are working commands you can use
|
||||
- 🎯 **Expected outcomes** - What you should see after running each command
|
||||
- 💡 **Why it works** - Brief explanation of the approach
|
||||
- ⚠️ **Gotchas** - Common issues and how to avoid them
|
||||
|
||||
---
|
||||
|
||||
## Quick Examples - Just Try These! 🚀
|
||||
|
||||
### Essential One-Liners
|
||||
```bash
|
||||
# Initialize and understand your project
|
||||
/sc:load # Load project context
|
||||
/sc:analyze . # Analyze entire project
|
||||
/sc:build # Smart build with auto-optimization
|
||||
|
||||
# Development workflows
|
||||
/sc:implement user-auth # Create authentication system
|
||||
/sc:improve messy-file.js # Clean up code automatically
|
||||
/sc:troubleshoot "login not working" # Debug specific issues
|
||||
|
||||
# Session management
|
||||
/sc:save --checkpoint # Save progress with analysis
|
||||
/sc:reflect --type completion # Validate task completion
|
||||
```
|
||||
|
||||
### Quick Analysis Commands
|
||||
```bash
|
||||
# Security focus
|
||||
/sc:analyze src/auth --focus security --depth deep
|
||||
|
||||
# Performance analysis
|
||||
/sc:analyze --focus performance --format report
|
||||
|
||||
# Quick quality check
|
||||
/sc:analyze src/components --focus quality --depth quick
|
||||
|
||||
# Architecture review
|
||||
/sc:analyze --focus architecture .
|
||||
```
|
||||
|
||||
### Rapid Development Commands
|
||||
```bash
|
||||
# UI components (triggers Magic MCP + Frontend agent)
|
||||
/sc:implement dashboard component --type component --framework react
|
||||
|
||||
# API development (triggers Backend agent + Context7)
|
||||
/sc:implement user management API --type api --safe
|
||||
|
||||
# Full features (triggers multiple agents)
|
||||
/sc:implement payment processing --type feature --with-tests
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Development Scenarios 📋
|
||||
|
||||
### Scenario 1: New Team Member Onboarding
|
||||
|
||||
**Situation**: New developer joining project, needs to understand codebase and setup development environment.
|
||||
|
||||
**Step-by-step workflow:**
|
||||
|
||||
```bash
|
||||
# 1. Initialize session and load project context
|
||||
/sc:load --deep --summary
|
||||
# 🎯 Expected: Comprehensive project analysis with structure, tech stack, and key components
|
||||
|
||||
# 2. Understand architecture and dependencies
|
||||
/sc:analyze --focus architecture
|
||||
# 🎯 Expected: System design overview, dependency mapping, and component relationships
|
||||
|
||||
# 3. Check code quality and identify areas needing attention
|
||||
/sc:analyze --focus quality --format report
|
||||
# 🎯 Expected: HTML report with quality metrics, technical debt, and improvement areas
|
||||
|
||||
# 4. Verify test coverage and quality
|
||||
/sc:test --coverage
|
||||
# 🎯 Expected: Test execution results with coverage percentages and missing test areas
|
||||
|
||||
# 5. Generate onboarding documentation
|
||||
/sc:document --type guide "getting started with this project"
|
||||
# 🎯 Expected: Comprehensive getting started guide with setup instructions
|
||||
|
||||
# 6. Save insights for future reference
|
||||
/sc:save --checkpoint "onboarding analysis complete"
|
||||
# 🎯 Expected: Session saved with all analysis insights and documentation
|
||||
```
|
||||
|
||||
**💡 Why this works:**
|
||||
- `/sc:load --deep` activates comprehensive project analysis
|
||||
- Multiple analysis focuses provide complete understanding
|
||||
- Documentation generation creates permanent reference materials
|
||||
- Session persistence preserves insights for future use
|
||||
|
||||
**⚠️ Gotchas:**
|
||||
- Large projects may take time for deep analysis
|
||||
- Test command requires existing test configuration
|
||||
- Documentation quality depends on project structure clarity
|
||||
|
||||
---
|
||||
|
||||
### Scenario 2: Security Vulnerability Investigation
|
||||
|
||||
**Situation**: Security scan flagged potential vulnerabilities, need systematic investigation and remediation.
|
||||
|
||||
**Step-by-step workflow:**
|
||||
|
||||
```bash
|
||||
# 1. Initialize focused security analysis
|
||||
/sc:analyze --focus security --depth deep
|
||||
# 🎯 Expected: Comprehensive security vulnerability assessment with severity ratings
|
||||
|
||||
# 2. Investigate specific suspicious components
|
||||
/sc:troubleshoot "potential SQL injection in user queries" --type security --trace
|
||||
# 🎯 Expected: Systematic analysis of SQL injection vectors and vulnerable code patterns
|
||||
|
||||
# 3. Analyze authentication and authorization systems
|
||||
/sc:analyze src/auth --focus security --format report
|
||||
# 🎯 Expected: Detailed auth security analysis with specific vulnerability details
|
||||
|
||||
# 4. Apply security improvements
|
||||
/sc:improve auth-service --type security --safe
|
||||
# 🎯 Expected: Automatic application of security best practices and vulnerability fixes
|
||||
|
||||
# 5. Validate security improvements with testing
|
||||
/sc:test --type security
|
||||
# 🎯 Expected: Security-focused test execution with validation of fixes
|
||||
|
||||
# 6. Document security findings and remediation
|
||||
/sc:document --type report "security vulnerability assessment"
|
||||
# 🎯 Expected: Comprehensive security report with findings and remediation steps
|
||||
|
||||
# 7. Save security analysis for compliance
|
||||
/sc:save --type security-audit "vulnerability remediation complete"
|
||||
# 🎯 Expected: Complete security audit trail saved for future reference
|
||||
```
|
||||
|
||||
**💡 Why this works:**
|
||||
- Security-focused analysis activates Security Engineer agent automatically
|
||||
- Systematic troubleshooting provides comprehensive investigation methodology
|
||||
- Safe improvements apply fixes without breaking existing functionality
|
||||
- Documentation creates audit trail for compliance requirements
|
||||
|
||||
**⚠️ Gotchas:**
|
||||
- Security analysis may flag false positives requiring manual review
|
||||
- Improvements should be tested thoroughly before production deployment
|
||||
- Complex security issues may require expert security engineer consultation
|
||||
|
||||
---
|
||||
|
||||
### Scenario 3: Performance Optimization Sprint
|
||||
|
||||
**Situation**: Application performance has degraded, need systematic optimization across frontend and backend.
|
||||
|
||||
**Step-by-step workflow:**
|
||||
|
||||
```bash
|
||||
# 1. Comprehensive performance baseline analysis
|
||||
/sc:analyze --focus performance --depth deep
|
||||
# 🎯 Expected: Performance bottleneck identification with specific metrics and recommendations
|
||||
|
||||
# 2. Profile API performance issues
|
||||
/sc:troubleshoot "API response times degraded" --type performance
|
||||
# 🎯 Expected: Systematic analysis of API bottlenecks, database queries, and caching issues
|
||||
|
||||
# 3. Optimize backend performance
|
||||
/sc:improve api-endpoints --type performance --interactive
|
||||
# 🎯 Expected: Performance engineer provides optimization recommendations with guided implementation
|
||||
|
||||
# 4. Optimize frontend bundle and rendering
|
||||
/sc:improve src/components --type performance --safe
|
||||
# 🎯 Expected: Frontend optimization including code splitting, lazy loading, and rendering improvements
|
||||
|
||||
# 5. Build optimized production artifacts
|
||||
/sc:build --type prod --optimize --verbose
|
||||
# 🎯 Expected: Optimized production build with minification, tree-shaking, and performance analysis
|
||||
|
||||
# 6. Validate performance improvements with testing
|
||||
/sc:test --type performance --coverage
|
||||
# 🎯 Expected: Performance test execution with before/after metrics comparison
|
||||
|
||||
# 7. Monitor and document optimization results
|
||||
/sc:reflect --type completion "performance optimization"
|
||||
# 🎯 Expected: Validation of optimization effectiveness with recommendations for monitoring
|
||||
|
||||
# 8. Save optimization insights and metrics
|
||||
/sc:save --checkpoint "performance optimization sprint complete"
|
||||
# 🎯 Expected: Complete optimization documentation with metrics and ongoing monitoring recommendations
|
||||
```
|
||||
|
||||
**💡 Why this works:**
|
||||
- Performance focus automatically activates Performance Engineer agent
|
||||
- Interactive improvements provide guided optimization decisions
|
||||
- Production build validation ensures optimizations work in deployment
|
||||
- Comprehensive testing validates improvement effectiveness
|
||||
|
||||
**⚠️ Gotchas:**
|
||||
- Performance improvements may introduce subtle bugs requiring thorough testing
|
||||
- Production builds should be tested in staging environment first
|
||||
- Performance metrics should be monitored continuously after deployment
|
||||
|
||||
---
|
||||
|
||||
### Scenario 4: Legacy Code Modernization
|
||||
|
||||
**Situation**: Large legacy codebase needs modernization to current standards and frameworks.
|
||||
|
||||
**Step-by-step workflow:**
|
||||
|
||||
```bash
|
||||
# 1. Assess legacy codebase comprehensively
|
||||
/sc:load --deep --summary
|
||||
# 🎯 Expected: Complete legacy system analysis with technology stack assessment
|
||||
|
||||
# 2. Identify modernization opportunities and technical debt
|
||||
/sc:analyze --focus architecture --depth deep
|
||||
# 🎯 Expected: Technical debt assessment with modernization recommendations and migration strategy
|
||||
|
||||
# 3. Plan systematic modernization approach
|
||||
/sc:select-tool "migrate 100+ files to TypeScript" --analyze
|
||||
# 🎯 Expected: Tool selection recommendations for large-scale code transformation
|
||||
|
||||
# 4. Begin with code quality improvements
|
||||
/sc:improve legacy-modules --type maintainability --preview
|
||||
# 🎯 Expected: Preview of maintainability improvements without applying changes
|
||||
|
||||
# 5. Apply safe modernization improvements
|
||||
/sc:improve legacy-modules --type maintainability --safe
|
||||
# 🎯 Expected: Application of safe refactoring and modernization patterns
|
||||
|
||||
# 6. Clean up technical debt systematically
|
||||
/sc:cleanup src/ --dead-code --safe
|
||||
# 🎯 Expected: Removal of dead code, unused imports, and outdated patterns
|
||||
|
||||
# 7. Validate modernization with comprehensive testing
|
||||
/sc:test --type all --coverage
|
||||
# 🎯 Expected: Complete test suite execution with coverage analysis
|
||||
|
||||
# 8. Document modernization progress and next steps
|
||||
/sc:document --type report "legacy modernization progress"
|
||||
# 🎯 Expected: Comprehensive modernization report with completed work and future recommendations
|
||||
|
||||
# 9. Save modernization insights for iterative improvement
|
||||
/sc:save --checkpoint "legacy modernization phase 1"
|
||||
# 🎯 Expected: Complete modernization context saved for continued iterative improvement
|
||||
```
|
||||
|
||||
**💡 Why this works:**
|
||||
- Deep analysis provides comprehensive understanding of legacy system complexity
|
||||
- Tool selection optimization ensures efficient modernization approach
|
||||
- Preview mode allows safe exploration of changes before application
|
||||
- Iterative approach with checkpoints enables manageable modernization process
|
||||
|
||||
**⚠️ Gotchas:**
|
||||
- Large legacy systems require multiple iteration cycles
|
||||
- Preview changes carefully before applying to critical systems
|
||||
- Comprehensive testing essential to prevent breaking legacy functionality
|
||||
- Modernization should be planned in phases to manage risk
|
||||
|
||||
---
|
||||
|
||||
### Scenario 5: Multi-Team API Design
|
||||
|
||||
**Situation**: Multiple teams need to collaborate on API design requiring coordination across frontend, backend, and security concerns.
|
||||
|
||||
**Step-by-step workflow:**
|
||||
|
||||
```bash
|
||||
# 1. Brainstorm API requirements with stakeholder exploration
|
||||
/sc:brainstorm "multi-service API architecture" --strategy enterprise --depth deep
|
||||
# 🎯 Expected: Comprehensive requirements discovery with cross-team considerations
|
||||
|
||||
# 2. Generate structured API implementation workflow
|
||||
/sc:workflow api-requirements.md --strategy systematic --parallel
|
||||
# 🎯 Expected: Detailed implementation plan with multi-team coordination and dependencies
|
||||
|
||||
# 3. Design API architecture with security considerations
|
||||
/sc:design --type api user-management --format spec
|
||||
# 🎯 Expected: Formal API specification with security, performance, and integration considerations
|
||||
|
||||
# 4. Implement API with multi-domain expertise
|
||||
/sc:implement user management API --type api --with-tests --safe
|
||||
# 🎯 Expected: Complete API implementation with automated testing and security validation
|
||||
|
||||
# 5. Validate API design with cross-team testing
|
||||
/sc:test --type integration --coverage
|
||||
# 🎯 Expected: Integration testing with frontend/backend coordination validation
|
||||
|
||||
# 6. Generate comprehensive API documentation
|
||||
/sc:document --type api src/controllers/ --style detailed
|
||||
# 🎯 Expected: Complete API documentation with usage examples and integration guidance
|
||||
|
||||
# 7. Reflect on multi-team coordination effectiveness
|
||||
/sc:reflect --type completion "API design collaboration"
|
||||
# 🎯 Expected: Analysis of coordination effectiveness with recommendations for future collaboration
|
||||
|
||||
# 8. Save API design insights for team knowledge sharing
|
||||
/sc:save --type collaboration "multi-team API design complete"
|
||||
# 🎯 Expected: Complete API design context saved for future multi-team projects
|
||||
```
|
||||
|
||||
**💡 Why this works:**
|
||||
- Brainstorming mode facilitates cross-team requirements discovery
|
||||
- Workflow generation provides structured coordination approach
|
||||
- Multi-persona activation ensures comprehensive domain coverage
|
||||
- Documentation supports ongoing team collaboration
|
||||
|
||||
**⚠️ Gotchas:**
|
||||
- Multi-team coordination requires clear communication channels
|
||||
- API design decisions should be validated with all stakeholder teams
|
||||
- Integration testing requires coordination of development environments
|
||||
- Documentation should be maintained as API evolves
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting Scenarios 🔧
|
||||
|
||||
### Problem: Build Failures After Dependency Updates
|
||||
|
||||
**Symptoms**: Build process failing with cryptic error messages after updating dependencies.
|
||||
|
||||
**Troubleshooting workflow:**
|
||||
|
||||
```bash
|
||||
# 1. Systematic build failure investigation
|
||||
/sc:troubleshoot "TypeScript compilation errors" --type build --trace
|
||||
# 🎯 Expected: Systematic analysis of build logs and TypeScript configuration issues
|
||||
|
||||
# 2. Analyze dependency compatibility
|
||||
/sc:analyze package.json --focus dependencies
|
||||
# 🎯 Expected: Dependency conflict analysis with compatibility recommendations
|
||||
|
||||
# 3. Attempt automatic build fixes
|
||||
/sc:troubleshoot "build failing" --type build --fix
|
||||
# 🎯 Expected: Application of common build fixes with validation
|
||||
|
||||
# 4. Clean build with optimization
|
||||
/sc:build --clean --verbose
|
||||
# 🎯 Expected: Clean build execution with detailed error analysis
|
||||
```
|
||||
|
||||
**💡 Why this works:** Systematic troubleshooting provides structured diagnosis, automatic fixes handle common issues, verbose output reveals detailed error information.
|
||||
|
||||
---
|
||||
|
||||
### Problem: Authentication System Security Vulnerabilities
|
||||
|
||||
**Symptoms**: Security scan revealed potential authentication vulnerabilities.
|
||||
|
||||
**Troubleshooting workflow:**
|
||||
|
||||
```bash
|
||||
# 1. Deep security analysis of authentication system
|
||||
/sc:analyze src/auth --focus security --depth deep
|
||||
# 🎯 Expected: Comprehensive security vulnerability assessment with specific findings
|
||||
|
||||
# 2. Investigate specific authentication vulnerabilities
|
||||
/sc:troubleshoot "JWT token vulnerability" --type security --trace
|
||||
# 🎯 Expected: Systematic analysis of JWT implementation with security recommendations
|
||||
|
||||
# 3. Apply security hardening improvements
|
||||
/sc:improve auth-service --type security --safe
|
||||
# 🎯 Expected: Application of security best practices and vulnerability fixes
|
||||
|
||||
# 4. Validate security fixes with testing
|
||||
/sc:test --type security auth-tests/
|
||||
# 🎯 Expected: Security-focused testing with validation of vulnerability fixes
|
||||
```
|
||||
|
||||
**💡 Why this works:** Security-focused analysis activates security expertise, systematic troubleshooting provides comprehensive investigation, safe improvements ensure no functionality breaks.
|
||||
|
||||
---
|
||||
|
||||
### Problem: Performance Degradation in Production
|
||||
|
||||
**Symptoms**: Application response times increased significantly in production environment.
|
||||
|
||||
**Troubleshooting workflow:**
|
||||
|
||||
```bash
|
||||
# 1. Performance bottleneck identification
|
||||
/sc:troubleshoot "API response times degraded" --type performance
|
||||
# 🎯 Expected: Systematic performance analysis with bottleneck identification
|
||||
|
||||
# 2. Analyze performance across application layers
|
||||
/sc:analyze --focus performance --format report
|
||||
# 🎯 Expected: Comprehensive performance report with optimization recommendations
|
||||
|
||||
# 3. Optimize critical performance paths
|
||||
/sc:improve api-endpoints --type performance --interactive
|
||||
# 🎯 Expected: Performance optimization with guided decision-making
|
||||
|
||||
# 4. Validate performance improvements
|
||||
/sc:test --type performance --coverage
|
||||
# 🎯 Expected: Performance testing with before/after metrics comparison
|
||||
```
|
||||
|
||||
**💡 Why this works:** Performance-focused troubleshooting provides systematic bottleneck analysis, interactive improvements guide complex optimization decisions, testing validates improvement effectiveness.
|
||||
|
||||
---
|
||||
|
||||
## Advanced Patterns 🎓
|
||||
|
||||
### Pattern: Cross-Session Project Development
|
||||
|
||||
**Use case**: Working on complex features across multiple development sessions with context preservation.
|
||||
|
||||
```bash
|
||||
# Session 1: Requirements and Planning
|
||||
/sc:load # Initialize project context
|
||||
/sc:brainstorm "user dashboard feature" --prd # Explore requirements
|
||||
/sc:workflow dashboard-requirements.md # Generate implementation plan
|
||||
/sc:save --checkpoint "dashboard planning" # Save planning context
|
||||
|
||||
# Session 2: Implementation Start
|
||||
/sc:load # Resume project context
|
||||
/sc:implement dashboard component --type component --framework react
|
||||
/sc:save --checkpoint "dashboard component created"
|
||||
|
||||
# Session 3: Testing and Refinement
|
||||
/sc:load # Resume project context
|
||||
/sc:test dashboard-component --coverage # Validate implementation
|
||||
/sc:improve dashboard-component --type quality --safe
|
||||
/sc:save --checkpoint "dashboard implementation complete"
|
||||
|
||||
# Session 4: Integration and Documentation
|
||||
/sc:load # Resume project context
|
||||
/sc:reflect --type completion "dashboard feature"
|
||||
/sc:document --type component dashboard-component
|
||||
/sc:save "dashboard feature complete"
|
||||
```
|
||||
|
||||
**💡 Why this works:** Session persistence maintains context across development cycles, checkpoints provide recovery points, progressive enhancement builds on previous work.
|
||||
|
||||
---
|
||||
|
||||
### Pattern: Multi-Tool Complex Analysis
|
||||
|
||||
**Use case**: Complex system analysis requiring coordination of multiple specialized tools and expertise.
|
||||
|
||||
```bash
|
||||
# Step 1: Intelligent tool selection for complex task
|
||||
/sc:select-tool "comprehensive security and performance audit" --analyze
|
||||
# 🎯 Expected: Recommended tool combination and coordination strategy
|
||||
|
||||
# Step 2: Coordinated multi-domain analysis
|
||||
/sc:analyze --focus security --depth deep &
|
||||
/sc:analyze --focus performance --depth deep &
|
||||
/sc:analyze --focus architecture --depth deep
|
||||
# 🎯 Expected: Parallel analysis across multiple domains
|
||||
|
||||
# Step 3: Systematic troubleshooting with expert coordination
|
||||
/sc:troubleshoot "complex system behavior" --type system --sequential
|
||||
# 🎯 Expected: Structured debugging with multiple expert perspectives
|
||||
|
||||
# Step 4: Comprehensive improvement with validation
|
||||
/sc:improve . --type quality --interactive --validate
|
||||
# 🎯 Expected: Guided improvements with comprehensive validation gates
|
||||
```
|
||||
|
||||
**💡 Why this works:** Tool selection optimization ensures efficient approach, parallel analysis maximizes efficiency, expert coordination provides comprehensive coverage.
|
||||
|
||||
---
|
||||
|
||||
### Pattern: Large-Scale Code Transformation
|
||||
|
||||
**Use case**: Systematic transformation of large codebase with pattern-based changes.
|
||||
|
||||
```bash
|
||||
# Step 1: Analyze scope and plan transformation approach
|
||||
/sc:select-tool "migrate 100+ files to TypeScript" --efficiency
|
||||
# 🎯 Expected: Optimal tool selection for large-scale transformation
|
||||
|
||||
# Step 2: Systematic transformation with progress tracking
|
||||
/sc:spawn migrate-typescript --parallel --monitor
|
||||
# 🎯 Expected: Parallel transformation with progress monitoring
|
||||
|
||||
# Step 3: Validate transformation quality and completeness
|
||||
/sc:test --type all --coverage
|
||||
/sc:analyze --focus quality transformed-files/
|
||||
# 🎯 Expected: Comprehensive validation of transformation quality
|
||||
|
||||
# Step 4: Cleanup and optimization post-transformation
|
||||
/sc:cleanup transformed-files/ --safe
|
||||
/sc:improve transformed-files/ --type maintainability --safe
|
||||
# 🎯 Expected: Final cleanup and optimization of transformed code
|
||||
```
|
||||
|
||||
**💡 Why this works:** Scope analysis ensures appropriate tool selection, parallel processing maximizes efficiency, comprehensive validation ensures quality maintenance.
|
||||
|
||||
---
|
||||
|
||||
## Command Combinations That Work Well 🔗
|
||||
|
||||
### Security-Focused Development Workflow
|
||||
```bash
|
||||
# Analysis → Improvement → Validation → Documentation
|
||||
/sc:analyze --focus security --depth deep
|
||||
/sc:improve src/ --type security --safe
|
||||
/sc:test --type security --coverage
|
||||
/sc:document --type security-guide
|
||||
```
|
||||
|
||||
### Performance Optimization Workflow
|
||||
```bash
|
||||
# Profiling → Optimization → Building → Validation
|
||||
/sc:analyze --focus performance --format report
|
||||
/sc:improve api/ --type performance --interactive
|
||||
/sc:build --type prod --optimize
|
||||
/sc:test --type performance
|
||||
```
|
||||
|
||||
### Quality Improvement Workflow
|
||||
```bash
|
||||
# Assessment → Preview → Application → Cleanup → Testing
|
||||
/sc:analyze --focus quality
|
||||
/sc:improve src/ --type quality --preview
|
||||
/sc:improve src/ --type quality --safe
|
||||
/sc:cleanup src/ --safe
|
||||
/sc:test --coverage
|
||||
```
|
||||
|
||||
### New Feature Development Workflow
|
||||
```bash
|
||||
# Planning → Implementation → Testing → Documentation → Session Save
|
||||
/sc:brainstorm "feature idea" --prd
|
||||
/sc:implement feature-name --type feature --with-tests
|
||||
/sc:test feature-tests/ --coverage
|
||||
/sc:document --type feature feature-name
|
||||
/sc:save --checkpoint "feature complete"
|
||||
```
|
||||
|
||||
### Legacy Code Modernization Workflow
|
||||
```bash
|
||||
# Assessment → Planning → Safe Improvement → Cleanup → Validation
|
||||
/sc:load --deep --summary
|
||||
/sc:select-tool "legacy modernization" --analyze
|
||||
/sc:improve legacy/ --type maintainability --preview
|
||||
/sc:improve legacy/ --type maintainability --safe
|
||||
/sc:cleanup legacy/ --safe
|
||||
/sc:test --type all
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Best Practices in Action 🌟
|
||||
|
||||
### Effective Flag Usage Patterns
|
||||
|
||||
**Safe Development Pattern:**
|
||||
```bash
|
||||
# Always preview before applying changes
|
||||
/sc:improve src/ --preview # See what would change
|
||||
/sc:improve src/ --safe # Apply only safe changes
|
||||
/sc:test --coverage # Validate changes work
|
||||
```
|
||||
|
||||
**Progressive Analysis Pattern:**
|
||||
```bash
|
||||
# Start broad, then focus deep
|
||||
/sc:analyze . # Quick overview
|
||||
/sc:analyze src/auth --focus security --depth deep # Deep dive specific areas
|
||||
/sc:analyze --focus performance --format report # Detailed reporting
|
||||
```
|
||||
|
||||
**Session Management Pattern:**
|
||||
```bash
|
||||
# Initialize → Work → Checkpoint → Validate → Save
|
||||
/sc:load # Start session
|
||||
# ... work commands ...
|
||||
/sc:save --checkpoint "work in progress" # Regular checkpoints
|
||||
/sc:reflect --type completion "task name" # Validate completion
|
||||
/sc:save "task complete" # Final save
|
||||
```
|
||||
|
||||
### Expert Activation Optimization
|
||||
|
||||
**Let auto-activation work:**
|
||||
```bash
|
||||
# These automatically activate appropriate experts
|
||||
/sc:analyze src/auth --focus security # → Security Engineer
|
||||
/sc:implement user dashboard --framework react # → Frontend Architect + Magic MCP
|
||||
/sc:troubleshoot "API performance issues" # → Performance Engineer + Backend Architect
|
||||
/sc:improve legacy-code --type maintainability # → Architect + Quality Engineer
|
||||
```
|
||||
|
||||
**Manual coordination when needed:**
|
||||
```bash
|
||||
# Complex scenarios benefit from explicit tool selection
|
||||
/sc:select-tool "enterprise authentication system" --analyze
|
||||
/sc:brainstorm "multi-service architecture" --strategy enterprise
|
||||
/sc:workflow complex-feature.md --strategy systematic --parallel
|
||||
```
|
||||
|
||||
### Error Recovery Patterns
|
||||
|
||||
**When commands don't work as expected:**
|
||||
```bash
|
||||
# 1. Start with broader scope
|
||||
/sc:analyze src/component.js # Instead of very specific file
|
||||
/sc:troubleshoot "build failing" # Instead of specific error
|
||||
|
||||
# 2. Use safe flags
|
||||
/sc:improve --safe --preview # Check before applying
|
||||
/sc:cleanup --safe # Conservative cleanup only
|
||||
|
||||
# 3. Validate systematically
|
||||
/sc:reflect --type task "what I'm trying to do" # Check approach
|
||||
/sc:test --coverage # Ensure nothing broke
|
||||
```
|
||||
|
||||
### Performance Optimization
|
||||
|
||||
**For large projects:**
|
||||
```bash
|
||||
# Use focused analysis instead of analyzing everything
|
||||
/sc:analyze src/components --focus quality # Not entire project
|
||||
/sc:analyze api/ --focus performance # Specific performance focus
|
||||
|
||||
# Use depth control
|
||||
/sc:analyze --depth quick # Fast overview
|
||||
/sc:analyze critical-files/ --depth deep # Deep dive where needed
|
||||
```
|
||||
|
||||
**For resource constraints:**
|
||||
```bash
|
||||
# Use efficient command combinations
|
||||
/sc:select-tool "complex operation" --efficiency # Get optimal approach
|
||||
/sc:spawn complex-task --parallel # Parallel processing
|
||||
/sc:save --checkpoint # Frequent saves to preserve work
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting Command Issues 🔧
|
||||
|
||||
### Common Command Problems and Solutions
|
||||
|
||||
**"Command not working as expected":**
|
||||
```bash
|
||||
# Try these diagnostic approaches
|
||||
/sc:index --search "keyword" # Find relevant commands
|
||||
/sc:select-tool "what you're trying to do" # Get tool recommendations
|
||||
/sc:reflect --type task "your goal" # Validate approach
|
||||
```
|
||||
|
||||
**"Analysis taking too long":**
|
||||
```bash
|
||||
# Use scope and depth control
|
||||
/sc:analyze src/specific-folder --depth quick # Narrow scope
|
||||
/sc:analyze --focus specific-area # Focus analysis
|
||||
/sc:analyze file.js # Single file analysis
|
||||
```
|
||||
|
||||
**"Build commands failing":**
|
||||
```bash
|
||||
# Systematic build troubleshooting
|
||||
/sc:troubleshoot "build issue description" --type build
|
||||
/sc:analyze package.json --focus dependencies
|
||||
/sc:build --clean --verbose # Clean build with details
|
||||
```
|
||||
|
||||
**"Not sure which command to use":**
|
||||
```bash
|
||||
# Command discovery
|
||||
/sc:index # Browse all commands
|
||||
/sc:index --category analysis # Commands by category
|
||||
/sc:index --search "performance" # Search by keyword
|
||||
```
|
||||
|
||||
### When to Use Which Approach
|
||||
|
||||
**Quick tasks (< 5 minutes):**
|
||||
- Use direct commands: `/sc:analyze`, `/sc:build`, `/sc:improve`
|
||||
- Skip session management for one-off tasks
|
||||
- Use `--quick` depth for fast results
|
||||
|
||||
**Medium tasks (30 minutes - 2 hours):**
|
||||
- Initialize with `/sc:load`
|
||||
- Use checkpoints: `/sc:save --checkpoint`
|
||||
- Use `--preview` before making changes
|
||||
- Validate with `/sc:reflect`
|
||||
|
||||
**Long-term projects (days/weeks):**
|
||||
- Always use session lifecycle: `/sc:load` → work → `/sc:save`
|
||||
- Use `/sc:brainstorm` for requirements discovery
|
||||
- Plan with `/sc:workflow` for complex features
|
||||
- Regular reflection and validation
|
||||
|
||||
**Emergency fixes:**
|
||||
- Start with `/sc:troubleshoot` for diagnosis
|
||||
- Use `--safe` flags for all changes
|
||||
- Test immediately: `/sc:test`
|
||||
- Document fixes: `/sc:document --type fix`
|
||||
|
||||
---
|
||||
|
||||
## Quick Reference Cheat Sheet 📝
|
||||
|
||||
### Most Useful Commands
|
||||
```bash
|
||||
/sc:load # Start session
|
||||
/sc:analyze . # Understand project
|
||||
/sc:implement feature-name # Build features
|
||||
/sc:improve messy-code # Clean up code
|
||||
/sc:troubleshoot "issue" # Debug problems
|
||||
/sc:build # Build project
|
||||
/sc:test --coverage # Test everything
|
||||
/sc:save # Save session
|
||||
```
|
||||
|
||||
### Best Flag Combinations
|
||||
```bash
|
||||
--safe # Conservative changes only
|
||||
--preview # Show changes before applying
|
||||
--depth deep # Thorough analysis
|
||||
--focus security|performance|quality # Domain-specific focus
|
||||
--with-tests # Include testing
|
||||
--interactive # Guided assistance
|
||||
--format report # Generate detailed reports
|
||||
```
|
||||
|
||||
### Emergency Commands
|
||||
```bash
|
||||
/sc:troubleshoot "critical issue" --fix # Emergency fixes
|
||||
/sc:analyze --focus security --depth deep # Security emergencies
|
||||
/sc:build --clean --verbose # Build emergencies
|
||||
/sc:reflect --type completion # Validate fixes work
|
||||
```
|
||||
|
||||
### Session Management
|
||||
```bash
|
||||
/sc:load # Start/resume session
|
||||
/sc:save --checkpoint "description" # Save progress
|
||||
/sc:reflect --type completion # Validate completion
|
||||
/sc:save "final description" # End session
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Remember: Learning Through Doing 🎯
|
||||
|
||||
**The SuperClaude Philosophy:**
|
||||
- **Start simple** - Try `/sc:analyze` or `/sc:implement` first
|
||||
- **Let auto-activation work** - SuperClaude picks experts for you
|
||||
- **Experiment freely** - Use `--preview` to see what would happen
|
||||
- **Progressive enhancement** - Start basic, add complexity as needed
|
||||
|
||||
**Most important patterns:**
|
||||
1. Initialize sessions: `/sc:load`
|
||||
2. Save progress: `/sc:save --checkpoint`
|
||||
3. Validate completion: `/sc:reflect`
|
||||
4. Preview before applying: `--preview` flag
|
||||
5. Use safe modes: `--safe` flag
|
||||
|
||||
**Remember:** You don't need to memorize everything in this cookbook. SuperClaude is designed to be discoverable through use. Start with the Quick Examples section and experiment from there!
|
||||
|
||||
---
|
||||
|
||||
## Related Guides
|
||||
|
||||
**🚀 Foundation Knowledge (Start Here)**
|
||||
- [Installation Guide](installation-guide.md) - Get SuperClaude set up first
|
||||
- [SuperClaude User Guide](superclaude-user-guide.md) - Understand the framework philosophy
|
||||
|
||||
**📚 Deep Understanding (After Trying Examples)**
|
||||
- [Commands Guide](commands-guide.md) - Complete reference for all 21 commands
|
||||
- [Session Management Guide](session-management.md) - Master /sc:load and /sc:save workflows
|
||||
- [Agents Guide](agents-guide.md) - Understanding the 13 specialists behind the scenes
|
||||
|
||||
**⚙️ Advanced Usage (When You Want Control)**
|
||||
- [Flags Guide](flags-guide.md) - Manual control and optimization flags
|
||||
- [Behavioral Modes Guide](behavioral-modes-guide.md) - How SuperClaude adapts automatically
|
||||
- [Best Practices Guide](best-practices.md) - Proven patterns for effective usage
|
||||
|
||||
**🔧 When Examples Don't Work**
|
||||
- [Troubleshooting Guide](troubleshooting-guide.md) - Solutions for common command issues
|
||||
|
||||
**🏗️ Technical Understanding (Optional)**
|
||||
- [Technical Architecture Guide](technical-architecture.md) - How the system works internally
|
||||
|
||||
**📖 Learning Path Using This Cookbook:**
|
||||
1. Try [Quick Examples](#quick-examples---just-try-these-) for immediate results
|
||||
2. Follow [Development Scenarios](#development-scenarios-) for complete workflows
|
||||
3. Use [Command Combinations](#command-combinations-that-work-well-) for your specific needs
|
||||
4. Reference [Best Practices](#best-practices-in-action-) for optimization
|
||||
|
||||
---
|
||||
|
||||
*Ready to start? Try `/sc:load` to initialize your session and pick any example that matches your current need! 🚀*
|
||||
@@ -30,7 +30,7 @@
|
||||
/sc:brainstorm "my app idea" # Auto-activates requirements-analyst agent for discovery
|
||||
```
|
||||
|
||||
**See? No flags needed.** Everything below is for when you get curious about what's happening behind the scenes.
|
||||
**See? No flags needed.** Everything below is for when you get curious about what's happening behind the scenes. For many more working examples, see [Examples Cookbook](examples-cookbook.md).
|
||||
|
||||
---
|
||||
|
||||
@@ -590,4 +590,30 @@ SuperClaude usually adds flags based on context. Here's when it tries:
|
||||
|
||||
---
|
||||
|
||||
## Related Guides
|
||||
|
||||
**🚀 Getting Started (Essential)**
|
||||
- [SuperClaude User Guide](superclaude-user-guide.md) - Framework overview and philosophy
|
||||
- [Examples Cookbook](examples-cookbook.md) - See flags in action with working examples
|
||||
- [Commands Guide](commands-guide.md) - Commands that work with flags
|
||||
|
||||
**🤝 Understanding the System (Recommended)**
|
||||
- [Agents Guide](agents-guide.md) - How flags activate different agents
|
||||
- [Behavioral Modes Guide](behavioral-modes-guide.md) - Flags that control modes
|
||||
- [Session Management Guide](session-management.md) - Session-related flags
|
||||
|
||||
**⚙️ Optimization and Control (Advanced)**
|
||||
- [Best Practices Guide](best-practices.md) - Proven flag combinations and patterns
|
||||
- [Technical Architecture Guide](technical-architecture.md) - How flag processing works
|
||||
|
||||
**🔧 When Flags Don't Work**
|
||||
- [Troubleshooting Guide](troubleshooting-guide.md) - Flag conflicts and issues
|
||||
|
||||
**📖 Recommended Learning Path:**
|
||||
1. [Examples Cookbook](examples-cookbook.md) - See auto-activation without flags
|
||||
2. [Commands Guide](commands-guide.md) - Learn which commands benefit from manual flags
|
||||
3. [Best Practices Guide](best-practices.md) - Master advanced flag patterns
|
||||
|
||||
---
|
||||
|
||||
*Remember: Behind all this apparent complexity, SuperClaude is actually simple to use. Just start typing commands! 🚀*
|
||||
@@ -423,14 +423,19 @@ SuperClaude install --components all
|
||||
1. **Just start using it** - Try `/sc:analyze some-file.js` or `/sc:build` and see what happens ✨
|
||||
2. **Don't stress about learning** - SuperClaude usually figures out what you need
|
||||
3. **Experiment freely** - Commands like `/sc:improve` and `/sc:troubleshoot` are pretty forgiving
|
||||
4. **Use session management** - Try `/sc:load` and `/sc:save` for persistent context
|
||||
5. **Explore behavioral modes** - Let SuperClaude adapt to your workflow automatically
|
||||
4. **Use session management** - Try `/sc:load` and `/sc:save` for persistent context ([Session Management Guide](session-management.md))
|
||||
5. **Explore behavioral modes** - Let SuperClaude adapt to your workflow automatically ([Behavioral Modes Guide](behavioral-modes-guide.md))
|
||||
6. **Give feedback** - Let us know what works and what doesn't
|
||||
|
||||
**The real secret**: SuperClaude is designed to enhance your existing workflow without you having to learn a bunch of new stuff. Just use it like you'd use regular Claude Code, but notice how much smarter it gets! 🎯
|
||||
|
||||
**Still feeling uncertain?** Start with just `/sc:help` and `/sc:analyze README.md` - you'll see how approachable it actually is.
|
||||
|
||||
**Next Steps:**
|
||||
- [Examples Cookbook](examples-cookbook.md) - Copy-paste commands for common tasks
|
||||
- [SuperClaude User Guide](superclaude-user-guide.md) - Complete framework overview
|
||||
- [Commands Guide](commands-guide.md) - All 21 commands with examples
|
||||
|
||||
---
|
||||
|
||||
## Final Notes 📝
|
||||
@@ -446,4 +451,32 @@ Thanks for trying SuperClaude! We hope it makes your development workflow smooth
|
||||
|
||||
---
|
||||
|
||||
## Related Guides
|
||||
|
||||
**🚀 What to Do Next (Essential)**
|
||||
- [Examples Cookbook](examples-cookbook.md) - Copy-paste commands to get started immediately
|
||||
- [SuperClaude User Guide](superclaude-user-guide.md) - Complete framework overview and philosophy
|
||||
|
||||
**📚 Learning the System (Recommended)**
|
||||
- [Commands Guide](commands-guide.md) - All 21 commands with practical examples
|
||||
- [Session Management Guide](session-management.md) - Persistent context and project memory
|
||||
- [Behavioral Modes Guide](behavioral-modes-guide.md) - How SuperClaude adapts automatically
|
||||
|
||||
**🔧 When You Need Help**
|
||||
- [Troubleshooting Guide](troubleshooting-guide.md) - Solutions for installation and usage issues
|
||||
- [Best Practices Guide](best-practices.md) - Proven patterns for effective usage
|
||||
|
||||
**🎯 Advanced Usage (Optional)**
|
||||
- [Agents Guide](agents-guide.md) - Understanding the 13 specialized AI experts
|
||||
- [Flags Guide](flags-guide.md) - Manual control and optimization options
|
||||
- [Technical Architecture Guide](technical-architecture.md) - Internal system design
|
||||
|
||||
**📖 Recommended Reading Path After Installation:**
|
||||
1. [Examples Cookbook](examples-cookbook.md) - Try commands immediately
|
||||
2. [Commands Guide](commands-guide.md) - Learn your toolkit
|
||||
3. [Session Management Guide](session-management.md) - Enable persistent context
|
||||
4. [Best Practices Guide](best-practices.md) - Optimize your workflow
|
||||
|
||||
---
|
||||
|
||||
*Last updated: August 2025 - Let us know if anything in this guide is wrong or confusing!*
|
||||
882
Guides/session-management.md
Normal file
882
Guides/session-management.md
Normal file
@@ -0,0 +1,882 @@
|
||||
# SuperClaude Session Management Guide
|
||||
|
||||
## Introduction
|
||||
|
||||
SuperClaude's session management system transforms Claude Code into a persistent, context-aware development partner. Unlike traditional AI interactions that reset with each conversation, SuperClaude maintains project memory, learning patterns, and development context across multiple sessions. See [Examples Cookbook](examples-cookbook.md) for practical session workflows.
|
||||
|
||||
### What Session Management Provides
|
||||
|
||||
**Persistent Context**: Your project understanding, architectural decisions, and development patterns survive session boundaries and accumulate over time.
|
||||
|
||||
**Cross-Session Learning**: SuperClaude builds comprehensive project knowledge, remembering code patterns, design decisions, and implementation approaches.
|
||||
|
||||
**Intelligent Checkpoints**: Automatic state preservation ensures you never lose progress on complex development tasks.
|
||||
|
||||
**Memory-Driven Workflows**: Task hierarchies, discovered patterns, and project insights are preserved and enhanced across sessions.
|
||||
|
||||
**Seamless Resumption**: Pick up exactly where you left off with full context restoration and intelligent state analysis.
|
||||
|
||||
## Core Concepts
|
||||
|
||||
### Session States
|
||||
|
||||
SuperClaude sessions exist in distinct states that determine available capabilities and behavior:
|
||||
|
||||
**Uninitialized Session**
|
||||
- No project context loaded
|
||||
- Limited to basic Claude Code capabilities
|
||||
- No memory persistence or cross-session learning
|
||||
- Manual project discovery required for each task
|
||||
|
||||
**Active Session**
|
||||
- Project context loaded via `/sc:load`
|
||||
- Full SuperClaude capabilities available
|
||||
- Memory persistence enabled through Serena MCP
|
||||
- Cross-session learning and pattern recognition active
|
||||
- Automatic checkpoint creation based on activity
|
||||
|
||||
**Checkpointed Session**
|
||||
- Critical states preserved for recovery
|
||||
- Task hierarchies and progress maintained
|
||||
- Discoveries and patterns archived
|
||||
- Recovery points for complex operations
|
||||
|
||||
**Archived Session**
|
||||
- Completed projects with preserved insights
|
||||
- Historical context available for future reference
|
||||
- Pattern libraries built from successful implementations
|
||||
- Learning artifacts maintained for similar projects
|
||||
|
||||
### Context Types
|
||||
|
||||
SuperClaude manages multiple context layers:
|
||||
|
||||
**Project Context**
|
||||
- Directory structure and file organization
|
||||
- Dependency mappings and architectural patterns
|
||||
- Code style preferences and team conventions
|
||||
- Build systems and development workflows
|
||||
|
||||
**Task Context**
|
||||
- Current work objectives and completion criteria
|
||||
- Multi-step operations with dependency tracking
|
||||
- Quality gates and validation requirements
|
||||
- Progress checkpoints and recovery states
|
||||
|
||||
**Learning Context**
|
||||
- Discovered patterns and successful approaches
|
||||
- Architectural decisions and their outcomes
|
||||
- Problem-solving strategies that worked
|
||||
- Anti-patterns and approaches to avoid
|
||||
|
||||
**Session Metadata**
|
||||
- Temporal information and session duration
|
||||
- Tool usage patterns and efficiency metrics
|
||||
- Quality assessments and reflection insights
|
||||
- Cross-session relationship tracking
|
||||
|
||||
### Memory Organization
|
||||
|
||||
SuperClaude organizes persistent memory using a structured hierarchy:
|
||||
|
||||
```
|
||||
plan_[timestamp]: Overall goals and objectives
|
||||
phase_[1-5]: Major milestone descriptions
|
||||
task_[phase].[number]: Specific deliverable status
|
||||
todo_[task].[number]: Atomic action completion
|
||||
checkpoint_[timestamp]: State snapshots for recovery
|
||||
blockers: Active impediments requiring attention
|
||||
decisions: Key architectural choices made
|
||||
patterns: Successful approaches discovered
|
||||
insights: Cross-session learning artifacts
|
||||
```
|
||||
|
||||
## Session Commands
|
||||
|
||||
### /sc:load - Project Context Loading
|
||||
|
||||
**Purpose**: Initialize session with project context and cross-session memory retrieval
|
||||
|
||||
**Syntax**:
|
||||
```bash
|
||||
/sc:load [target] [--type project|config|deps|checkpoint] [--refresh] [--analyze]
|
||||
```
|
||||
|
||||
**Behavioral Flow**:
|
||||
1. **Initialize**: Establish Serena MCP connection for memory management
|
||||
2. **Discover**: Analyze project structure and identify context requirements
|
||||
3. **Load**: Retrieve memories, checkpoints, and cross-session persistence data
|
||||
4. **Activate**: Establish project context and prepare development workflow
|
||||
5. **Validate**: Ensure loaded context integrity and session readiness
|
||||
|
||||
**Examples**:
|
||||
|
||||
```bash
|
||||
# Basic project loading - most common usage
|
||||
/sc:load
|
||||
# Loads current directory with memory integration
|
||||
# Establishes session context for development work
|
||||
|
||||
# Specific project with analysis
|
||||
/sc:load /path/to/project --type project --analyze
|
||||
# Loads specific project with comprehensive analysis
|
||||
# Activates context and retrieves cross-session memories
|
||||
|
||||
# Checkpoint restoration
|
||||
/sc:load --type checkpoint --checkpoint session_123
|
||||
# Restores specific checkpoint with session context
|
||||
# Continues previous work with full context preservation
|
||||
|
||||
# Dependency context refresh
|
||||
/sc:load --type deps --refresh
|
||||
# Updates dependency understanding and mappings
|
||||
# Refreshes project analysis with current state
|
||||
```
|
||||
|
||||
**Performance**: Target <500ms initialization, <200ms for core operations
|
||||
|
||||
### /sc:save - Session Context Persistence
|
||||
|
||||
**Purpose**: Preserve session context, discoveries, and progress for cross-session continuity
|
||||
|
||||
**Syntax**:
|
||||
```bash
|
||||
/sc:save [--type session|learnings|context|all] [--summarize] [--checkpoint]
|
||||
```
|
||||
|
||||
**Behavioral Flow**:
|
||||
1. **Analyze**: Examine session progress and identify discoveries worth preserving
|
||||
2. **Persist**: Save context and learnings using Serena MCP memory management
|
||||
3. **Checkpoint**: Create recovery points for complex sessions
|
||||
4. **Validate**: Ensure data integrity and cross-session compatibility
|
||||
5. **Prepare**: Ready context for seamless future session continuation
|
||||
|
||||
**Examples**:
|
||||
|
||||
```bash
|
||||
# Basic session save - automatic checkpoint if >30min
|
||||
/sc:save
|
||||
# Saves discoveries and context to Serena MCP
|
||||
# Creates checkpoint for sessions exceeding 30 minutes
|
||||
|
||||
# Comprehensive checkpoint with recovery state
|
||||
/sc:save --type all --checkpoint
|
||||
# Complete session preservation with recovery capability
|
||||
# Includes learnings, context, and progress state
|
||||
|
||||
# Session summary with discovery documentation
|
||||
/sc:save --summarize
|
||||
# Creates session summary with discovery patterns
|
||||
# Updates cross-session learning and project insights
|
||||
|
||||
# Discovery-only persistence
|
||||
/sc:save --type learnings
|
||||
# Saves only new patterns and insights
|
||||
# Updates project understanding without full preservation
|
||||
```
|
||||
|
||||
**Automatic Triggers**:
|
||||
- Session duration >30 minutes
|
||||
- Complex task completion
|
||||
- Major architectural decisions
|
||||
- Error recovery scenarios
|
||||
- Quality gate completions
|
||||
|
||||
### /sc:reflect - Task Reflection and Validation
|
||||
|
||||
**Purpose**: Analyze session progress, validate task adherence, and capture learning insights
|
||||
|
||||
**Syntax**:
|
||||
```bash
|
||||
/sc:reflect [--type task|session|completion] [--analyze] [--validate]
|
||||
```
|
||||
|
||||
**Behavioral Flow**:
|
||||
1. **Analyze**: Examine task state and session progress using Serena reflection tools
|
||||
2. **Validate**: Assess task adherence, completion quality, and requirement fulfillment
|
||||
3. **Reflect**: Apply deep analysis of collected information and insights
|
||||
4. **Document**: Update session metadata and capture learning patterns
|
||||
5. **Optimize**: Provide recommendations for process improvement
|
||||
|
||||
**Examples**:
|
||||
|
||||
```bash
|
||||
# Task adherence validation
|
||||
/sc:reflect --type task --analyze
|
||||
# Validates current approach against project goals
|
||||
# Identifies deviations and recommends course corrections
|
||||
|
||||
# Session progress analysis
|
||||
/sc:reflect --type session --validate
|
||||
# Comprehensive analysis of session work and information gathering
|
||||
# Quality assessment and gap identification
|
||||
|
||||
# Completion criteria evaluation
|
||||
/sc:reflect --type completion
|
||||
# Evaluates task completion against actual progress
|
||||
# Determines readiness and identifies remaining blockers
|
||||
```
|
||||
|
||||
**Reflection Tools Integration**:
|
||||
- `think_about_task_adherence`: Goal alignment validation
|
||||
- `think_about_collected_information`: Session work analysis
|
||||
- `think_about_whether_you_are_done`: Completion assessment
|
||||
|
||||
## Session Lifecycle
|
||||
|
||||
### Session Initialization Workflow
|
||||
|
||||
**Step 1: Environment Assessment**
|
||||
```bash
|
||||
# SuperClaude analyzes current environment
|
||||
- Directory structure and project type detection
|
||||
- Existing configuration and dependency analysis
|
||||
- Previous session memory availability check
|
||||
- Development tool and framework identification
|
||||
```
|
||||
|
||||
**Step 2: Context Loading**
|
||||
```bash
|
||||
/sc:load
|
||||
# Triggers comprehensive context establishment:
|
||||
- Serena MCP connection initialization
|
||||
- Project memory retrieval from previous sessions
|
||||
- Code pattern analysis and architectural understanding
|
||||
- Development workflow preference loading
|
||||
```
|
||||
|
||||
**Step 3: Session Activation**
|
||||
```bash
|
||||
# SuperClaude prepares active development environment:
|
||||
- Agent specialization activation based on project type
|
||||
- MCP server integration for enhanced capabilities
|
||||
- Memory-driven task management preparation
|
||||
- Cross-session learning pattern application
|
||||
```
|
||||
|
||||
### Active Session Operations
|
||||
|
||||
**Continuous Context Management**:
|
||||
- Real-time memory updates during development work
|
||||
- Pattern recognition and learning capture
|
||||
- Automatic checkpoint creation at critical junctures
|
||||
- Cross-session insight accumulation and refinement
|
||||
|
||||
**Task Management Integration**:
|
||||
```bash
|
||||
# Task Management Mode with Memory
|
||||
📋 Plan → write_memory("plan", goal_statement)
|
||||
→ 🎯 Phase → write_memory("phase_X", milestone)
|
||||
→ 📦 Task → write_memory("task_X.Y", deliverable)
|
||||
→ ✓ Todo → TodoWrite + write_memory("todo_X.Y.Z", status)
|
||||
```
|
||||
|
||||
**Quality Gate Integration**:
|
||||
- Validation checkpoints with memory persistence
|
||||
- Reflection triggers for major decisions
|
||||
- Learning capture during problem resolution
|
||||
- Pattern documentation for future reference
|
||||
|
||||
### Session Completion and Persistence
|
||||
|
||||
**Step 1: Progress Assessment**
|
||||
```bash
|
||||
/sc:reflect --type completion
|
||||
# Evaluates session outcomes:
|
||||
- Task completion against original objectives
|
||||
- Quality assessment of delivered work
|
||||
- Learning insights and pattern discoveries
|
||||
- Blockers and remaining work identification
|
||||
```
|
||||
|
||||
**Step 2: Context Preservation**
|
||||
```bash
|
||||
/sc:save --type all --summarize
|
||||
# Comprehensive session archival:
|
||||
- Complete context state preservation
|
||||
- Discovery documentation and pattern capture
|
||||
- Cross-session learning artifact creation
|
||||
- Recovery checkpoint establishment
|
||||
```
|
||||
|
||||
**Step 3: Session Closure**
|
||||
```bash
|
||||
# SuperClaude completes session lifecycle:
|
||||
- Memory optimization and cleanup
|
||||
- Temporary state removal
|
||||
- Cross-session relationship establishment
|
||||
- Future session preparation
|
||||
```
|
||||
|
||||
### Session Resumption Workflow
|
||||
|
||||
**Context Restoration**:
|
||||
```bash
|
||||
/sc:load
|
||||
# Intelligent session restoration:
|
||||
1. list_memories() → Display available context
|
||||
2. read_memory("current_plan") → Resume primary objectives
|
||||
3. think_about_collected_information() → Understand progress state
|
||||
4. Project context reactivation with full capability restoration
|
||||
```
|
||||
|
||||
**State Analysis**:
|
||||
```bash
|
||||
# SuperClaude analyzes restoration context:
|
||||
- Progress evaluation against previous session objectives
|
||||
- Context gap identification and resolution
|
||||
- Workflow continuation strategy determination
|
||||
- Enhanced capability activation based on accumulated learning
|
||||
```
|
||||
|
||||
## Context Management
|
||||
|
||||
### Project Context Layers
|
||||
|
||||
**File System Context**:
|
||||
- Directory structure and organization patterns
|
||||
- File naming conventions and categorization
|
||||
- Configuration file relationships and dependencies
|
||||
- Build artifact and output directory management
|
||||
|
||||
**Code Context**:
|
||||
- Architectural patterns and design principles
|
||||
- Code style and formatting preferences
|
||||
- Dependency usage patterns and import conventions
|
||||
- Testing strategies and quality assurance approaches
|
||||
|
||||
**Development Context**:
|
||||
- Workflow patterns and tool preferences
|
||||
- Debugging strategies and problem-solving approaches
|
||||
- Performance optimization patterns and techniques
|
||||
- Security considerations and implementation strategies
|
||||
|
||||
**Team Context**:
|
||||
- Collaboration patterns and communication preferences
|
||||
- Code review standards and quality criteria
|
||||
- Documentation approaches and maintenance strategies
|
||||
- Deployment and release management patterns
|
||||
|
||||
### Context Persistence Strategies
|
||||
|
||||
**Incremental Context Building**:
|
||||
- Session-by-session context enhancement
|
||||
- Pattern recognition and abstraction
|
||||
- Anti-pattern identification and avoidance
|
||||
- Success strategy documentation and refinement
|
||||
|
||||
**Context Validation**:
|
||||
- Regular context integrity checks
|
||||
- Outdated information identification and removal
|
||||
- Context relationship validation and maintenance
|
||||
- Cross-session consistency enforcement
|
||||
|
||||
**Context Optimization**:
|
||||
- Memory usage optimization for large projects
|
||||
- Context relevance scoring and prioritization
|
||||
- Selective context loading based on task requirements
|
||||
- Performance-critical context caching strategies
|
||||
|
||||
### Memory Management Patterns
|
||||
|
||||
**Memory Types**:
|
||||
|
||||
**Temporary Memory**: Session-specific, cleanup after completion
|
||||
```bash
|
||||
checkpoint_[timestamp]: Recovery states
|
||||
todo_[task].[number]: Atomic action tracking
|
||||
blockers: Current impediments
|
||||
working_context: Active development state
|
||||
```
|
||||
|
||||
**Persistent Memory**: Cross-session preservation
|
||||
```bash
|
||||
plan_[timestamp]: Project objectives
|
||||
decisions: Architectural choices
|
||||
patterns: Successful approaches
|
||||
insights: Learning artifacts
|
||||
```
|
||||
|
||||
**Archived Memory**: Historical reference
|
||||
```bash
|
||||
completed_phases: Finished milestone documentation
|
||||
resolved_patterns: Successful problem solutions
|
||||
performance_optimizations: Applied improvements
|
||||
security_implementations: Implemented protections
|
||||
```
|
||||
|
||||
## Checkpointing
|
||||
|
||||
### Automatic Checkpoint Creation
|
||||
|
||||
**Time-Based Triggers**:
|
||||
- Session duration exceeding 30 minutes
|
||||
- Continuous development work >45 minutes
|
||||
- Complex task sequences >1 hour
|
||||
- Daily development session boundaries
|
||||
|
||||
**Event-Based Triggers**:
|
||||
- Major architectural decision implementation
|
||||
- Significant code refactoring completion
|
||||
- Error recovery and problem resolution
|
||||
- Quality gate completion and validation
|
||||
|
||||
**Progress-Based Triggers**:
|
||||
- Task phase completion in complex workflows
|
||||
- Multi-file operation completion
|
||||
- Testing milestone achievement
|
||||
- Documentation generation completion
|
||||
|
||||
### Manual Checkpoint Strategies
|
||||
|
||||
**Strategic Checkpoints**:
|
||||
```bash
|
||||
/sc:save --checkpoint --type all
|
||||
# Before risky operations:
|
||||
- Major refactoring initiatives
|
||||
- Architectural pattern changes
|
||||
- Dependency updates or migrations
|
||||
- Performance optimization attempts
|
||||
```
|
||||
|
||||
**Milestone Checkpoints**:
|
||||
```bash
|
||||
/sc:save --summarize --checkpoint
|
||||
# At development milestones:
|
||||
- Feature completion and testing
|
||||
- Integration points and API implementations
|
||||
- Security feature implementations
|
||||
- Performance target achievements
|
||||
```
|
||||
|
||||
**Recovery Checkpoints**:
|
||||
```bash
|
||||
/sc:save --type context --checkpoint
|
||||
# Before complex debugging:
|
||||
- Multi-component failure investigation
|
||||
- Performance bottleneck analysis
|
||||
- Security vulnerability remediation
|
||||
- Integration issue resolution
|
||||
```
|
||||
|
||||
### Checkpoint Management
|
||||
|
||||
**Checkpoint Naming Conventions**:
|
||||
```bash
|
||||
session_[timestamp]: Regular session preservation
|
||||
milestone_[feature]: Feature completion states
|
||||
recovery_[issue]: Problem resolution points
|
||||
decision_[architecture]: Major choice documentation
|
||||
```
|
||||
|
||||
**Checkpoint Validation**:
|
||||
- Context integrity verification
|
||||
- Memory consistency checking
|
||||
- Cross-session compatibility validation
|
||||
- Recovery state functionality testing
|
||||
|
||||
**Checkpoint Cleanup**:
|
||||
- Automatic removal of outdated temporary checkpoints
|
||||
- Consolidation of related checkpoint sequences
|
||||
- Archive creation for completed project phases
|
||||
- Memory optimization through selective retention
|
||||
|
||||
## Cross-Session Workflows
|
||||
|
||||
### Long-Term Project Development
|
||||
|
||||
**Project Initiation Session**:
|
||||
```bash
|
||||
Session 1: Project Analysis and Planning
|
||||
/sc:load # Initialize new project
|
||||
/sc:analyze . # Comprehensive project analysis
|
||||
/sc:brainstorm "modernization strategy" # Interactive requirement discovery
|
||||
/sc:save --type all --summarize # Preserve initial insights
|
||||
```
|
||||
|
||||
**Implementation Sessions**:
|
||||
```bash
|
||||
Session 2-N: Iterative Development
|
||||
/sc:load # Resume with full context
|
||||
/sc:reflect --type session # Validate progress continuation
|
||||
[Development work with automatic checkpointing]
|
||||
/sc:save --checkpoint # Preserve progress state
|
||||
```
|
||||
|
||||
**Completion Session**:
|
||||
```bash
|
||||
Final Session: Project Completion
|
||||
/sc:load # Final context restoration
|
||||
/sc:reflect --type completion # Comprehensive completion assessment
|
||||
/sc:save --type all --summarize # Archive complete project insights
|
||||
```
|
||||
|
||||
### Collaborative Development Patterns
|
||||
|
||||
**Context Sharing Strategies**:
|
||||
- Team-specific memory organization
|
||||
- Shared pattern libraries and conventions
|
||||
- Collaborative checkpoint management
|
||||
- Cross-team insight documentation
|
||||
|
||||
**Handoff Workflows**:
|
||||
```bash
|
||||
Developer A Completion:
|
||||
/sc:save --type all --summarize
|
||||
# Complete context documentation for handoff
|
||||
|
||||
Developer B Resumption:
|
||||
/sc:load --analyze
|
||||
# Context restoration with comprehension validation
|
||||
```
|
||||
|
||||
### Multi-Project Context Management
|
||||
|
||||
**Project Isolation**:
|
||||
- Separate memory namespaces per project
|
||||
- Context switching with state preservation
|
||||
- Project-specific pattern libraries
|
||||
- Independent checkpoint management
|
||||
|
||||
**Cross-Project Learning**:
|
||||
- Pattern sharing between related projects
|
||||
- Architecture decision documentation
|
||||
- Solution library accumulation
|
||||
- Best practice consolidation
|
||||
|
||||
### Complex Task Continuation
|
||||
|
||||
**Multi-Session Task Management**:
|
||||
```bash
|
||||
Session 1: Task Initiation
|
||||
write_memory("plan_auth", "Implement JWT authentication")
|
||||
write_memory("phase_1", "Analysis and design")
|
||||
TodoWrite: Create detailed task breakdown
|
||||
|
||||
Session 2: Implementation Continuation
|
||||
list_memories() → Shows previous context
|
||||
read_memory("plan_auth") → Resume objectives
|
||||
think_about_collected_information() → Progress assessment
|
||||
Continue implementation with full context
|
||||
```
|
||||
|
||||
**Cross-Session Quality Gates**:
|
||||
- Validation checkpoints across session boundaries
|
||||
- Quality criteria persistence and evaluation
|
||||
- Cross-session testing strategy continuation
|
||||
- Performance monitoring across development phases
|
||||
|
||||
## Session Optimization
|
||||
|
||||
### Best Practices for Effective Sessions
|
||||
|
||||
**Session Initialization Optimization**:
|
||||
```bash
|
||||
# Efficient session startup pattern
|
||||
/sc:load --analyze # Load with immediate analysis
|
||||
/sc:reflect --type session # Validate continuation strategy
|
||||
[Focused development work]
|
||||
/sc:save --checkpoint # Regular progress preservation
|
||||
```
|
||||
|
||||
**Memory Management Optimization**:
|
||||
- Regular memory cleanup of temporary artifacts
|
||||
- Strategic memory organization for quick retrieval
|
||||
- Context relevance validation and maintenance
|
||||
- Performance monitoring for large project contexts
|
||||
|
||||
**Task Management Optimization**:
|
||||
- Clear objective definition and persistence
|
||||
- Progress tracking with meaningful checkpoints
|
||||
- Quality gate integration with validation
|
||||
- Learning capture and pattern documentation
|
||||
|
||||
### Performance Considerations
|
||||
|
||||
**Session Startup Performance**:
|
||||
- Target <500ms for context loading
|
||||
- <200ms for memory operations
|
||||
- <1s for checkpoint creation
|
||||
- Optimal balance between completeness and speed
|
||||
|
||||
**Memory Performance**:
|
||||
- Efficient storage patterns for large codebases
|
||||
- Selective context loading based on task scope
|
||||
- Memory compression for archived sessions
|
||||
- Cache optimization for frequently accessed patterns
|
||||
|
||||
**Cross-Session Performance**:
|
||||
- Context relationship optimization
|
||||
- Pattern matching acceleration
|
||||
- Learning algorithm efficiency
|
||||
- Cleanup automation for memory optimization
|
||||
|
||||
### Session Efficiency Patterns
|
||||
|
||||
**Focused Session Design**:
|
||||
- Clear session objectives and success criteria
|
||||
- Scope limitation for manageable complexity
|
||||
- Quality gate integration for validation
|
||||
- Learning capture for future efficiency
|
||||
|
||||
**Context Reuse Strategies**:
|
||||
- Pattern library development and maintenance
|
||||
- Solution template creation and application
|
||||
- Architecture decision documentation and reuse
|
||||
- Best practice consolidation and application
|
||||
|
||||
**Automation Integration**:
|
||||
- Automatic checkpoint creation based on activity
|
||||
- Quality gate automation with context persistence
|
||||
- Pattern recognition and application automation
|
||||
- Learning capture automation for efficiency
|
||||
|
||||
## Advanced Session Patterns
|
||||
|
||||
### Multi-Layer Context Management
|
||||
|
||||
**Context Hierarchies**:
|
||||
```bash
|
||||
Global Context: Organization patterns and standards
|
||||
Project Context: Specific project architecture and decisions
|
||||
Feature Context: Feature-specific patterns and implementations
|
||||
Task Context: Immediate work objectives and constraints
|
||||
```
|
||||
|
||||
**Context Inheritance Patterns**:
|
||||
- Global patterns inherited by projects
|
||||
- Project decisions applied to features
|
||||
- Feature patterns available to tasks
|
||||
- Task insights contributed to higher levels
|
||||
|
||||
**Context Specialization**:
|
||||
- Domain-specific context layers (frontend, backend, security)
|
||||
- Technology-specific patterns and conventions
|
||||
- Quality-specific criteria and validation approaches
|
||||
- Performance-specific optimization strategies
|
||||
|
||||
### Adaptive Session Management
|
||||
|
||||
**Context-Aware Session Adaptation**:
|
||||
- Session behavior modification based on project type
|
||||
- Tool selection optimization based on context history
|
||||
- Agent activation patterns based on accumulated learning
|
||||
- Quality gate customization based on project requirements
|
||||
|
||||
**Learning-Driven Session Evolution**:
|
||||
- Session pattern optimization based on success metrics
|
||||
- Context organization improvement through usage analysis
|
||||
- Memory management refinement through performance monitoring
|
||||
- Checkpoint strategy optimization through recovery analysis
|
||||
|
||||
**Predictive Session Features**:
|
||||
- Next-step suggestion based on context patterns
|
||||
- Resource requirement prediction based on task analysis
|
||||
- Quality issue prediction based on historical patterns
|
||||
- Performance bottleneck prediction based on context analysis
|
||||
|
||||
### Power User Techniques
|
||||
|
||||
**Session Orchestration**:
|
||||
```bash
|
||||
# Complex multi-session orchestration
|
||||
/sc:load --type checkpoint --analyze # Strategic restoration
|
||||
/sc:reflect --type task --validate # Comprehensive validation
|
||||
[Orchestrated development with multiple agents and tools]
|
||||
/sc:save --type all --summarize # Complete preservation
|
||||
```
|
||||
|
||||
**Memory Pattern Development**:
|
||||
- Custom memory schemas for specialized workflows
|
||||
- Pattern template creation for repeated tasks
|
||||
- Context relationship modeling for complex projects
|
||||
- Learning acceleration through pattern recognition
|
||||
|
||||
**Cross-Session Analytics**:
|
||||
- Session efficiency analysis and optimization
|
||||
- Context usage pattern analysis and refinement
|
||||
- Quality outcome correlation with session patterns
|
||||
- Performance optimization through session analytics
|
||||
|
||||
**Advanced Integration Patterns**:
|
||||
- Multi-MCP server coordination with context awareness
|
||||
- Agent specialization with session-specific optimization
|
||||
- Tool selection matrix optimization based on session history
|
||||
- Quality gate customization with context-aware validation
|
||||
|
||||
## Troubleshooting Sessions
|
||||
|
||||
### Common Session Issues
|
||||
|
||||
**Context Loading Problems**:
|
||||
|
||||
**Symptom**: Session fails to load project context
|
||||
```bash
|
||||
Error: "Failed to activate project context"
|
||||
Solution:
|
||||
1. Verify Serena MCP server connection
|
||||
2. Check project directory permissions
|
||||
3. Validate memory integrity with list_memories()
|
||||
4. Reinitialize with /sc:load --refresh
|
||||
```
|
||||
|
||||
**Symptom**: Incomplete context restoration
|
||||
```bash
|
||||
Issue: Missing project patterns or decisions
|
||||
Diagnosis:
|
||||
1. /sc:reflect --type session --analyze
|
||||
2. Check memory completeness with list_memories()
|
||||
3. Validate context relationships
|
||||
Resolution:
|
||||
1. Manual context restoration from checkpoints
|
||||
2. Pattern rediscovery through analysis
|
||||
3. Context rebuild with /sc:load --analyze
|
||||
```
|
||||
|
||||
**Memory Management Issues**:
|
||||
|
||||
**Symptom**: Memory operations timeout or fail
|
||||
```bash
|
||||
Error: "Memory operation exceeded timeout"
|
||||
Solution:
|
||||
1. Check Serena MCP server health
|
||||
2. Optimize memory size through cleanup
|
||||
3. Validate memory schema consistency
|
||||
4. Reinitialize session with fresh context
|
||||
```
|
||||
|
||||
**Symptom**: Context inconsistency across sessions
|
||||
```bash
|
||||
Issue: Different behavior between sessions
|
||||
Diagnosis:
|
||||
1. Compare memory states with list_memories()
|
||||
2. Validate context integrity
|
||||
3. Check for corrupted checkpoints
|
||||
Resolution:
|
||||
1. Restore from known-good checkpoint
|
||||
2. Rebuild context through fresh analysis
|
||||
3. Consolidate memory with cleanup
|
||||
```
|
||||
|
||||
### Performance Troubleshooting
|
||||
|
||||
**Slow Session Initialization**:
|
||||
|
||||
**Diagnosis**:
|
||||
```bash
|
||||
# Performance analysis
|
||||
/sc:load --analyze # Time context loading
|
||||
list_memories() # Check memory size
|
||||
/sc:reflect --type session --analyze # Assess context complexity
|
||||
```
|
||||
|
||||
**Optimization**:
|
||||
```bash
|
||||
# Memory optimization
|
||||
/sc:save --type learnings # Preserve insights only
|
||||
[Clean up temporary memories]
|
||||
/sc:load --refresh # Fresh initialization
|
||||
```
|
||||
|
||||
**Memory Performance Issues**:
|
||||
|
||||
**Large Project Context Management**:
|
||||
- Selective context loading based on task scope
|
||||
- Memory compression for archived sessions
|
||||
- Context segmentation for performance
|
||||
- Cleanup automation for memory optimization
|
||||
|
||||
**Cross-Session Performance Optimization**:
|
||||
- Context relationship streamlining
|
||||
- Pattern matching algorithm optimization
|
||||
- Learning algorithm efficiency improvement
|
||||
- Memory access pattern optimization
|
||||
|
||||
### Recovery Procedures
|
||||
|
||||
**Complete Session Recovery**:
|
||||
```bash
|
||||
# When session state is completely lost
|
||||
1. /sc:load --type checkpoint --checkpoint [last_known_good]
|
||||
2. /sc:reflect --type session --validate
|
||||
3. Manual context verification and supplementation
|
||||
4. /sc:save --checkpoint # Create new recovery point
|
||||
```
|
||||
|
||||
**Partial Context Recovery**:
|
||||
```bash
|
||||
# When some context is available but incomplete
|
||||
1. list_memories() # Assess available context
|
||||
2. /sc:load --analyze # Attempt restoration
|
||||
3. /sc:reflect --type completion # Identify gaps
|
||||
4. Manual gap filling through analysis
|
||||
5. /sc:save --type all # Preserve recovered state
|
||||
```
|
||||
|
||||
**Memory Corruption Recovery**:
|
||||
```bash
|
||||
# When memory contains inconsistent or corrupted data
|
||||
1. Backup current state: /sc:save --checkpoint
|
||||
2. Clean corrupted memories: delete_memory([corrupted_keys])
|
||||
3. Restore from archived checkpoints
|
||||
4. Rebuild context through fresh analysis
|
||||
5. Validate recovery: /sc:reflect --type session --validate
|
||||
```
|
||||
|
||||
### Session Health Monitoring
|
||||
|
||||
**Session Health Indicators**:
|
||||
- Context loading time (<500ms target)
|
||||
- Memory operation performance (<200ms target)
|
||||
- Cross-session consistency validation
|
||||
- Learning accumulation and pattern recognition
|
||||
|
||||
**Proactive Health Management**:
|
||||
- Regular memory optimization and cleanup
|
||||
- Context integrity validation
|
||||
- Performance monitoring and optimization
|
||||
- Checkpoint validation and maintenance
|
||||
|
||||
**Health Diagnostics**:
|
||||
```bash
|
||||
# Comprehensive session health check
|
||||
/sc:load --analyze # Context loading assessment
|
||||
list_memories() # Memory state evaluation
|
||||
/sc:reflect --type session --validate # Context integrity check
|
||||
[Performance monitoring during operations]
|
||||
/sc:save --summarize # Health documentation
|
||||
```
|
||||
|
||||
This comprehensive session management system transforms SuperClaude from a stateless AI assistant into a persistent, learning development partner that accumulates project knowledge and improves its assistance over time. The combination of intelligent memory management, automatic checkpointing, and cross-session learning creates a development experience that truly adapts to your projects and workflows.
|
||||
|
||||
## Related Guides
|
||||
|
||||
**🚀 Foundation (Start Here First)**
|
||||
- [Installation Guide](installation-guide.md) - Ensure SuperClaude is properly installed with MCP servers
|
||||
- [SuperClaude User Guide](superclaude-user-guide.md) - Understanding persistent intelligence concepts
|
||||
- [Examples Cookbook](examples-cookbook.md) - Working session workflows and patterns
|
||||
|
||||
**🛠️ Core Session Usage (Essential)**
|
||||
- [Commands Guide](commands-guide.md) - Session commands (/sc:load, /sc:save, /sc:reflect)
|
||||
- [Agents Guide](agents-guide.md) - How agents coordinate across sessions
|
||||
- [Behavioral Modes Guide](behavioral-modes-guide.md) - Mode persistence and adaptation
|
||||
|
||||
**⚙️ Advanced Session Techniques (Power Users)**
|
||||
- [Best Practices Guide](best-practices.md) - Session optimization and workflow patterns
|
||||
- [Flags Guide](flags-guide.md) - Session-related flags and control options
|
||||
- [Technical Architecture Guide](technical-architecture.md) - Memory system and checkpoint implementation
|
||||
|
||||
**🔧 Session Troubleshooting**
|
||||
- [Troubleshooting Guide](troubleshooting-guide.md) - Session loading, memory, and persistence issues
|
||||
|
||||
**📖 Recommended Learning Path:**
|
||||
1. [Examples Cookbook](examples-cookbook.md) - Try basic session workflows
|
||||
2. [Commands Guide](commands-guide.md) - Master /sc:load, /sc:save, /sc:reflect
|
||||
3. [Best Practices Guide](best-practices.md) - Learn checkpoint and workflow patterns
|
||||
4. Advanced techniques in this guide for complex projects
|
||||
|
||||
**🎯 Session Management Mastery:**
|
||||
- **Beginner**: Basic /sc:load and /sc:save usage
|
||||
- **Intermediate**: Checkpoint strategies and cross-session workflows
|
||||
- **Advanced**: Memory optimization and custom session patterns
|
||||
- **Expert**: Multi-project context management and session analytics
|
||||
File diff suppressed because it is too large
Load Diff
1145
Guides/technical-architecture.md
Normal file
1145
Guides/technical-architecture.md
Normal file
File diff suppressed because it is too large
Load Diff
1011
Guides/troubleshooting-guide.md
Normal file
1011
Guides/troubleshooting-guide.md
Normal file
File diff suppressed because it is too large
Load Diff
Reference in New Issue
Block a user