mirror of
https://github.com/SuperClaude-Org/SuperClaude_Framework.git
synced 2025-12-29 16:16:08 +00:00
refactor(docs): normalize documentation naming to lowercase for PEP8 compliance (#434)
* refactor(docs): rename directories to lowercase for PEP8 compliance - Developer-Guide → developer-guide - Getting-Started → getting-started - Reference → reference - Templates → templates - User-Guide → user-guide - User-Guide-jp → user-guide-jp - User-Guide-kr → user-guide-kr - User-Guide-zh → user-guide-zh This change aligns with Python PEP8 package naming conventions. All 43 files affected. * refactor: rename root documentation files to lowercase - CHANGELOG.md → changelog.md - CODE_OF_CONDUCT.md → code_of_conduct.md - CONTRIBUTING.md → contributing.md - SECURITY.md → security.md Aligns with Python package naming conventions (PEP8). README files remain uppercase as per convention. * refactor: move documentation files to docs/ for cleaner root Moved OSS standard files to docs/: - CHANGELOG.md → docs/CHANGELOG.md - CODE_OF_CONDUCT.md → docs/CODE_OF_CONDUCT.md - CONTRIBUTING.md → docs/CONTRIBUTING.md - SECURITY.md → docs/SECURITY.md Root now contains only essential files: ✓ README files (表紙: en, ja, kr, zh) ✓ LICENSE (法的要件) ✓ Build configs (pyproject.toml, setup.py, MANIFEST.in) ✓ VERSION Rationale: Cleaner root structure following modern Python project conventions. All detailed documentation consolidated in docs/ directory. * refactor: update documentation links after restructure Auto-updated internal documentation links to reflect new structure: - docs/ subdirectories now lowercase (PEP8) - Root files moved to docs/ - All cross-references updated This commit includes linter-generated link updates. * chore(docs): keep OSS-standard uppercase root files (CHANGELOG, CODE_OF_CONDUCT, CONTRIBUTING, SECURITY) * chore(docs): remove duplicated PR docs from repo root (moved under docs) * docs: rename pm-agent-implementation-status.md -> PM_AGENT.md for clarity * docs: update links to PM_AGENT.md after rename --------- Co-authored-by: kazuki <kazuki@kazukinoMacBook-Air.local>
This commit is contained in:
kazuki nakai
249
docs/reference/README.md
Normal file
249
docs/reference/README.md
Normal file
@@ -0,0 +1,249 @@
|
||||
# SuperClaude Framework Reference Documentation
|
||||
|
||||
**Navigation Hub**: Structured learning paths and technical references for all skill levels.
|
||||
|
||||
**Documentation Status**: ✅ **Status: Current** - All content verified for accuracy and completeness.
|
||||
|
||||
## How to Use This Reference Library
|
||||
|
||||
This documentation is organized for **progressive learning** with multiple entry points:
|
||||
|
||||
- **📱 Quick Reference**: Jump to specific solutions for immediate needs
|
||||
- **📚 Learning Paths**: Structured progression from beginner to expert
|
||||
- **🔍 Problem-Solving**: Targeted troubleshooting and diagnostic guidance
|
||||
- **⚡ Performance**: Optimization patterns and advanced techniques
|
||||
|
||||
**Verification Standards**: All examples tested, commands validated, patterns proven in real-world usage.
|
||||
|
||||
---
|
||||
|
||||
## Documentation Navigation Matrix
|
||||
|
||||
| Document | Purpose | Target Audience | Complexity | |
|
||||
|----------|---------|-----------------|------------|-----------------|
|
||||
| **[basic-examples.md](./basic-examples.md)** | Copy-paste ready commands and patterns | All users, quick reference | **Basic** | |
|
||||
| **[examples-cookbook.md](./examples-cookbook.md)** | Recipe collection hub and organization | All users, navigation | **Reference** | |
|
||||
| **[common-issues.md](./common-issues.md)** | Essential troubleshooting and solutions | All users, problem-solving | **Basic** | As needed |
|
||||
| **[mcp-server-guide.md](./mcp-server-guide.md)** | MCP server configuration and usage | Technical users, integration | **Intermediate** | |
|
||||
|
||||
| **[advanced-patterns.md](./advanced-patterns.md)** | Expert coordination and orchestration | Experienced users | **Advanced** | |
|
||||
| **[advanced-workflows.md](./advanced-workflows.md)** | Complex multi-agent orchestration | Expert users | **Advanced** | |
|
||||
| **[integration-patterns.md](./integration-patterns.md)** | Framework and system integration | Architects, experts | **Advanced** | |
|
||||
| **[troubleshooting.md](./troubleshooting.md)** | Comprehensive diagnostic guide | All levels, deep debugging | **Variable** | As needed |
|
||||
| **[diagnostic-reference.md](./diagnostic-reference.md)** | Advanced debugging and analysis | Expert users, complex issues | **Advanced** | |
|
||||
|
||||
---
|
||||
|
||||
## Recommended Learning Paths
|
||||
|
||||
### New Users (Week 1 Foundation)
|
||||
**Goal**: Establish confident SuperClaude usage with essential workflows
|
||||
|
||||
```
|
||||
Day 1-2: ../getting-started/quick-start.md
|
||||
↓ Foundation building and first commands
|
||||
Day 3-4: basic-examples.md
|
||||
↓ Practical application and pattern recognition
|
||||
Day 5-7: common-issues.md
|
||||
↓ Problem resolution and confidence building
|
||||
```
|
||||
|
||||
**Success Metrics**: Can execute basic commands, manage sessions, resolve common issues independently.
|
||||
|
||||
### Intermediate Users (Week 2-3 Enhancement)
|
||||
**Goal**: Master coordination patterns and technical depth
|
||||
|
||||
```
|
||||
Week 2: advanced-patterns.md
|
||||
↓ Multi-agent coordination and orchestration mastery
|
||||
Week 3: mcp-server-guide.md + advanced-workflows.md
|
||||
↓ Performance excellence and technical configuration
|
||||
```
|
||||
|
||||
**Success Metrics**: Can orchestrate complex workflows, optimize performance, configure MCP servers.
|
||||
|
||||
### Expert Users (Advanced Mastery)
|
||||
**Goal**: Complete framework mastery and complex system integration
|
||||
|
||||
```
|
||||
Phase 1: advanced-workflows.md
|
||||
↓ Complex orchestration and enterprise patterns
|
||||
Phase 2: integration-patterns.md
|
||||
↓ Framework integration and architectural mastery
|
||||
Phase 3: diagnostic-reference.md
|
||||
↓ Advanced debugging and system analysis
|
||||
```
|
||||
|
||||
**Success Metrics**: Can design custom workflows, integrate with any framework, diagnose complex issues.
|
||||
|
||||
### Problem-Solving Path (As Needed)
|
||||
**Goal**: Immediate issue resolution and diagnostic guidance
|
||||
|
||||
```
|
||||
Quick Issues: common-issues.md
|
||||
↓ Common problems and immediate solutions
|
||||
Complex Debugging: troubleshooting.md
|
||||
↓ Comprehensive diagnostic approach
|
||||
Advanced Analysis: diagnostic-reference.md
|
||||
↓ Expert-level debugging and analysis
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Command Quick Reference
|
||||
|
||||
### Essential SuperClaude Commands
|
||||
|
||||
| Command Pattern | Purpose | Example |
|
||||
|----------------|---------|---------|
|
||||
| `/sc:load` | Restore session context | `/sc:load project_name` |
|
||||
| `/sc:save` | Preserve session state | `/sc:save "milestone checkpoint"` |
|
||||
| `--think` | Enable structured analysis | `--think analyze performance bottlenecks` |
|
||||
| `--brainstorm` | Collaborative requirement discovery | `--brainstorm new authentication system` |
|
||||
| `--task-manage` | Multi-step operation orchestration | `--task-manage refactor user module` |
|
||||
|
||||
### Performance & Efficiency Flags
|
||||
|
||||
| Flag | Purpose | Best For |
|
||||
|------|---------|----------|
|
||||
| `--uc` / `--ultracompressed` | Token-efficient communication | Large operations, context pressure |
|
||||
| `--orchestrate` | Optimize tool selection | Multi-tool operations, performance needs |
|
||||
| `--loop` | Iterative improvement cycles | Code refinement, quality enhancement |
|
||||
| `--validate` | Pre-execution risk assessment | Production environments, critical operations |
|
||||
|
||||
### MCP Server Activation
|
||||
|
||||
| Flag | Server | Best For |
|
||||
|------|---------|----------|
|
||||
| `--c7` / `--context7` | Context7 | Official documentation, framework patterns |
|
||||
| `--seq` / `--sequential` | Sequential | Complex analysis, debugging, system design |
|
||||
| `--magic` | Magic | UI components, design systems, frontend work |
|
||||
| `--morph` / `--morphllm` | Morphllm | Bulk transformations, pattern-based edits |
|
||||
| `--serena` | Serena | Symbol operations, project memory, large codebases |
|
||||
| `--play` / `--playwright` | Playwright | Browser testing, E2E scenarios, visual validation |
|
||||
|
||||
---
|
||||
|
||||
## Framework Integration Quick Start
|
||||
|
||||
### React/Next.js Projects
|
||||
```bash
|
||||
# Initialize with React patterns
|
||||
--c7 --magic "implement Next.js authentication with TypeScript"
|
||||
|
||||
# Component development workflow
|
||||
--magic --think "create responsive dashboard component"
|
||||
```
|
||||
|
||||
### Node.js/Express Backend
|
||||
```bash
|
||||
# API development with best practices
|
||||
--c7 --seq "design RESTful API with Express and MongoDB"
|
||||
|
||||
# Performance optimization
|
||||
--think --orchestrate "optimize database queries and caching"
|
||||
```
|
||||
|
||||
### Full-Stack Development
|
||||
```bash
|
||||
# Complete application workflow
|
||||
--task-manage --all-mcp "build full-stack e-commerce platform"
|
||||
|
||||
# Integration testing
|
||||
--play --seq "implement end-to-end testing strategy"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Problem-Solving Quick Reference
|
||||
|
||||
### Immediate Issues
|
||||
- **Command not working**: Check [common-issues.md](./common-issues.md) → Common SuperClaude Problems
|
||||
- **Session lost**: Use `/sc:load` → See [Session Management](../user-guide/session-management.md)
|
||||
- **Flag confusion**: Check [basic-examples.md](./basic-examples.md) → Flag Usage Examples
|
||||
|
||||
### Development Blockers
|
||||
- **Performance slow**: See [Advanced Workflows](./advanced-workflows.md) → Performance Patterns
|
||||
- **Complex debugging**: Use [troubleshooting.md](./troubleshooting.md) → Systematic Debugging
|
||||
- **Integration issues**: Check [integration-patterns.md](./integration-patterns.md) → Framework Patterns
|
||||
|
||||
### System-Level Issues
|
||||
- **Architecture problems**: Use [advanced-workflows.md](./advanced-workflows.md) → System Design
|
||||
- **Expert debugging**: Apply [diagnostic-reference.md](./diagnostic-reference.md) → Advanced Analysis
|
||||
- **Custom workflow needs**: Study [advanced-patterns.md](./advanced-patterns.md) → Custom Orchestration [advanced-patterns.md](./advanced-patterns.md) → Custom Orchestration
|
||||
|
||||
---
|
||||
|
||||
## Documentation Health & Verification
|
||||
|
||||
### Quality Assurance
|
||||
- ✅ **Commands Tested**: All examples tested and functional
|
||||
- ✅ **Patterns Proven**: Real-world usage validation in production environments
|
||||
- ✅ **Cross-References**: Internal links verified and maintained
|
||||
- ✅ **Regular Updates**: Documentation synchronized with framework evolution
|
||||
|
||||
### Accuracy Standards
|
||||
- **Command Syntax**: Verified against latest SuperClaude implementation
|
||||
- **Flag Behavior**: Tested in multiple scenarios and environments
|
||||
- **MCP Integration**: Confirmed compatibility with current MCP server versions
|
||||
- **Performance Claims**: Benchmarked and measured in realistic conditions
|
||||
|
||||
### Reporting Issues
|
||||
Found outdated information or broken examples?
|
||||
|
||||
1. **Quick Fixes**: Check [common-issues.md](./common-issues.md) first
|
||||
2. **Documentation Bugs**: Report via project issues with specific file and line
|
||||
3. **Missing Patterns**: Suggest additions with use case description
|
||||
4. **Verification Requests**: Request re-testing of specific examples
|
||||
|
||||
---
|
||||
|
||||
## Expert Tips for Maximum Productivity
|
||||
|
||||
### Daily Workflow Optimization
|
||||
1. **Session Management**: Always start with `/sc:load`, end with `/sc:save`
|
||||
2. **Flag Combinations**: Combine complementary flags: `--think --c7` for documented analysis
|
||||
3. **Progressive Complexity**: Start simple, add sophistication incrementally
|
||||
4. **Tool Specialization**: Match tools to tasks: Magic for UI, Sequential for analysis
|
||||
|
||||
### Learning Acceleration
|
||||
1. **Follow the Paths**: Use recommended learning sequences for structured growth
|
||||
2. **Practice Patterns**: Repeat common workflows until they become intuitive
|
||||
3. **Experiment Safely**: Use feature branches and checkpoints for exploration
|
||||
4. **Community Learning**: Share discoveries and learn from others' approaches
|
||||
|
||||
### Troubleshooting Mastery
|
||||
1. **Systematic Approach**: Always start with [common-issues.md](./common-issues.md)
|
||||
2. **Evidence Gathering**: Use `--think` for complex problem analysis
|
||||
3. **Root Cause Focus**: Address underlying issues, not just symptoms
|
||||
4. **Documentation First**: Check official docs before experimental solutions
|
||||
|
||||
---
|
||||
|
||||
## Advanced Resources & Integration
|
||||
|
||||
### Framework-Specific Guides
|
||||
- **React/Next.js**: See [integration-patterns.md](./integration-patterns.md) → React Integration
|
||||
- **Vue/Nuxt**: See [integration-patterns.md](./integration-patterns.md) → Vue Ecosystem
|
||||
- **Node.js/Express**: See [integration-patterns.md](./integration-patterns.md) → Backend Patterns
|
||||
- **Python/Django**: See [integration-patterns.md](./integration-patterns.md) → Python Workflows
|
||||
|
||||
### Specialized Workflows
|
||||
- **DevOps Integration**: [advanced-workflows.md](./advanced-workflows.md) → CI/CD Patterns
|
||||
- **Testing Strategies**: [advanced-patterns.md](./advanced-patterns.md) → Testing Orchestration
|
||||
- **Performance Engineering**: [Advanced Patterns](./advanced-patterns.md) → Complex Coordination
|
||||
- **Security Implementation**: [integration-patterns.md](./integration-patterns.md) → Security Patterns
|
||||
|
||||
### Community & Support
|
||||
- **Best Practices**: Continuously updated based on community feedback
|
||||
- **Pattern Library**: Growing collection of proven workflow patterns
|
||||
- **Expert Network**: Connect with experienced SuperClaude practitioners
|
||||
- **Regular Updates**: Documentation evolves with framework capabilities
|
||||
|
||||
---
|
||||
|
||||
**Start Your Journey**: New to SuperClaude? Begin with [Quick Start Guide](../getting-started/quick-start.md) for immediate productivity gains.
|
||||
|
||||
**Need Answers Now**: Jump to [basic-examples.md](./basic-examples.md) for copy-paste solutions.
|
||||
|
||||
**Ready for Advanced**: Explore [advanced-patterns.md](./advanced-patterns.md) for expert-level orchestration.
|
||||
323
docs/reference/advanced-patterns.md
Normal file
323
docs/reference/advanced-patterns.md
Normal file
@@ -0,0 +1,323 @@
|
||||
# SuperClaude Advanced Patterns
|
||||
|
||||
**Advanced Context Usage Patterns**: Sophisticated combinations of commands, agents, and flags for experienced SuperClaude users working on complex projects.
|
||||
|
||||
**Remember**: SuperClaude provides context to Claude Code. All patterns here are about guiding Claude's behavior through context, not executing code or coordinating processes.
|
||||
|
||||
## Table of Contents
|
||||
|
||||
### Context Combination Patterns
|
||||
- [Multi-Agent Context Patterns](#multi-agent-context-patterns) - Combining multiple specialist contexts
|
||||
- [Command Sequencing Patterns](#command-sequencing-patterns) - Effective command combinations
|
||||
- [Flag Combination Strategies](#flag-combination-strategies) - Advanced flag usage
|
||||
|
||||
### Workflow Patterns
|
||||
- [Complex Project Patterns](#complex-project-patterns) - Large project approaches
|
||||
- [Migration Patterns](#migration-patterns) - Legacy system modernization
|
||||
- [Review and Audit Patterns](#review-and-audit-patterns) - Comprehensive analysis
|
||||
|
||||
## Multi-Agent Context Patterns
|
||||
|
||||
### Combining Specialist Contexts
|
||||
|
||||
**Security + Backend Pattern:**
|
||||
```bash
|
||||
# Security-focused backend development
|
||||
@agent-security "define authentication requirements"
|
||||
@agent-backend-architect "design API with security requirements"
|
||||
/sc:implement "secure API endpoints"
|
||||
|
||||
# What happens:
|
||||
# 1. Security context loaded first
|
||||
# 2. Backend context added
|
||||
# 3. Implementation guided by both contexts
|
||||
# Note: Contexts combine in Claude's understanding, not in execution
|
||||
```
|
||||
|
||||
**Frontend + UX + Accessibility Pattern:**
|
||||
```bash
|
||||
# Comprehensive frontend development
|
||||
@agent-frontend-architect "design component architecture"
|
||||
/sc:implement "accessible React components" --magic
|
||||
@agent-quality-engineer "review accessibility compliance"
|
||||
|
||||
# Context layering:
|
||||
# - Frontend patterns guide structure
|
||||
# - Magic MCP may provide UI components (if configured)
|
||||
# - Quality context ensures standards
|
||||
```
|
||||
|
||||
### Manual vs Automatic Agent Selection
|
||||
|
||||
**Explicit Control Pattern:**
|
||||
```bash
|
||||
# Manually control which contexts load
|
||||
@agent-python-expert "implement data pipeline"
|
||||
# Only Python context, no auto-activation
|
||||
|
||||
# vs Automatic selection
|
||||
/sc:implement "Python data pipeline"
|
||||
# May activate multiple agents based on keywords
|
||||
```
|
||||
|
||||
**Override Auto-Selection:**
|
||||
```bash
|
||||
# Prevent unwanted agent activation
|
||||
/sc:implement "simple utility" --no-mcp
|
||||
@agent-backend-architect "keep it simple"
|
||||
# Limits context to specified agent only
|
||||
```
|
||||
|
||||
## Command Sequencing Patterns
|
||||
|
||||
### Progressive Refinement Pattern
|
||||
|
||||
```bash
|
||||
# Start broad, then focus
|
||||
/sc:analyze project/
|
||||
# General analysis
|
||||
|
||||
/sc:analyze project/core/ --focus architecture
|
||||
# Focused on structure
|
||||
|
||||
/sc:analyze project/core/auth/ --focus security --think-hard
|
||||
# Deep security analysis
|
||||
|
||||
# Each command builds on previous context within the conversation
|
||||
```
|
||||
|
||||
### Discovery to Implementation Pattern
|
||||
|
||||
```bash
|
||||
# Complete feature development flow
|
||||
/sc:brainstorm "feature idea"
|
||||
# Explores requirements
|
||||
|
||||
/sc:design "feature architecture"
|
||||
# Creates structure
|
||||
|
||||
@agent-backend-architect "review design"
|
||||
# Expert review
|
||||
|
||||
/sc:implement "feature based on design"
|
||||
# Implementation follows design
|
||||
|
||||
/sc:test --validate
|
||||
# Verification approach
|
||||
```
|
||||
|
||||
### Iterative Improvement Pattern
|
||||
|
||||
```bash
|
||||
# Multiple improvement passes
|
||||
/sc:analyze code/ --focus quality
|
||||
# Identify issues
|
||||
|
||||
/sc:improve code/ --fix
|
||||
# First improvement pass
|
||||
|
||||
@agent-refactoring-expert "suggest further improvements"
|
||||
# Expert suggestions
|
||||
|
||||
/sc:improve code/ --fix --focus maintainability
|
||||
# Refined improvements
|
||||
```
|
||||
|
||||
## Flag Combination Strategies
|
||||
|
||||
### Analysis Depth Control
|
||||
|
||||
```bash
|
||||
# Quick overview
|
||||
/sc:analyze . --overview --uc
|
||||
# Fast, compressed output
|
||||
|
||||
# Standard analysis
|
||||
/sc:analyze . --think
|
||||
# Structured thinking
|
||||
|
||||
# Deep analysis
|
||||
/sc:analyze . --think-hard --verbose
|
||||
# Comprehensive analysis
|
||||
|
||||
# Maximum depth (use sparingly)
|
||||
/sc:analyze . --ultrathink
|
||||
# Exhaustive analysis
|
||||
```
|
||||
|
||||
### MCP Server Selection
|
||||
|
||||
```bash
|
||||
# Selective MCP usage
|
||||
/sc:implement "React component" --magic --c7
|
||||
# Only Magic and Context7 MCP
|
||||
|
||||
# Disable all MCP
|
||||
/sc:implement "simple function" --no-mcp
|
||||
# Pure Claude context only
|
||||
|
||||
# All available MCP
|
||||
/sc:analyze complex-system/ --all-mcp
|
||||
# Maximum tool availability (if configured)
|
||||
```
|
||||
|
||||
## Complex Project Patterns
|
||||
|
||||
### Large Codebase Analysis
|
||||
|
||||
```bash
|
||||
# Systematic exploration of large projects
|
||||
# Step 1: Structure understanding
|
||||
/sc:load project/
|
||||
/sc:analyze . --overview --focus architecture
|
||||
|
||||
# Step 2: Identify problem areas
|
||||
@agent-quality-engineer "identify high-risk modules"
|
||||
|
||||
# Step 3: Deep dive into specific areas
|
||||
/sc:analyze high-risk-module/ --think-hard --focus quality
|
||||
|
||||
# Step 4: Implementation plan
|
||||
/sc:workflow "improvement plan based on analysis"
|
||||
```
|
||||
|
||||
### Multi-Module Development
|
||||
|
||||
```bash
|
||||
# Developing interconnected modules
|
||||
# Frontend module
|
||||
/sc:implement "user interface module"
|
||||
@agent-frontend-architect "ensure consistency"
|
||||
|
||||
# Backend module
|
||||
/sc:implement "API module"
|
||||
@agent-backend-architect "ensure compatibility"
|
||||
|
||||
# Integration layer
|
||||
/sc:implement "frontend-backend integration"
|
||||
# Context from both previous implementations guides this
|
||||
```
|
||||
|
||||
### Cross-Technology Projects
|
||||
|
||||
```bash
|
||||
# Projects with multiple technologies
|
||||
# Python backend
|
||||
@agent-python-expert "implement FastAPI backend"
|
||||
|
||||
# React frontend
|
||||
@agent-frontend-architect "implement React frontend"
|
||||
|
||||
# DevOps setup
|
||||
@agent-devops-architect "create deployment configuration"
|
||||
|
||||
# Integration documentation
|
||||
/sc:document --type integration
|
||||
```
|
||||
|
||||
## Migration Patterns
|
||||
|
||||
### Legacy System Analysis
|
||||
|
||||
```bash
|
||||
# Understanding legacy systems
|
||||
/sc:load legacy-system/
|
||||
/sc:analyze . --focus architecture --verbose
|
||||
|
||||
@agent-refactoring-expert "identify modernization opportunities"
|
||||
@agent-system-architect "propose migration strategy"
|
||||
|
||||
/sc:workflow "create migration plan"
|
||||
```
|
||||
|
||||
### Incremental Migration
|
||||
|
||||
```bash
|
||||
# Step-by-step migration approach
|
||||
# Phase 1: Analysis
|
||||
/sc:analyze legacy-module/ --comprehensive
|
||||
|
||||
# Phase 2: Design new architecture
|
||||
@agent-system-architect "design modern replacement"
|
||||
|
||||
# Phase 3: Implementation
|
||||
/sc:implement "modern module with compatibility layer"
|
||||
|
||||
# Phase 4: Validation
|
||||
/sc:test --focus compatibility
|
||||
```
|
||||
|
||||
## Review and Audit Patterns
|
||||
|
||||
### Security Audit Pattern
|
||||
|
||||
```bash
|
||||
# Comprehensive security review
|
||||
/sc:analyze . --focus security --think-hard
|
||||
@agent-security "review authentication and authorization"
|
||||
@agent-security "check for OWASP vulnerabilities"
|
||||
/sc:document --type security-audit
|
||||
```
|
||||
|
||||
### Code Quality Review
|
||||
|
||||
```bash
|
||||
# Multi-aspect quality review
|
||||
/sc:analyze src/ --focus quality
|
||||
@agent-quality-engineer "review test coverage"
|
||||
@agent-refactoring-expert "identify code smells"
|
||||
/sc:improve --fix --preview
|
||||
```
|
||||
|
||||
### Architecture Review
|
||||
|
||||
```bash
|
||||
# System architecture assessment
|
||||
@agent-system-architect "review current architecture"
|
||||
/sc:analyze . --focus architecture --think-hard
|
||||
@agent-performance-engineer "identify bottlenecks"
|
||||
/sc:design "optimization recommendations"
|
||||
```
|
||||
|
||||
## Important Clarifications
|
||||
|
||||
### What These Patterns Actually Do
|
||||
|
||||
- ✅ **Guide Claude's Thinking**: Provide structured approaches
|
||||
- ✅ **Combine Contexts**: Layer multiple expertise areas
|
||||
- ✅ **Improve Output Quality**: Better code generation through better context
|
||||
- ✅ **Structure Workflows**: Organize complex tasks
|
||||
|
||||
### What These Patterns Don't Do
|
||||
|
||||
- ❌ **Execute in Parallel**: Everything is sequential context loading
|
||||
- ❌ **Coordinate Processes**: No actual process coordination
|
||||
- ❌ **Optimize Performance**: No code runs, so no performance impact
|
||||
- ❌ **Persist Between Sessions**: Each conversation is independent
|
||||
|
||||
## Best Practices for Advanced Usage
|
||||
|
||||
### Context Management
|
||||
|
||||
1. **Layer Deliberately**: Add contexts in logical order
|
||||
2. **Avoid Overload**: Too many agents can dilute focus
|
||||
3. **Use Manual Control**: Override auto-activation when needed
|
||||
4. **Maintain Conversation Flow**: Keep related work in same conversation
|
||||
|
||||
### Command Efficiency
|
||||
|
||||
1. **Progress Logically**: Broad → Specific → Implementation
|
||||
2. **Reuse Context**: Later commands benefit from earlier context
|
||||
3. **Document Decisions**: Use `/sc:save` for important summaries
|
||||
4. **Scope Appropriately**: Focus on manageable chunks
|
||||
|
||||
### Flag Usage
|
||||
|
||||
1. **Match Task Complexity**: Simple tasks don't need `--ultrathink`
|
||||
2. **Control Output**: Use `--uc` for concise results
|
||||
3. **Manage MCP**: Only activate needed servers
|
||||
4. **Avoid Conflicts**: Don't use contradictory flags
|
||||
|
||||
## Summary
|
||||
|
||||
Advanced SuperClaude patterns are about sophisticated context management and command sequencing. They help Claude Code generate better outputs by providing richer, more structured context. Remember: all "coordination" and "optimization" happens in how Claude interprets the context, not in any actual execution or parallel processing.
|
||||
309
docs/reference/advanced-workflows.md
Normal file
309
docs/reference/advanced-workflows.md
Normal file
@@ -0,0 +1,309 @@
|
||||
# SuperClaude Advanced Workflows Collection
|
||||
|
||||
**Status**: ✅ **Status: Current** - Complex command sequences and context combinations for sophisticated projects.
|
||||
|
||||
**Advanced Usage Guide**: Patterns for complex projects using multiple commands, agents, and careful context management within Claude Code conversations.
|
||||
|
||||
## Overview and Usage Guide
|
||||
|
||||
**Purpose**: Advanced SuperClaude patterns for complex, multi-step projects that require careful sequencing of commands and context management.
|
||||
|
||||
**Important**: These are conversation patterns, not executing workflows. All work happens within Claude Code based on context provided.
|
||||
|
||||
**Key Concepts**:
|
||||
- Command sequences within a conversation
|
||||
- Context layering through multiple agents
|
||||
- Progressive refinement approaches
|
||||
- Project phase management (manual, not automated)
|
||||
|
||||
## Multi-Context Project Patterns
|
||||
|
||||
### Full-Stack Development Sequence
|
||||
|
||||
```bash
|
||||
# E-commerce platform using multiple contexts
|
||||
# Step 1: Architecture context
|
||||
@agent-system-architect "design e-commerce architecture"
|
||||
|
||||
# Step 2: Security requirements
|
||||
@agent-security "define security requirements for payments"
|
||||
|
||||
# Step 3: Backend implementation
|
||||
/sc:implement "API with authentication and payment processing"
|
||||
# Claude uses accumulated context from previous steps
|
||||
|
||||
# Step 4: Frontend implementation
|
||||
@agent-frontend-architect "design responsive UI"
|
||||
/sc:implement "React frontend with TypeScript"
|
||||
|
||||
# Step 5: Review
|
||||
/sc:analyze . --focus quality
|
||||
|
||||
# Note: Each step builds context within the conversation
|
||||
# No actual coordination or parallel execution occurs
|
||||
```
|
||||
|
||||
### Problem-Solving Workflow
|
||||
|
||||
```bash
|
||||
# Complex troubleshooting approach
|
||||
# Step 1: Problem understanding
|
||||
/sc:troubleshoot "application performance issues"
|
||||
|
||||
# Step 2: Expert analysis
|
||||
@agent-performance-engineer "analyze potential bottlenecks"
|
||||
@agent-backend-architect "review architecture for issues"
|
||||
|
||||
# Step 3: Solution design
|
||||
/sc:design "performance improvement plan"
|
||||
|
||||
# Step 4: Implementation
|
||||
/sc:implement "performance optimizations"
|
||||
|
||||
# Context accumulates but doesn't execute
|
||||
```
|
||||
|
||||
## Complex Project Phases
|
||||
|
||||
### Project Initialization Pattern
|
||||
|
||||
```bash
|
||||
# Starting a new project
|
||||
# Discovery phase
|
||||
/sc:brainstorm "project concept"
|
||||
# Claude explores requirements
|
||||
|
||||
# Planning phase
|
||||
/sc:design "system architecture"
|
||||
@agent-system-architect "review and refine"
|
||||
|
||||
# Documentation
|
||||
/sc:document --type architecture
|
||||
/sc:save "project-plan"
|
||||
# Creates summary for your records (not persistent storage)
|
||||
```
|
||||
|
||||
### Incremental Development Pattern
|
||||
|
||||
```bash
|
||||
# Building features incrementally
|
||||
# Feature 1: Authentication
|
||||
/sc:implement "user authentication"
|
||||
/sc:test --focus security
|
||||
/sc:document --type api
|
||||
|
||||
# Feature 2: User Profiles (builds on auth context)
|
||||
/sc:implement "user profile management"
|
||||
/sc:test --focus functionality
|
||||
|
||||
# Feature 3: Admin Dashboard (uses previous context)
|
||||
/sc:implement "admin dashboard"
|
||||
@agent-frontend-architect "ensure consistency"
|
||||
|
||||
# Each feature builds on conversation context
|
||||
```
|
||||
|
||||
### Migration Project Pattern
|
||||
|
||||
```bash
|
||||
# Legacy system migration
|
||||
# Phase 1: Analysis
|
||||
/sc:load legacy-system/
|
||||
/sc:analyze . --focus architecture --verbose
|
||||
# Claude builds understanding
|
||||
|
||||
# Phase 2: Planning
|
||||
@agent-system-architect "design migration strategy"
|
||||
/sc:workflow "create migration plan"
|
||||
|
||||
# Phase 3: Implementation
|
||||
/sc:implement "compatibility layer"
|
||||
/sc:implement "new system components"
|
||||
|
||||
# Phase 4: Validation
|
||||
/sc:test --focus compatibility
|
||||
/sc:document --type migration
|
||||
|
||||
# Manual phases, not automated workflow
|
||||
```
|
||||
|
||||
## Enterprise-Scale Patterns
|
||||
|
||||
### Large Codebase Analysis
|
||||
|
||||
```bash
|
||||
# Systematic analysis of large projects
|
||||
# Overview
|
||||
/sc:analyze . --overview
|
||||
# Get high-level understanding
|
||||
|
||||
# Focused analysis by module
|
||||
/sc:analyze auth-module/ --focus security
|
||||
/sc:analyze api-module/ --focus quality
|
||||
/sc:analyze frontend/ --focus performance
|
||||
|
||||
# Synthesis
|
||||
@agent-system-architect "synthesize findings"
|
||||
/sc:workflow "improvement recommendations"
|
||||
|
||||
# Note: Sequential analysis, not parallel
|
||||
```
|
||||
|
||||
### Multi-Technology Projects
|
||||
|
||||
```bash
|
||||
# Projects with diverse tech stacks
|
||||
# Backend (Python)
|
||||
@agent-python-expert "implement FastAPI backend"
|
||||
/sc:implement "Python API with async support"
|
||||
|
||||
# Frontend (React)
|
||||
@agent-frontend-architect "implement React frontend"
|
||||
/sc:implement "TypeScript React application"
|
||||
|
||||
# Mobile (React Native)
|
||||
/sc:implement "React Native mobile app"
|
||||
|
||||
# Infrastructure
|
||||
@agent-devops-architect "design deployment"
|
||||
/sc:implement "Docker configuration"
|
||||
|
||||
# Each technology addressed sequentially
|
||||
```
|
||||
|
||||
## Quality Assurance Workflows
|
||||
|
||||
### Comprehensive Review Pattern
|
||||
|
||||
```bash
|
||||
# Multi-aspect code review
|
||||
# Quality review
|
||||
/sc:analyze . --focus quality
|
||||
@agent-quality-engineer "identify improvements"
|
||||
|
||||
# Security review
|
||||
/sc:analyze . --focus security
|
||||
@agent-security "check for vulnerabilities"
|
||||
|
||||
# Architecture review
|
||||
@agent-system-architect "evaluate design"
|
||||
|
||||
# Performance review
|
||||
@agent-performance-engineer "suggest optimizations"
|
||||
|
||||
# Consolidated improvements
|
||||
/sc:improve . --fix
|
||||
|
||||
# Sequential reviews, not parallel analysis
|
||||
```
|
||||
|
||||
### Testing Strategy Pattern
|
||||
|
||||
```bash
|
||||
# Comprehensive testing approach
|
||||
# Test planning
|
||||
/sc:design "testing strategy"
|
||||
|
||||
# Unit tests
|
||||
/sc:test --type unit
|
||||
# Claude generates unit test code
|
||||
|
||||
# Integration tests
|
||||
/sc:test --type integration
|
||||
# Claude generates integration test code
|
||||
|
||||
# E2E tests
|
||||
/sc:test --type e2e
|
||||
# Claude suggests E2E test scenarios
|
||||
|
||||
# Documentation
|
||||
/sc:document --type testing
|
||||
|
||||
# Test code generation, not execution
|
||||
```
|
||||
|
||||
## Session Management Patterns
|
||||
|
||||
### Long Project Sessions
|
||||
|
||||
```bash
|
||||
# Managing context in long conversations
|
||||
# Start with context
|
||||
/sc:load project/
|
||||
|
||||
# Work progressively
|
||||
/sc:implement "feature A"
|
||||
/sc:implement "feature B"
|
||||
# Context accumulates
|
||||
|
||||
# Create checkpoint
|
||||
/sc:save "session-checkpoint"
|
||||
# Creates summary for your notes
|
||||
|
||||
# Continue work
|
||||
/sc:implement "feature C"
|
||||
|
||||
# Final summary
|
||||
/sc:reflect
|
||||
# Reviews conversation progress
|
||||
```
|
||||
|
||||
### Context Refresh Pattern
|
||||
|
||||
```bash
|
||||
# When conversation gets too long
|
||||
# Save current state
|
||||
/sc:save "work-complete"
|
||||
# Copy output for next conversation
|
||||
|
||||
# In new conversation:
|
||||
/sc:load project/
|
||||
"Previous work: [paste summary]"
|
||||
# Manually restore context
|
||||
|
||||
# Continue work
|
||||
/sc:implement "next feature"
|
||||
```
|
||||
|
||||
## Important Clarifications
|
||||
|
||||
### What These Workflows ARE
|
||||
|
||||
- ✅ **Conversation Patterns**: Sequences within a single Claude conversation
|
||||
- ✅ **Context Building**: Progressive accumulation of understanding
|
||||
- ✅ **Command Sequences**: Ordered use of commands for better results
|
||||
- ✅ **Manual Phases**: User-controlled project progression
|
||||
|
||||
### What These Workflows ARE NOT
|
||||
|
||||
- ❌ **Automated Workflows**: No automatic execution or orchestration
|
||||
- ❌ **Parallel Processing**: Everything is sequential
|
||||
- ❌ **Persistent Sessions**: Context lost between conversations
|
||||
- ❌ **Performance Optimization**: No code executes to optimize
|
||||
|
||||
## Best Practices
|
||||
|
||||
### Conversation Management
|
||||
|
||||
1. **Keep Related Work Together**: Don't split related tasks across conversations
|
||||
2. **Build Context Progressively**: Start broad, then focus
|
||||
3. **Document Key Decisions**: Use `/sc:save` for important points
|
||||
4. **Manage Conversation Length**: Start new conversation if too long
|
||||
|
||||
### Command Sequencing
|
||||
|
||||
1. **Logical Order**: Analysis → Design → Implementation → Testing
|
||||
2. **Context Accumulation**: Later commands benefit from earlier context
|
||||
3. **Appropriate Depth**: Match analysis depth to task complexity
|
||||
4. **Clear Scope**: Focus commands on specific areas
|
||||
|
||||
### Agent Usage
|
||||
|
||||
1. **Strategic Activation**: Use agents for specific expertise
|
||||
2. **Avoid Overload**: Too many agents can dilute focus
|
||||
3. **Manual Control**: Use `@agent-` for precise control
|
||||
4. **Context Layering**: Add agents in logical order
|
||||
|
||||
## Summary
|
||||
|
||||
Advanced workflows in SuperClaude are sophisticated conversation patterns that build context progressively within a single Claude Code session. They help generate better outputs through careful command sequencing and context management, but do not involve any actual workflow execution, parallel processing, or automation. Success comes from understanding how to layer context effectively within Claude's conversation scope.
|
||||
553
docs/reference/basic-examples.md
Normal file
553
docs/reference/basic-examples.md
Normal file
@@ -0,0 +1,553 @@
|
||||
# SuperClaude Basic Examples Collection
|
||||
|
||||
**Status**: ✅ **Status: Current** - Essential commands, single-agent workflows, and common development tasks.
|
||||
|
||||
**Quick Reference Guide**: Copy-paste ready examples for beginners, focused on essential SuperClaude usage patterns and fundamental development workflows.
|
||||
|
||||
> **📝 Context Note**: These examples show `/sc:` commands and `@agent-` invocations that trigger Claude Code to read specific context files and adopt the behaviors defined there. The sophistication comes from the behavioral instructions, not from executable software.
|
||||
|
||||
## Overview and Usage Guide
|
||||
|
||||
**Purpose**: Essential SuperClaude commands and patterns for everyday development tasks. Start here for your first SuperClaude experience.
|
||||
|
||||
**Target Audience**: New users, developers learning SuperClaude fundamentals, immediate task application
|
||||
|
||||
**Usage Pattern**: Copy → Adapt → Execute → Learn from results
|
||||
|
||||
**Key Features**:
|
||||
- Examples demonstrate core SuperClaude functionality
|
||||
- Clear patterns for immediate application
|
||||
- Single-focus examples for clear learning
|
||||
- Progressive complexity within basic scope
|
||||
|
||||
## Essential One-Liner Commands
|
||||
|
||||
### Core Development Commands
|
||||
|
||||
#### Command: /sc:brainstorm
|
||||
**Purpose**: Interactive project discovery and requirements gathering
|
||||
**Syntax**: `/sc:brainstorm "project description"`
|
||||
**Example**:
|
||||
```bash
|
||||
/sc:brainstorm "mobile app for fitness tracking"
|
||||
# Expected: Socratic dialogue, requirement elicitation, feasibility analysis
|
||||
```
|
||||
**Behavior**: Triggers interactive discovery dialogue and requirements analysis
|
||||
|
||||
#### Command: /sc:analyze
|
||||
**Purpose**: Analyze existing codebase for issues and improvements
|
||||
**Syntax**: `/sc:analyze [target] --focus [domain]`
|
||||
**Example**:
|
||||
```bash
|
||||
/sc:analyze src/ --focus security
|
||||
# Expected: Comprehensive security audit, vulnerability report, improvement suggestions
|
||||
```
|
||||
**Behavior**: Provides comprehensive security analysis and improvement recommendations
|
||||
|
||||
#### Command: /sc:implement
|
||||
**Purpose**: Implement a complete feature with best practices
|
||||
**Syntax**: `/sc:implement "feature description with requirements"`
|
||||
**Example**:
|
||||
```bash
|
||||
/sc:implement "user authentication with JWT and rate limiting"
|
||||
# Expected: Complete auth implementation, security validation, tests included
|
||||
```
|
||||
**Behavior**: Delivers complete implementation following security and quality standards
|
||||
|
||||
#### Command: /sc:troubleshoot
|
||||
**Purpose**: Troubleshoot and fix a problem systematically
|
||||
**Syntax**: `/sc:troubleshoot "problem description"`
|
||||
**Example**:
|
||||
```bash
|
||||
/sc:troubleshoot "API returns 500 error on user login"
|
||||
# Expected: Step-by-step diagnosis, root cause identification, solution ranking
|
||||
```
|
||||
**Verification**: Activates root-cause-analyst + Sequential reasoning + systematic debugging
|
||||
|
||||
#### Command: /sc:test
|
||||
**Purpose**: Generate comprehensive tests for existing code
|
||||
**Syntax**: `/sc:test [target] --focus [domain]`
|
||||
**Example**:
|
||||
```bash
|
||||
/sc:test --focus quality
|
||||
# Expected: Test suite, quality metrics, coverage reporting
|
||||
```
|
||||
**Verification**: Activates quality-engineer + test automation
|
||||
|
||||
### Quick Analysis Commands
|
||||
|
||||
#### Command: /sc:analyze (Quality Focus)
|
||||
**Purpose**: Project structure and quality overview
|
||||
**Syntax**: `/sc:analyze [target] --focus quality`
|
||||
**Example**:
|
||||
```bash
|
||||
/sc:analyze . --focus quality
|
||||
```
|
||||
**Verification**:
|
||||
|
||||
#### Command: /sc:analyze (Security Focus)
|
||||
**Purpose**: Security-focused code review
|
||||
**Syntax**: `/sc:analyze [target] --focus security [--think]`
|
||||
**Example**:
|
||||
```bash
|
||||
/sc:analyze src/ --focus security --think
|
||||
```
|
||||
**Verification**:
|
||||
|
||||
#### Command: /sc:analyze (Performance Focus)
|
||||
**Purpose**: Performance bottleneck identification
|
||||
**Syntax**: `/sc:analyze [target] --focus performance`
|
||||
**Example**:
|
||||
```bash
|
||||
/sc:analyze api/ --focus performance
|
||||
```
|
||||
**Verification**:
|
||||
|
||||
#### Command: /sc:analyze (Architecture Focus)
|
||||
**Purpose**: Architecture assessment for refactoring
|
||||
**Syntax**: `/sc:analyze [target] --focus architecture [--serena]`
|
||||
**Example**:
|
||||
```bash
|
||||
/sc:analyze . --focus architecture --serena
|
||||
```
|
||||
**Verification**:
|
||||
|
||||
## Manual Agent Invocation Examples
|
||||
|
||||
### Direct Specialist Activation
|
||||
|
||||
#### Pattern: @agent-[specialist]
|
||||
**Purpose**: Manually invoke specific domain experts instead of auto-activation
|
||||
**Syntax**: `@agent-[specialist] "task or question"`
|
||||
|
||||
#### Python Expert
|
||||
```bash
|
||||
@agent-python-expert "optimize this data processing pipeline for performance"
|
||||
# Expected: Python-specific optimizations, async patterns, memory management
|
||||
```
|
||||
|
||||
#### Security Engineer
|
||||
```bash
|
||||
@agent-security "review this authentication system for vulnerabilities"
|
||||
# Expected: OWASP compliance check, vulnerability assessment, secure coding recommendations
|
||||
```
|
||||
|
||||
#### Frontend Architect
|
||||
```bash
|
||||
@agent-frontend-architect "design a responsive component architecture"
|
||||
# Expected: Component patterns, state management, accessibility considerations
|
||||
```
|
||||
|
||||
#### Quality Engineer
|
||||
```bash
|
||||
@agent-quality-engineer "create comprehensive test coverage for payment module"
|
||||
# Expected: Test strategy, unit/integration/e2e tests, edge cases
|
||||
```
|
||||
|
||||
### Combining Auto and Manual Patterns
|
||||
|
||||
#### Pattern: Command + Manual Override
|
||||
```bash
|
||||
# Step 1: Use command with auto-activation
|
||||
/sc:implement "user profile management system"
|
||||
# Auto-activates: backend-architect, possibly frontend
|
||||
|
||||
# Step 2: Add specific expert review
|
||||
@agent-security "review the profile system for data privacy compliance"
|
||||
# Manual activation for targeted review
|
||||
|
||||
# Step 3: Performance optimization
|
||||
@agent-performance-engineer "optimize database queries for profile fetching"
|
||||
# Manual activation for specific optimization
|
||||
```
|
||||
|
||||
#### Pattern: Sequential Specialist Chain
|
||||
```bash
|
||||
# Design phase
|
||||
@agent-system-architect "design microservices architecture for e-commerce"
|
||||
|
||||
# Security review
|
||||
@agent-security "review architecture for security boundaries"
|
||||
|
||||
# Implementation guidance
|
||||
@agent-backend-architect "implement service communication patterns"
|
||||
|
||||
# DevOps setup
|
||||
@agent-devops-architect "configure CI/CD for microservices"
|
||||
```
|
||||
|
||||
## Basic Usage Patterns
|
||||
|
||||
### Discovery → Implementation Pattern
|
||||
```bash
|
||||
# Step 1: Explore and understand requirements
|
||||
/sc:brainstorm "web dashboard for project management"
|
||||
# Expected: Requirements discovery, feature prioritization, technical scope
|
||||
|
||||
# Step 2: Analyze technical approach
|
||||
/sc:analyze "dashboard architecture patterns" --focus architecture --c7
|
||||
# Expected: Architecture patterns, technology recommendations, implementation strategy
|
||||
|
||||
# Step 3: Implement core functionality
|
||||
/sc:implement "React dashboard with task management and team collaboration"
|
||||
# Expected: Complete dashboard implementation with modern React patterns
|
||||
```
|
||||
|
||||
### Development → Quality Pattern
|
||||
```bash
|
||||
# Step 1: Build the feature
|
||||
/sc:implement "user registration with email verification"
|
||||
# Expected: Registration system with email integration
|
||||
|
||||
# Step 2: Test thoroughly
|
||||
/sc:test --focus quality
|
||||
# Expected: Comprehensive test coverage and validation
|
||||
|
||||
# Step 3: Review and improve
|
||||
/sc:analyze . --focus quality && /sc:implement "quality improvements"
|
||||
# Expected: Quality assessment and targeted improvements
|
||||
```
|
||||
|
||||
### Problem → Solution Pattern
|
||||
```bash
|
||||
# Step 1: Understand the problem
|
||||
/sc:troubleshoot "slow database queries on user dashboard"
|
||||
# Expected: Systematic problem diagnosis and root cause analysis
|
||||
|
||||
# Step 2: Analyze affected components
|
||||
/sc:analyze db/ --focus performance
|
||||
# Expected: Database performance analysis and optimization opportunities
|
||||
|
||||
# Step 3: Implement solutions
|
||||
/sc:implement "database query optimization and caching"
|
||||
# Expected: Performance improvements with measurable impact
|
||||
```
|
||||
|
||||
## Getting Started Examples
|
||||
|
||||
### Your First Project Analysis
|
||||
```bash
|
||||
# Complete project understanding workflow
|
||||
/sc:load . && /sc:analyze --focus quality
|
||||
|
||||
# Expected Results:
|
||||
# - Project structure analysis and documentation
|
||||
# - Code quality assessment across all files
|
||||
# - Architecture overview with component relationships
|
||||
# - Security audit and performance recommendations
|
||||
|
||||
# Activates: Serena (project loading) + analyzer + security-engineer + performance-engineer
|
||||
# Output: Comprehensive project report with actionable insights
|
||||
|
||||
|
||||
# Variations for different focuses:
|
||||
/sc:analyze src/ --focus quality # Code quality only
|
||||
/sc:analyze . --scope file # Quick file analysis
|
||||
/sc:analyze backend/ --focus security # Backend security review
|
||||
```
|
||||
|
||||
### Interactive Requirements Discovery
|
||||
```bash
|
||||
# Transform vague ideas into concrete requirements
|
||||
/sc:brainstorm "productivity app for remote teams"
|
||||
|
||||
# Expected Interaction:
|
||||
# - Socratic questioning about user needs and pain points
|
||||
# - Feature prioritization and scope definition
|
||||
# - Technical feasibility assessment
|
||||
# - Structured requirements document generation
|
||||
|
||||
# Activates: Brainstorming mode + system-architect + requirements-analyst
|
||||
# Output: Product Requirements Document (PRD) with clear specifications
|
||||
|
||||
# Follow-up commands for progression:
|
||||
/sc:analyze "team collaboration architecture" --focus architecture --c7
|
||||
/sc:implement "real-time messaging system with React and WebSocket"
|
||||
```
|
||||
|
||||
### Simple Feature Implementation
|
||||
```bash
|
||||
# Complete authentication system
|
||||
/sc:implement "user login with JWT tokens and password hashing"
|
||||
|
||||
# Expected Implementation:
|
||||
# - Secure password hashing with bcrypt
|
||||
# - JWT token generation and validation
|
||||
# - Login/logout endpoints with proper error handling
|
||||
# - Frontend login form with validation
|
||||
|
||||
# Activates: security-engineer + backend-architect + Context7
|
||||
# Output: Production-ready authentication system
|
||||
|
||||
|
||||
# Variations for different auth needs:
|
||||
/sc:implement "OAuth integration with Google and GitHub"
|
||||
/sc:implement "password reset flow with email verification"
|
||||
/sc:implement "two-factor authentication with TOTP"
|
||||
```
|
||||
|
||||
## Common Development Tasks
|
||||
|
||||
### API Development Basics
|
||||
```bash
|
||||
# REST API with CRUD operations
|
||||
/sc:implement "Express.js REST API for blog posts with validation"
|
||||
# Expected: Complete REST API with proper HTTP methods, validation, error handling
|
||||
|
||||
|
||||
# API documentation generation
|
||||
/sc:analyze api/ --focus architecture --c7
|
||||
# Expected: Comprehensive API documentation with usage examples
|
||||
|
||||
|
||||
# API testing setup
|
||||
/sc:test --focus api --type integration
|
||||
# Expected: Integration test suite for API endpoints
|
||||
|
||||
```
|
||||
|
||||
### Frontend Component Development
|
||||
```bash
|
||||
# React component with modern patterns
|
||||
/sc:implement "React user profile component with form validation and image upload"
|
||||
# Activates: frontend-architect + Magic MCP + accessibility patterns
|
||||
# Expected: Modern React component with hooks, validation, accessibility
|
||||
|
||||
|
||||
# Component testing
|
||||
/sc:test src/components/ --focus quality
|
||||
# Expected: Component tests with React Testing Library
|
||||
|
||||
|
||||
# Responsive design implementation
|
||||
/sc:implement "responsive navigation component with mobile menu"
|
||||
# Expected: Mobile-first responsive navigation with accessibility
|
||||
|
||||
```
|
||||
|
||||
### Database Integration
|
||||
```bash
|
||||
# Database setup with ORM
|
||||
/sc:implement "PostgreSQL integration with Prisma ORM and migrations"
|
||||
# Expected: Database schema, ORM setup, migration system
|
||||
|
||||
|
||||
# Database query optimization
|
||||
/sc:analyze db/ --focus performance
|
||||
# Expected: Query performance analysis and optimization suggestions
|
||||
|
||||
|
||||
# Data validation and security
|
||||
/sc:implement "input validation and SQL injection prevention"
|
||||
# Expected: Comprehensive input validation and security measures
|
||||
|
||||
```
|
||||
|
||||
## Basic Troubleshooting Examples
|
||||
|
||||
### Common API Issues
|
||||
```bash
|
||||
# Performance problems
|
||||
/sc:troubleshoot "API response time increased from 200ms to 2 seconds"
|
||||
# Activates: root-cause-analyst + performance-engineer + Sequential reasoning
|
||||
# Expected: Systematic diagnosis, root cause identification, solution ranking
|
||||
|
||||
# Authentication errors
|
||||
/sc:troubleshoot "JWT token validation failing for valid users"
|
||||
# Expected: Token validation analysis, security assessment, fix implementation
|
||||
|
||||
# Database connection issues
|
||||
/sc:troubleshoot "database connection pool exhausted under load"
|
||||
# Expected: Connection analysis, configuration fixes, scaling recommendations
|
||||
```
|
||||
|
||||
### Frontend Debugging
|
||||
```bash
|
||||
# React rendering issues
|
||||
/sc:troubleshoot "React components not updating when data changes"
|
||||
# Expected: State management analysis, re-rendering optimization, debugging guide
|
||||
|
||||
# Performance problems
|
||||
/sc:troubleshoot "React app loading slowly with large component tree"
|
||||
# Expected: Performance analysis, optimization strategies, code splitting recommendations
|
||||
|
||||
# Build failures
|
||||
/sc:troubleshoot "webpack build failing with dependency conflicts"
|
||||
# Expected: Dependency analysis, conflict resolution, build optimization
|
||||
```
|
||||
|
||||
### Development Environment Issues
|
||||
```bash
|
||||
# Setup problems
|
||||
/sc:troubleshoot "Node.js application not starting after npm install"
|
||||
# Expected: Environment analysis, dependency troubleshooting, configuration fixes
|
||||
|
||||
# Testing failures
|
||||
/sc:troubleshoot "tests passing locally but failing in CI"
|
||||
# Expected: Environment comparison, CI configuration analysis, fix recommendations
|
||||
|
||||
# Deployment issues
|
||||
/sc:troubleshoot "application crashes on production deployment"
|
||||
# Expected: Production environment analysis, configuration validation, deployment fixes
|
||||
```
|
||||
|
||||
## Copy-Paste Quick Solutions
|
||||
|
||||
### Immediate Project Setup
|
||||
```bash
|
||||
# New React project with TypeScript
|
||||
/sc:implement "React TypeScript project with routing, state management, and testing setup"
|
||||
@agent-frontend-architect "review and optimize the project structure"
|
||||
|
||||
# New Node.js API server
|
||||
/sc:implement "Express.js REST API with JWT authentication and PostgreSQL integration"
|
||||
@agent-backend-architect "ensure scalability and best practices"
|
||||
|
||||
# Python web API
|
||||
/sc:implement "FastAPI application with async PostgreSQL and authentication middleware"
|
||||
@agent-python-expert "optimize async patterns and dependency injection"
|
||||
|
||||
# Next.js full-stack app
|
||||
/sc:implement "Next.js 14 application with App Router, TypeScript, and Tailwind CSS"
|
||||
@agent-system-architect "design optimal data fetching strategy"
|
||||
```
|
||||
|
||||
### Quick Quality Improvements
|
||||
```bash
|
||||
# Code quality enhancement
|
||||
/sc:analyze . --focus quality && /sc:implement "code quality improvements"
|
||||
@agent-quality-engineer "create quality metrics dashboard"
|
||||
|
||||
# Security hardening
|
||||
/sc:analyze . --focus security && /sc:implement "security improvements"
|
||||
|
||||
# Test coverage improvement
|
||||
/sc:test --focus quality && /sc:implement "additional test coverage"
|
||||
```
|
||||
|
||||
### Common Feature Implementations
|
||||
```bash
|
||||
# User authentication system
|
||||
/sc:implement "complete user authentication with registration, login, and password reset"
|
||||
|
||||
# File upload functionality
|
||||
/sc:implement "secure file upload with image resizing and cloud storage"
|
||||
|
||||
# Real-time features
|
||||
/sc:implement "real-time chat with WebSocket and message persistence"
|
||||
|
||||
# Payment processing
|
||||
/sc:implement "Stripe payment integration with subscription management"
|
||||
|
||||
# Email functionality
|
||||
/sc:implement "email service with templates and delivery tracking"
|
||||
```
|
||||
|
||||
## Basic Flag Examples
|
||||
|
||||
### Analysis Depth Control
|
||||
```bash
|
||||
# Quick analysis
|
||||
/sc:analyze src/ --scope file
|
||||
|
||||
# Standard analysis
|
||||
/sc:analyze . --think
|
||||
|
||||
# Deep analysis
|
||||
/sc:analyze . --think-hard --focus architecture
|
||||
|
||||
```
|
||||
|
||||
### Focus Area Selection
|
||||
```bash
|
||||
# Security-focused analysis
|
||||
/sc:analyze . --focus security
|
||||
|
||||
|
||||
# Implementation with specific focus
|
||||
/sc:implement "API optimization" --focus architecture
|
||||
|
||||
|
||||
# Quality-focused testing
|
||||
/sc:test --focus quality
|
||||
|
||||
```
|
||||
|
||||
### Tool Integration
|
||||
```bash
|
||||
# Use Context7 for official patterns
|
||||
/sc:implement "React hooks implementation" --c7
|
||||
|
||||
|
||||
# Use Serena for project memory
|
||||
/sc:analyze . --serena --focus architecture
|
||||
|
||||
|
||||
# Efficient token usage
|
||||
/sc:analyze large-project/ --uc
|
||||
|
||||
```
|
||||
|
||||
## Learning Progression Workflow
|
||||
|
||||
### Week 1: Foundation
|
||||
```bash
|
||||
# Day 1-2: Basic commands
|
||||
/sc:analyze . --focus quality
|
||||
/sc:implement "simple feature"
|
||||
/sc:test --focus quality
|
||||
|
||||
# Day 3-4: Troubleshooting
|
||||
/sc:troubleshoot "specific problem"
|
||||
/sc:analyze problem-area/ --focus relevant-domain
|
||||
|
||||
# Day 5-7: Integration
|
||||
/sc:brainstorm "project idea"
|
||||
/sc:implement "core feature"
|
||||
/sc:test --focus quality
|
||||
```
|
||||
|
||||
### Week 2: Patterns
|
||||
```bash
|
||||
# Workflow patterns
|
||||
/sc:brainstorm → /sc:analyze → /sc:implement → /sc:test
|
||||
|
||||
# Problem-solving patterns
|
||||
/sc:troubleshoot → /sc:analyze → /sc:implement
|
||||
|
||||
# Quality patterns
|
||||
/sc:analyze → /sc:implement → /sc:test → /sc:analyze
|
||||
```
|
||||
|
||||
### Week 3-4: Integration
|
||||
```bash
|
||||
# Multi-step projects
|
||||
/sc:brainstorm "larger project"
|
||||
/sc:implement "phase 1"
|
||||
/sc:test --focus quality
|
||||
/sc:implement "phase 2"
|
||||
/sc:test --focus integration
|
||||
```
|
||||
|
||||
## Next Steps
|
||||
|
||||
### Ready for Intermediate?
|
||||
- Comfortable with all basic commands
|
||||
- Can complete simple workflows independently
|
||||
- Understanding of agent activation and tool selection
|
||||
- Ready for multi-step projects
|
||||
|
||||
### Continue Learning:
|
||||
- **Advanced Workflows**: Complex orchestration and multi-agent coordination
|
||||
- **Integration Patterns**: Framework integration and cross-tool coordination
|
||||
- **Best Practices Guide**: Optimization strategies and expert techniques
|
||||
|
||||
### Success Indicators:
|
||||
- Can solve common development problems independently
|
||||
- Understands when to use different flags and focuses
|
||||
- Can adapt examples to specific project needs
|
||||
- Ready to explore more complex SuperClaude capabilities
|
||||
|
||||
---
|
||||
|
||||
**Remember**: Start simple, practice frequently, and gradually increase complexity. These basic examples form the foundation for all advanced SuperClaude usage.
|
||||
556
docs/reference/claude-code-history-management.md
Normal file
556
docs/reference/claude-code-history-management.md
Normal file
@@ -0,0 +1,556 @@
|
||||
# Claude Code Conversation History Management Research
|
||||
|
||||
**Research Date**: 2025-10-09
|
||||
**Purpose**: Understand .jsonl file structure, performance impact, and establish rotation policy
|
||||
|
||||
---
|
||||
|
||||
## 1. Official Documentation & Purpose
|
||||
|
||||
### .jsonl File Structure
|
||||
**Location**: `~/.claude/projects/{project-directory}/`
|
||||
|
||||
**Data Structure** (from analysis of actual files):
|
||||
```json
|
||||
{
|
||||
"type": "summary|file-history-snapshot|user|assistant|system|tool_use|tool_result|message",
|
||||
"timestamp": "ISO-8601 timestamp",
|
||||
"cwd": "/absolute/path/to/working/directory",
|
||||
"sessionId": "uuid",
|
||||
"gitBranch": "branch-name",
|
||||
"content": "message content or command",
|
||||
"messageId": "uuid for message tracking"
|
||||
}
|
||||
```
|
||||
|
||||
**Key Message Types** (from 2.6MB conversation analysis):
|
||||
- `message` (228): Container for conversation messages
|
||||
- `assistant` (228): Claude's responses
|
||||
- `user` (182): User inputs
|
||||
- `tool_use` (137): Tool invocations
|
||||
- `tool_result` (137): Tool execution results
|
||||
- `text` (74): Text content blocks
|
||||
- `file-history-snapshot` (39): File state tracking
|
||||
- `thinking` (31): Claude's reasoning process
|
||||
- `system` (12): System-level messages
|
||||
|
||||
### File History Snapshot Purpose
|
||||
```json
|
||||
{
|
||||
"type": "file-history-snapshot",
|
||||
"messageId": "uuid",
|
||||
"snapshot": {
|
||||
"messageId": "uuid",
|
||||
"trackedFileBackups": {},
|
||||
"timestamp": "ISO-8601"
|
||||
},
|
||||
"isSnapshotUpdate": false
|
||||
}
|
||||
```
|
||||
|
||||
**Purpose** (inferred from structure):
|
||||
- Tracks file states at specific conversation points
|
||||
- Enables undo/redo functionality for file changes
|
||||
- Provides rollback capability for edits
|
||||
- **Note**: No official documentation found on this feature
|
||||
|
||||
### Conversation Loading Behavior
|
||||
**Official Best Practices** ([source](https://www.anthropic.com/engineering/claude-code-best-practices)):
|
||||
- "All conversations are automatically saved locally with their full message history"
|
||||
- "When resuming, the entire message history is restored to maintain context"
|
||||
- "Tool usage and results from previous conversations preserved"
|
||||
|
||||
**Resume Commands**:
|
||||
- `--continue`: Automatically continue most recent conversation
|
||||
- `/resume`: Show list of recent sessions and choose one
|
||||
- Session ID specification: Resume specific conversation
|
||||
|
||||
---
|
||||
|
||||
## 2. Performance Impact
|
||||
|
||||
### Known Issues from GitHub
|
||||
|
||||
#### Issue #5024: History Accumulation Causing Performance Issues
|
||||
**Status**: Open (Major Issue)
|
||||
**URL**: https://github.com/anthropics/claude-code/issues/5024
|
||||
|
||||
**Reported Problems**:
|
||||
- File sizes growing to "hundreds of MB or more"
|
||||
- Slower application startup times
|
||||
- System performance degradation
|
||||
- No automatic cleanup mechanism
|
||||
- One user reported file size of 968KB+ continuously growing
|
||||
|
||||
**Current Workaround**:
|
||||
- Manual editing of `.claude.json` (risky - can break configurations)
|
||||
- `claude history clear` (removes ALL history across ALL projects)
|
||||
|
||||
#### Issue #7985: Severe Memory Leak
|
||||
**Status**: Critical
|
||||
**URL**: https://github.com/anthropics/claude-code/issues/7985
|
||||
|
||||
**Reported Problems**:
|
||||
- Context accumulation causing massive memory usage
|
||||
- Memory leaks with objects not garbage collected
|
||||
- One user reported ~570GB of virtual memory usage
|
||||
- Long-running sessions become unusable
|
||||
|
||||
#### Issue #8839: Conversation Compaction Failure
|
||||
**Status**: Regression (after undo/redo feature)
|
||||
**URL**: https://github.com/anthropics/claude-code/issues/8839
|
||||
|
||||
**Impact**:
|
||||
- Claude Code can no longer automatically compact long conversations
|
||||
- "Too long" errors after conversation history navigation feature added
|
||||
- Conversations become unmanageable without manual intervention
|
||||
|
||||
#### Issue #8755: /clear Command Not Working
|
||||
**Status**: Bug
|
||||
**URL**: https://github.com/anthropics/claude-code/issues/8755
|
||||
|
||||
**Impact**:
|
||||
- `/clear` command stopped functioning for some users
|
||||
- "Clear Conversations" menu option non-functional
|
||||
- Users cannot reset context window as recommended
|
||||
|
||||
### Actual Performance Data (Your Environment)
|
||||
|
||||
**Current State** (as of 2025-10-09):
|
||||
- **Total agiletec project**: 33MB (57 conversation files)
|
||||
- **Largest file**: 2.6MB (462 lines)
|
||||
- **Average file**: ~580KB
|
||||
- **Files >1MB**: 3 files
|
||||
- **Total across all projects**: ~62MB
|
||||
|
||||
**Age Distribution**:
|
||||
- Files older than 30 days: 0
|
||||
- Files older than 7 days: 4
|
||||
- Most files: <7 days old
|
||||
|
||||
**Comparison to Other Projects**:
|
||||
```
|
||||
33M agiletec (57 files) - Most active
|
||||
14M SSD-2TB project
|
||||
6.3M tokium
|
||||
2.6M bunseki
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. Official Retention Policies
|
||||
|
||||
### Standard Retention (Consumer)
|
||||
**Source**: [Anthropic Privacy Center](https://privacy.claude.com/en/articles/10023548-how-long-do-you-store-my-data)
|
||||
|
||||
- **Prompts/Responses**: Up to 30 days in back-end logs
|
||||
- **Deleted chats**: Immediately removed from UI, purged within 30 days
|
||||
- **API logs**: Reducing to 7 days starting September 15, 2025 (from 30 days)
|
||||
|
||||
### Enterprise Controls
|
||||
**Source**: [Custom Data Retention Controls](https://privacy.anthropic.com/en/articles/10440198-custom-data-retention-controls-for-claude-enterprise)
|
||||
|
||||
- **Minimum retention**: 30 days
|
||||
- **Retention start**: Last observed activity (last message or project update)
|
||||
- **Custom periods**: Available for organizations
|
||||
|
||||
### Local Storage (No Official Policy)
|
||||
**Finding**: No official documentation found regarding:
|
||||
- Recommended local .jsonl file retention periods
|
||||
- Automatic cleanup of old conversations
|
||||
- Performance thresholds for file sizes
|
||||
- Safe deletion procedures
|
||||
|
||||
**Current Tools**:
|
||||
- `claude history clear`: Removes ALL history (all projects, destructive)
|
||||
- No selective cleanup tools available
|
||||
- No archive functionality
|
||||
|
||||
---
|
||||
|
||||
## 4. Best Practices (Official & Community)
|
||||
|
||||
### Official Recommendations
|
||||
|
||||
#### Context Management
|
||||
**Source**: [Claude Code Best Practices](https://www.anthropic.com/engineering/claude-code-best-practices)
|
||||
|
||||
**Key Guidelines**:
|
||||
1. **Use `/clear` frequently**: "Reset context window between tasks"
|
||||
2. **Scope conversations**: "One project or feature per conversation"
|
||||
3. **Clear before switching**: "/clear before fixing bugs to prevent context pollution"
|
||||
4. **Don't rely on long context**: "Claude's context window can fill with irrelevant conversation"
|
||||
|
||||
**Quote**: "During long sessions, Claude's context window can fill with irrelevant conversation, file contents, and commands which can reduce performance, so use the /clear command frequently between tasks to reset the context window."
|
||||
|
||||
#### CLAUDE.md Strategy
|
||||
- **Persistent context**: Use CLAUDE.md files for stable instructions
|
||||
- **Auto-loaded**: "Claude automatically pulls into context when starting"
|
||||
- **Hierarchy**: Global (`~/.claude/CLAUDE.md`) → Workspace → Project
|
||||
- **Refinement**: "Take time to experiment and determine what produces best results"
|
||||
|
||||
#### When to Restart vs /clear
|
||||
**Source**: [Community Best Practices](https://claudelog.com/faqs/does-claude-code-store-my-data/)
|
||||
|
||||
**Use `/clear` when**:
|
||||
- Starting new task/feature
|
||||
- Switching between features
|
||||
- Context becomes polluted
|
||||
- Before bug fixing
|
||||
|
||||
**Restart session when**:
|
||||
- Switching projects
|
||||
- Updating CLAUDE.md files
|
||||
- Experiencing session issues
|
||||
- Memory usage high
|
||||
|
||||
### Community Strategies
|
||||
|
||||
#### Conversation Organization
|
||||
**Pattern**: "Scope a chat to one project or feature"
|
||||
- Start conversation for specific goal
|
||||
- Use `/clear` when goal complete
|
||||
- Don't mix unrelated tasks in same conversation
|
||||
|
||||
#### Context Optimization
|
||||
**Pattern**: "Avoid extensive, unrefined context"
|
||||
- Iterate on CLAUDE.md effectiveness
|
||||
- Remove ineffective instructions
|
||||
- Test and refine periodically
|
||||
|
||||
#### Incognito Mode for Sensitive Work
|
||||
**Pattern**: "Ghost icon for temporary conversations"
|
||||
- Not saved to chat history
|
||||
- No contribution to context memory
|
||||
- Useful for experimental or sensitive work
|
||||
|
||||
---
|
||||
|
||||
## 5. Recommended Rotation Policy
|
||||
|
||||
### Immediate Actions (No Risk)
|
||||
|
||||
#### 1. Delete Very Old Conversations (>30 days)
|
||||
```bash
|
||||
# Backup first
|
||||
mkdir -p ~/.claude/projects-archive/$(date +%Y-%m)
|
||||
|
||||
# Find and archive
|
||||
find ~/.claude/projects/ -name "*.jsonl" -mtime +30 -type f \
|
||||
-exec mv {} ~/.claude/projects-archive/$(date +%Y-%m)/ \;
|
||||
```
|
||||
|
||||
**Rationale**:
|
||||
- Aligns with Anthropic's 30-day back-end retention
|
||||
- Minimal functionality loss (context rarely useful after 30 days)
|
||||
- Significant space savings
|
||||
|
||||
#### 2. Archive Project-Specific Old Conversations (>14 days)
|
||||
```bash
|
||||
# Per-project archive
|
||||
mkdir -p ~/.claude/projects-archive/agiletec/$(date +%Y-%m)
|
||||
|
||||
find ~/.claude/projects/-Users-kazuki-github-agiletec -name "*.jsonl" -mtime +14 -type f \
|
||||
-exec mv {} ~/.claude/projects-archive/agiletec/$(date +%Y-%m)/ \;
|
||||
```
|
||||
|
||||
**Rationale**:
|
||||
- 14 days provides buffer for resumed work
|
||||
- Most development tasks complete within 2 weeks
|
||||
- Easy to restore if needed
|
||||
|
||||
### Periodic Maintenance (Weekly)
|
||||
|
||||
#### 3. Identify Large Files for Manual Review
|
||||
```bash
|
||||
# Find files >1MB
|
||||
find ~/.claude/projects/ -name "*.jsonl" -type f -size +1M -exec ls -lh {} \;
|
||||
|
||||
# Review and archive if not actively used
|
||||
```
|
||||
|
||||
**Criteria for Archival**:
|
||||
- File >1MB and not modified in 7 days
|
||||
- Completed feature/project conversations
|
||||
- Debugging sessions that are resolved
|
||||
|
||||
### Aggressive Cleanup (Monthly)
|
||||
|
||||
#### 4. Archive All Inactive Conversations (>7 days)
|
||||
```bash
|
||||
# Monthly archive
|
||||
mkdir -p ~/.claude/projects-archive/$(date +%Y-%m)
|
||||
|
||||
find ~/.claude/projects/ -name "*.jsonl" -mtime +7 -type f \
|
||||
-exec mv {} ~/.claude/projects-archive/$(date +%Y-%m)/ \;
|
||||
```
|
||||
|
||||
**When to Use**:
|
||||
- Project directory >50MB
|
||||
- Startup performance degraded
|
||||
- Running low on disk space
|
||||
|
||||
### Emergency Cleanup (Performance Issues)
|
||||
|
||||
#### 5. Nuclear Option - Keep Only Recent Week
|
||||
```bash
|
||||
# BACKUP EVERYTHING FIRST
|
||||
tar -czf ~/claude-history-backup-$(date +%Y%m%d).tar.gz ~/.claude/projects/
|
||||
|
||||
# Keep only last 7 days
|
||||
find ~/.claude/projects/ -name "*.jsonl" -mtime +7 -type f -delete
|
||||
```
|
||||
|
||||
**When to Use**:
|
||||
- Claude Code startup >10 seconds
|
||||
- Memory usage abnormally high
|
||||
- Experiencing Issue #7985 symptoms
|
||||
|
||||
---
|
||||
|
||||
## 6. Proposed Automated Solution
|
||||
|
||||
### Shell Script: `claude-history-rotate.sh`
|
||||
```bash
|
||||
#!/usr/bin/env bash
|
||||
# Claude Code Conversation History Rotation
|
||||
# Usage: ./claude-history-rotate.sh [--dry-run] [--days N]
|
||||
|
||||
set -euo pipefail
|
||||
|
||||
DAYS=${DAYS:-30}
|
||||
DRY_RUN=false
|
||||
ARCHIVE_BASE=~/.claude/projects-archive
|
||||
|
||||
# Parse arguments
|
||||
while [[ $# -gt 0 ]]; do
|
||||
case $1 in
|
||||
--dry-run) DRY_RUN=true; shift ;;
|
||||
--days) DAYS="$2"; shift 2 ;;
|
||||
*) echo "Unknown option: $1"; exit 1 ;;
|
||||
esac
|
||||
done
|
||||
|
||||
# Create archive directory
|
||||
ARCHIVE_DIR="$ARCHIVE_BASE/$(date +%Y-%m)"
|
||||
mkdir -p "$ARCHIVE_DIR"
|
||||
|
||||
# Find old conversations
|
||||
OLD_FILES=$(find ~/.claude/projects/ -name "*.jsonl" -mtime "+$DAYS" -type f)
|
||||
|
||||
if [[ -z "$OLD_FILES" ]]; then
|
||||
echo "No files older than $DAYS days found."
|
||||
exit 0
|
||||
fi
|
||||
|
||||
# Count and size
|
||||
FILE_COUNT=$(echo "$OLD_FILES" | wc -l | tr -d ' ')
|
||||
TOTAL_SIZE=$(echo "$OLD_FILES" | xargs du -ch | tail -1 | awk '{print $1}')
|
||||
|
||||
echo "Found $FILE_COUNT files older than $DAYS days ($TOTAL_SIZE total)"
|
||||
|
||||
if [[ "$DRY_RUN" == "true" ]]; then
|
||||
echo "DRY RUN - Would archive:"
|
||||
echo "$OLD_FILES"
|
||||
exit 0
|
||||
fi
|
||||
|
||||
# Archive files
|
||||
echo "$OLD_FILES" | while read -r file; do
|
||||
mv "$file" "$ARCHIVE_DIR/"
|
||||
echo "Archived: $(basename "$file")"
|
||||
done
|
||||
|
||||
echo "✓ Archived $FILE_COUNT files to $ARCHIVE_DIR"
|
||||
```
|
||||
|
||||
### Cron Job Setup (Optional)
|
||||
```bash
|
||||
# Add to crontab (monthly cleanup)
|
||||
# 0 3 1 * * /Users/kazuki/.local/bin/claude-history-rotate.sh --days 30
|
||||
|
||||
# Or use launchd on macOS
|
||||
cat > ~/Library/LaunchAgents/com.user.claude-history-rotate.plist <<'EOF'
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
|
||||
<plist version="1.0">
|
||||
<dict>
|
||||
<key>Label</key>
|
||||
<string>com.user.claude-history-rotate</string>
|
||||
<key>ProgramArguments</key>
|
||||
<array>
|
||||
<string>/Users/kazuki/.local/bin/claude-history-rotate.sh</string>
|
||||
<string>--days</string>
|
||||
<string>30</string>
|
||||
</array>
|
||||
<key>StartCalendarInterval</key>
|
||||
<dict>
|
||||
<key>Day</key>
|
||||
<integer>1</integer>
|
||||
<key>Hour</key>
|
||||
<integer>3</integer>
|
||||
</dict>
|
||||
</dict>
|
||||
</plist>
|
||||
EOF
|
||||
|
||||
launchctl load ~/Library/LaunchAgents/com.user.claude-history-rotate.plist
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 7. Monitoring & Alerts
|
||||
|
||||
### Disk Usage Check Script
|
||||
```bash
|
||||
#!/usr/bin/env bash
|
||||
# claude-history-check.sh
|
||||
|
||||
THRESHOLD_MB=100
|
||||
PROJECTS_DIR=~/.claude/projects
|
||||
|
||||
TOTAL_SIZE_MB=$(du -sm "$PROJECTS_DIR" | awk '{print $1}')
|
||||
|
||||
echo "Claude Code conversation history: ${TOTAL_SIZE_MB}MB"
|
||||
|
||||
if [[ $TOTAL_SIZE_MB -gt $THRESHOLD_MB ]]; then
|
||||
echo "⚠️ WARNING: History size exceeds ${THRESHOLD_MB}MB threshold"
|
||||
echo "Consider running: claude-history-rotate.sh --days 30"
|
||||
|
||||
# Find largest projects
|
||||
echo ""
|
||||
echo "Largest projects:"
|
||||
du -sm "$PROJECTS_DIR"/*/ | sort -rn | head -5
|
||||
fi
|
||||
```
|
||||
|
||||
### Performance Indicators to Watch
|
||||
1. **Startup time**: >5 seconds = investigate
|
||||
2. **File sizes**: >2MB per conversation = review
|
||||
3. **Total size**: >100MB across all projects = cleanup
|
||||
4. **Memory usage**: >2GB during session = Issue #7985
|
||||
5. **Conversation length**: >500 message pairs = use `/clear`
|
||||
|
||||
---
|
||||
|
||||
## 8. Key Takeaways & Recommendations
|
||||
|
||||
### Critical Findings
|
||||
|
||||
✅ **Safe to Delete**:
|
||||
- Conversations >30 days old (aligns with Anthropic retention)
|
||||
- Completed feature/project conversations
|
||||
- Large files (>1MB) not accessed in 14+ days
|
||||
|
||||
⚠️ **Caution Required**:
|
||||
- Active project conversations (<7 days)
|
||||
- Files referenced in recent work
|
||||
- Conversations with unfinished tasks
|
||||
|
||||
❌ **Known Issues**:
|
||||
- No official cleanup tools (Issue #5024)
|
||||
- Memory leaks in long sessions (Issue #7985)
|
||||
- `/clear` command bugs (Issue #8755)
|
||||
- Conversation compaction broken (Issue #8839)
|
||||
|
||||
### Recommended Policy for Your Environment
|
||||
|
||||
**Daily Practice**:
|
||||
- Use `/clear` between major tasks
|
||||
- Scope conversations to single features
|
||||
- Restart session if >2 hours continuous work
|
||||
|
||||
**Weekly Review** (Sunday):
|
||||
```bash
|
||||
# Check current state
|
||||
du -sh ~/.claude/projects/*/
|
||||
|
||||
# Archive old conversations (>14 days)
|
||||
claude-history-rotate.sh --days 14 --dry-run # Preview
|
||||
claude-history-rotate.sh --days 14 # Execute
|
||||
```
|
||||
|
||||
**Monthly Cleanup** (1st of month):
|
||||
```bash
|
||||
# Aggressive cleanup (>30 days)
|
||||
claude-history-rotate.sh --days 30
|
||||
|
||||
# Review large files
|
||||
find ~/.claude/projects/ -name "*.jsonl" -size +1M -mtime +7
|
||||
```
|
||||
|
||||
**Performance Threshold Actions**:
|
||||
- Total size >50MB: Archive 30-day-old conversations
|
||||
- Total size >100MB: Archive 14-day-old conversations
|
||||
- Total size >200MB: Emergency cleanup (7-day retention)
|
||||
- Startup >10s: Investigate memory leaks, consider Issue #7985
|
||||
|
||||
### Future-Proofing
|
||||
|
||||
**Watch for Official Solutions**:
|
||||
- `claude history prune` command (requested in #5024)
|
||||
- Automatic history rotation feature
|
||||
- Configurable retention settings
|
||||
- Separate configuration from history storage
|
||||
|
||||
**Community Tools**:
|
||||
- [cclogviewer](https://github.com/hesreallyhim/awesome-claude-code): View .jsonl files
|
||||
- Consider contributing to #5024 discussion
|
||||
- Monitor anthropics/claude-code releases
|
||||
|
||||
---
|
||||
|
||||
## 9. References
|
||||
|
||||
### Official Documentation
|
||||
- [Claude Code Best Practices](https://www.anthropic.com/engineering/claude-code-best-practices)
|
||||
- [How Long Do You Store My Data?](https://privacy.claude.com/en/articles/10023548-how-long-do-you-store-my-data)
|
||||
- [Custom Data Retention Controls](https://privacy.anthropic.com/en/articles/10440198-custom-data-retention-controls-for-claude-enterprise)
|
||||
|
||||
### GitHub Issues
|
||||
- [#5024: History accumulation causes performance issues](https://github.com/anthropics/claude-code/issues/5024)
|
||||
- [#7985: Severe memory leak](https://github.com/anthropics/claude-code/issues/7985)
|
||||
- [#8839: Conversation compaction failure](https://github.com/anthropics/claude-code/issues/8839)
|
||||
- [#8755: /clear command not working](https://github.com/anthropics/claude-code/issues/8755)
|
||||
|
||||
### Community Resources
|
||||
- [Awesome Claude Code](https://github.com/hesreallyhim/awesome-claude-code)
|
||||
- [Claude Code Context Guide](https://www.arsturn.com/blog/beyond-prompting-a-guide-to-managing-context-in-claude-code)
|
||||
- [ClaudeLog Documentation](https://claudelog.com/)
|
||||
|
||||
---
|
||||
|
||||
## Appendix: Current Environment Statistics
|
||||
|
||||
**Generated**: 2025-10-09 04:24 JST
|
||||
|
||||
### Project Size Breakdown
|
||||
```
|
||||
33M -Users-kazuki-github-agiletec (57 files)
|
||||
14M -Volumes-SSD-2TB (project count: N/A)
|
||||
6.3M -Users-kazuki-github-tokium
|
||||
2.6M -Users-kazuki-github-bunseki
|
||||
1.9M -Users-kazuki
|
||||
1.9M -Users-kazuki-github-superclaude
|
||||
---
|
||||
Total: ~62MB across all projects
|
||||
```
|
||||
|
||||
### agiletec Project Details
|
||||
- **Total conversations**: 57
|
||||
- **Largest file**: 2.6MB (d4852655-b760-4311-8f67-26f593f2403f.jsonl)
|
||||
- **Files >1MB**: 3 files
|
||||
- **Avg file size**: ~580KB
|
||||
- **Files >7 days**: 4 files
|
||||
- **Files >30 days**: 0 files
|
||||
|
||||
### Immediate Recommendation
|
||||
**Status**: ✅ Healthy (no immediate action required)
|
||||
|
||||
**Reasoning**:
|
||||
- Total size (33MB) well below concern threshold (100MB)
|
||||
- No files >30 days old
|
||||
- Only 4 files >7 days old
|
||||
- Largest file (2.6MB) within acceptable range
|
||||
|
||||
**Next Review**: 2025-10-16 (weekly check)
|
||||
79
docs/reference/common-issues.md
Normal file
79
docs/reference/common-issues.md
Normal file
@@ -0,0 +1,79 @@
|
||||
# SuperClaude Common Issues - Quick Reference 🚀
|
||||
|
||||
**Problem Solving Guide**: Most frequent issues with practical solutions.
|
||||
|
||||
## Top 5 Quick Fixes (90% of Issues)
|
||||
|
||||
### 1. Commands Not Working in Claude Code ⚡
|
||||
```
|
||||
Problem: /sc:brainstorm doesn't work
|
||||
Solution: Restart Claude Code completely
|
||||
Test: /sc:brainstorm "test" should ask questions
|
||||
```
|
||||
|
||||
### 2. Installation Verification
|
||||
```bash
|
||||
python3 -m SuperClaude --version # Should show 4.1.5
|
||||
|
||||
# If not working:
|
||||
# For pipx users
|
||||
pipx upgrade SuperClaude
|
||||
|
||||
# For pip users
|
||||
pip install --upgrade SuperClaude
|
||||
|
||||
# Then reinstall
|
||||
python3 -m SuperClaude install
|
||||
```
|
||||
|
||||
### 3. Permission Issues
|
||||
```bash
|
||||
# Permission denied / PEP 668 errors:
|
||||
# Option 1: Use pipx (recommended)
|
||||
pipx install SuperClaude
|
||||
|
||||
# Option 2: Use pip with --user
|
||||
pip install --user SuperClaude
|
||||
|
||||
# Option 3: Fix permissions
|
||||
sudo chown -R $USER ~/.claude
|
||||
```
|
||||
|
||||
### 4. MCP Server Issues
|
||||
```bash
|
||||
/sc:analyze . --no-mcp # Test without MCP servers
|
||||
node --version # Check Node.js 16+ if needed
|
||||
```
|
||||
|
||||
### 5. Component Missing
|
||||
```bash
|
||||
python3 -m SuperClaude install --components core commands agents modes --force
|
||||
```
|
||||
|
||||
## Platform-Specific Issues
|
||||
|
||||
**Windows:**
|
||||
```cmd
|
||||
set CLAUDE_CONFIG_DIR=%USERPROFILE%\.claude
|
||||
python -m SuperClaude install --install-dir "%CLAUDE_CONFIG_DIR%"
|
||||
```
|
||||
|
||||
**macOS:**
|
||||
```bash
|
||||
brew install python3 node
|
||||
pip3 install SuperClaude
|
||||
```
|
||||
|
||||
**Linux:**
|
||||
```bash
|
||||
sudo apt install python3 python3-pip nodejs
|
||||
pip3 install SuperClaude
|
||||
```
|
||||
|
||||
## Verification Checklist
|
||||
- [ ] `python3 -m SuperClaude --version` returns 4.1.5
|
||||
- [ ] `/sc:brainstorm "test"` works in Claude Code
|
||||
- [ ] `SuperClaude install --list-components` shows components
|
||||
|
||||
## When Quick Fixes Don't Work
|
||||
See [Troubleshooting Guide](troubleshooting.md) for advanced diagnostics.
|
||||
338
docs/reference/diagnostic-reference.md
Normal file
338
docs/reference/diagnostic-reference.md
Normal file
@@ -0,0 +1,338 @@
|
||||
# SuperClaude Diagnostic Reference Guide
|
||||
|
||||
## Overview
|
||||
|
||||
This guide provides procedures for diagnosing issues with SuperClaude context files and configurations. Since SuperClaude is a collection of text files (not running software), diagnostics focus on file verification and configuration checking.
|
||||
|
||||
**Important**: There are no processes to monitor, no performance metrics to measure, and no system resources to analyze. SuperClaude is purely configuration files that Claude Code reads.
|
||||
|
||||
## Quick Diagnostics
|
||||
|
||||
### One-Line Health Check
|
||||
|
||||
```bash
|
||||
# Quick status check
|
||||
ls ~/.claude/CLAUDE.md && echo "✅ SuperClaude installed" || echo "❌ Not installed"
|
||||
```
|
||||
|
||||
### Basic Diagnostic Commands
|
||||
|
||||
```bash
|
||||
# Check if SuperClaude is installed
|
||||
python3 -m SuperClaude --version
|
||||
|
||||
# Count context files
|
||||
find ~/.claude -name "*.md" -type f | wc -l
|
||||
# Expected: 40+ files
|
||||
|
||||
# Check file sizes (context files should have content)
|
||||
find ~/.claude -name "*.md" -type f -size 0
|
||||
# Expected: No output (no empty files)
|
||||
|
||||
# Verify directory structure
|
||||
tree -L 2 ~/.claude/
|
||||
# Or without tree command:
|
||||
ls -la ~/.claude/
|
||||
```
|
||||
|
||||
## File System Diagnostics
|
||||
|
||||
### Context File Verification
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# Comprehensive context file check
|
||||
|
||||
echo "=== SuperClaude Context File Diagnostic ==="
|
||||
|
||||
# Define expected counts
|
||||
EXPECTED_AGENTS=14
|
||||
EXPECTED_COMMANDS=21
|
||||
EXPECTED_MODES=6
|
||||
|
||||
# Count actual files
|
||||
ACTUAL_AGENTS=$(ls ~/.claude/agents/*.md 2>/dev/null | wc -l)
|
||||
ACTUAL_COMMANDS=$(ls ~/.claude/commands/*.md 2>/dev/null | wc -l)
|
||||
ACTUAL_MODES=$(ls ~/.claude/modes/*.md 2>/dev/null | wc -l)
|
||||
|
||||
# Report findings
|
||||
echo "Agents: $ACTUAL_AGENTS/$EXPECTED_AGENTS $([ $ACTUAL_AGENTS -ge $EXPECTED_AGENTS ] && echo ✅ || echo ⚠️)"
|
||||
echo "Commands: $ACTUAL_COMMANDS/$EXPECTED_COMMANDS $([ $ACTUAL_COMMANDS -ge $EXPECTED_COMMANDS ] && echo ✅ || echo ⚠️)"
|
||||
echo "Modes: $ACTUAL_MODES/$EXPECTED_MODES $([ $ACTUAL_MODES -ge $EXPECTED_MODES ] && echo ✅ || echo ⚠️)"
|
||||
|
||||
# Check core files
|
||||
for file in CLAUDE.md FLAGS.md RULES.md PRINCIPLES.md; do
|
||||
if [ -f ~/.claude/$file ]; then
|
||||
SIZE=$(wc -c < ~/.claude/$file)
|
||||
echo "$file: $SIZE bytes ✅"
|
||||
else
|
||||
echo "$file: MISSING ❌"
|
||||
fi
|
||||
done
|
||||
```
|
||||
|
||||
### Import System Check
|
||||
|
||||
```bash
|
||||
# Verify import statements in CLAUDE.md
|
||||
echo "=== Import System Check ==="
|
||||
if [ -f ~/.claude/CLAUDE.md ]; then
|
||||
echo "Imports found in CLAUDE.md:"
|
||||
grep "^@import" ~/.claude/CLAUDE.md
|
||||
|
||||
# Count import statements
|
||||
IMPORT_COUNT=$(grep -c "^@import" ~/.claude/CLAUDE.md)
|
||||
echo "Total imports: $IMPORT_COUNT"
|
||||
|
||||
if [ $IMPORT_COUNT -ge 5 ]; then
|
||||
echo "✅ Import system configured correctly"
|
||||
else
|
||||
echo "⚠️ Some imports may be missing"
|
||||
fi
|
||||
else
|
||||
echo "❌ CLAUDE.md not found"
|
||||
fi
|
||||
```
|
||||
|
||||
## Configuration Diagnostics
|
||||
|
||||
### MCP Server Configuration Check
|
||||
|
||||
```bash
|
||||
# Check MCP configuration
|
||||
echo "=== MCP Configuration Diagnostic ==="
|
||||
|
||||
CONFIG_FILE=~/.claude.json
|
||||
|
||||
if [ -f "$CONFIG_FILE" ]; then
|
||||
echo "✅ Configuration file exists"
|
||||
|
||||
# Validate JSON syntax
|
||||
if python3 -c "import json; json.load(open('$CONFIG_FILE'))" 2>/dev/null; then
|
||||
echo "✅ Valid JSON syntax"
|
||||
|
||||
# List configured servers
|
||||
echo "Configured MCP servers:"
|
||||
python3 -c "
|
||||
import json
|
||||
with open('$HOME/.claude.json') as f:
|
||||
config = json.load(f)
|
||||
if 'mcpServers' in config:
|
||||
for server in config['mcpServers']:
|
||||
print(f' - {server}')
|
||||
else:
|
||||
print(' No servers configured')
|
||||
"
|
||||
else
|
||||
echo "❌ Invalid JSON syntax in $CONFIG_FILE"
|
||||
fi
|
||||
else
|
||||
echo "⚠️ No MCP configuration file found"
|
||||
echo " This is OK if you don't use MCP servers"
|
||||
fi
|
||||
```
|
||||
|
||||
### Permission Diagnostics
|
||||
|
||||
```bash
|
||||
# Check file permissions
|
||||
echo "=== File Permission Check ==="
|
||||
|
||||
# Check if files are readable
|
||||
UNREADABLE_COUNT=0
|
||||
for file in ~/.claude/**/*.md; do
|
||||
if [ ! -r "$file" ]; then
|
||||
echo "❌ Cannot read: $file"
|
||||
((UNREADABLE_COUNT++))
|
||||
fi
|
||||
done
|
||||
|
||||
if [ $UNREADABLE_COUNT -eq 0 ]; then
|
||||
echo "✅ All context files are readable"
|
||||
else
|
||||
echo "⚠️ Found $UNREADABLE_COUNT unreadable files"
|
||||
echo "Fix with: chmod 644 ~/.claude/**/*.md"
|
||||
fi
|
||||
|
||||
# Check directory permissions
|
||||
for dir in ~/.claude ~/.claude/agents ~/.claude/commands ~/.claude/modes; do
|
||||
if [ -d "$dir" ]; then
|
||||
if [ -x "$dir" ]; then
|
||||
echo "✅ $dir is accessible"
|
||||
else
|
||||
echo "❌ $dir is not accessible"
|
||||
fi
|
||||
else
|
||||
echo "❌ $dir does not exist"
|
||||
fi
|
||||
done
|
||||
```
|
||||
|
||||
## Common Issue Diagnostics
|
||||
|
||||
### Issue: Commands Not Recognized
|
||||
|
||||
```bash
|
||||
# Diagnose command issues
|
||||
COMMAND="implement" # Change to test different commands
|
||||
|
||||
echo "=== Diagnosing command: $COMMAND ==="
|
||||
|
||||
FILE=~/.claude/commands/$COMMAND.md
|
||||
|
||||
if [ -f "$FILE" ]; then
|
||||
echo "✅ Command file exists"
|
||||
|
||||
# Check file size
|
||||
SIZE=$(wc -c < "$FILE")
|
||||
if [ $SIZE -gt 100 ]; then
|
||||
echo "✅ File has content ($SIZE bytes)"
|
||||
else
|
||||
echo "⚠️ File seems too small ($SIZE bytes)"
|
||||
fi
|
||||
|
||||
# Check for metadata
|
||||
if head -10 "$FILE" | grep -q "^---"; then
|
||||
echo "✅ Has metadata header"
|
||||
else
|
||||
echo "⚠️ Missing metadata header"
|
||||
fi
|
||||
|
||||
# Check for command pattern
|
||||
if grep -q "/sc:$COMMAND" "$FILE"; then
|
||||
echo "✅ Contains command pattern"
|
||||
else
|
||||
echo "⚠️ Missing command pattern"
|
||||
fi
|
||||
else
|
||||
echo "❌ Command file not found: $FILE"
|
||||
echo "Available commands:"
|
||||
ls ~/.claude/commands/ | sed 's/.md$//'
|
||||
fi
|
||||
```
|
||||
|
||||
### Issue: Agent Not Activating
|
||||
|
||||
```bash
|
||||
# Diagnose agent issues
|
||||
AGENT="python-expert" # Change to test different agents
|
||||
|
||||
echo "=== Diagnosing agent: $AGENT ==="
|
||||
|
||||
FILE=~/.claude/agents/$AGENT.md
|
||||
|
||||
if [ -f "$FILE" ]; then
|
||||
echo "✅ Agent file exists"
|
||||
|
||||
# Check for trigger keywords
|
||||
echo "Trigger keywords found:"
|
||||
grep -A 5 "## Triggers" "$FILE" | tail -n +2
|
||||
|
||||
# Check for metadata
|
||||
if head -10 "$FILE" | grep -q "^name:"; then
|
||||
echo "✅ Has metadata"
|
||||
else
|
||||
echo "⚠️ Missing metadata"
|
||||
fi
|
||||
else
|
||||
echo "❌ Agent file not found: $FILE"
|
||||
echo "Available agents:"
|
||||
ls ~/.claude/agents/ | sed 's/.md$//'
|
||||
fi
|
||||
```
|
||||
|
||||
## Installation Repair
|
||||
|
||||
### Quick Fix Script
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# SuperClaude Quick Fix Script
|
||||
|
||||
echo "=== SuperClaude Quick Fix ==="
|
||||
|
||||
# Check for common issues and fix them
|
||||
ISSUES_FOUND=0
|
||||
|
||||
# Fix permissions
|
||||
echo "Fixing file permissions..."
|
||||
chmod 644 ~/.claude/*.md 2>/dev/null
|
||||
chmod 644 ~/.claude/**/*.md 2>/dev/null
|
||||
chmod 755 ~/.claude ~/.claude/agents ~/.claude/commands ~/.claude/modes 2>/dev/null
|
||||
|
||||
# Check for missing directories
|
||||
for dir in agents commands modes; do
|
||||
if [ ! -d ~/.claude/$dir ]; then
|
||||
echo "⚠️ Missing directory: $dir"
|
||||
echo " Run: SuperClaude install --components $dir"
|
||||
((ISSUES_FOUND++))
|
||||
fi
|
||||
done
|
||||
|
||||
# Check for empty files
|
||||
EMPTY_FILES=$(find ~/.claude -name "*.md" -type f -size 0 2>/dev/null)
|
||||
if [ -n "$EMPTY_FILES" ]; then
|
||||
echo "⚠️ Found empty files:"
|
||||
echo "$EMPTY_FILES"
|
||||
echo " Run: SuperClaude install --force"
|
||||
((ISSUES_FOUND++))
|
||||
fi
|
||||
|
||||
if [ $ISSUES_FOUND -eq 0 ]; then
|
||||
echo "✅ No issues found"
|
||||
else
|
||||
echo "Found $ISSUES_FOUND issues - see recommendations above"
|
||||
fi
|
||||
```
|
||||
|
||||
### Complete Reinstallation
|
||||
|
||||
```bash
|
||||
# Complete clean reinstall
|
||||
echo "=== Clean Reinstall ==="
|
||||
|
||||
# Backup current installation
|
||||
BACKUP_DIR=~/.claude.backup.$(date +%Y%m%d_%H%M%S)
|
||||
if [ -d ~/.claude ]; then
|
||||
cp -r ~/.claude "$BACKUP_DIR"
|
||||
echo "✅ Backed up to $BACKUP_DIR"
|
||||
fi
|
||||
|
||||
# Remove current installation
|
||||
rm -rf ~/.claude
|
||||
|
||||
# Reinstall
|
||||
SuperClaude install
|
||||
|
||||
# Verify installation
|
||||
if [ -f ~/.claude/CLAUDE.md ]; then
|
||||
echo "✅ Reinstallation successful"
|
||||
else
|
||||
echo "❌ Reinstallation failed"
|
||||
echo "Restoring backup..."
|
||||
cp -r "$BACKUP_DIR" ~/.claude
|
||||
fi
|
||||
```
|
||||
|
||||
## What These Diagnostics DON'T Do
|
||||
|
||||
### Not Applicable Concepts
|
||||
|
||||
- **CPU/Memory Monitoring**: No processes to monitor
|
||||
- **Performance Metrics**: No code execution to measure
|
||||
- **Network Analysis**: No network operations (except MCP)
|
||||
- **Process Management**: No running processes
|
||||
- **Resource Optimization**: No resources consumed
|
||||
- **Execution Timing**: No code executes
|
||||
|
||||
### Focus on What Matters
|
||||
|
||||
- **File Presence**: Are context files installed?
|
||||
- **File Integrity**: Are files readable and complete?
|
||||
- **Configuration Validity**: Is JSON syntax correct?
|
||||
- **Directory Structure**: Is organization correct?
|
||||
- **Permissions**: Can Claude Code read the files?
|
||||
|
||||
## Summary
|
||||
|
||||
SuperClaude diagnostics are simple: verify files exist, check they're readable, and ensure configurations are valid. Since it's just text files that Claude Code reads, there's no complex system monitoring or performance analysis needed. If files are present and readable, SuperClaude is working.
|
||||
172
docs/reference/examples-cookbook.md
Normal file
172
docs/reference/examples-cookbook.md
Normal file
@@ -0,0 +1,172 @@
|
||||
# SuperClaude Examples Cookbook
|
||||
|
||||
**Status**: ✅ **Status: Current** - Comprehensive collection of practical SuperClaude usage examples organized by complexity and domain.
|
||||
|
||||
**Focused Recipe Collections**: The SuperClaude Examples Cookbook has been restructured into three focused collections for better usability and progressive learning.
|
||||
|
||||
## Recipe Collections Overview
|
||||
|
||||
### [Basic Examples Collection](./basic-examples.md)
|
||||
**Essential commands and single-agent workflows**
|
||||
- Copy-paste ready commands for immediate use
|
||||
- Essential SuperClaude patterns and fundamentals
|
||||
- Common development tasks and troubleshooting
|
||||
- Perfect starting point for new users
|
||||
|
||||
**Best for**: New users, quick task execution, learning fundamentals
|
||||
|
||||
### [Advanced Workflows Collection](./advanced-workflows.md)
|
||||
**Multi-agent coordination and complex orchestration**
|
||||
- Multi-agent collaboration patterns
|
||||
- Enterprise-scale project workflows
|
||||
- Session management and persistence
|
||||
- Complex system development patterns
|
||||
|
||||
**Best for**: Experienced users, enterprise projects, complex coordination
|
||||
|
||||
### [Integration Patterns Collection](./integration-patterns.md)
|
||||
**Framework integration and cross-tool coordination**
|
||||
- Framework-specific integration patterns
|
||||
- Performance optimization recipes
|
||||
- Cross-tool coordination strategies
|
||||
- Monitoring and observability patterns
|
||||
|
||||
**Best for**: Expert users, system architects, performance optimization
|
||||
|
||||
## Quick Navigation Guide
|
||||
|
||||
### By Experience Level
|
||||
**Beginner**
|
||||
→ Start with [Basic Examples](./basic-examples.md)
|
||||
- Essential commands and patterns
|
||||
- Simple troubleshooting workflows
|
||||
- Copy-paste solutions for common tasks
|
||||
|
||||
**Intermediate**
|
||||
→ Progress to [Advanced Workflows](./advanced-workflows.md)
|
||||
- Multi-agent coordination
|
||||
- Complex project orchestration
|
||||
- Session management patterns
|
||||
|
||||
**Expert**
|
||||
→ Master [Integration Patterns](./integration-patterns.md)
|
||||
- Framework integration strategies
|
||||
- Performance optimization recipes
|
||||
- Enterprise-scale architecture patterns
|
||||
|
||||
### By Use Case
|
||||
**Web Development**
|
||||
- Frontend: [Basic Examples](./basic-examples.md#frontend-component-development) → [Integration Patterns](./integration-patterns.md#react-ecosystem-integration)
|
||||
- Backend: [Basic Examples](./basic-examples.md#api-development-basics) → [Integration Patterns](./integration-patterns.md#nodejs-backend-integration)
|
||||
- Full-Stack: [Advanced Workflows](./advanced-workflows.md#complete-e-commerce-platform-development)
|
||||
|
||||
**Mobile Development**
|
||||
- React Native: [Basic Examples](./basic-examples.md#copy-paste-quick-solutions) → [Integration Patterns](./integration-patterns.md#mobile-and-web-integration)
|
||||
- Cross-Platform: [Integration Patterns](./integration-patterns.md#cross-platform-integration-patterns)
|
||||
|
||||
**DevOps & Infrastructure**
|
||||
- CI/CD: [Basic Examples](./basic-examples.md#copy-paste-quick-solutions) → [Integration Patterns](./integration-patterns.md#devops-and-infrastructure-integration)
|
||||
- Monitoring: [Advanced Workflows](./advanced-workflows.md#advanced-monitoring-and-observability) → [Integration Patterns](./integration-patterns.md#monitoring-and-observability-patterns)
|
||||
|
||||
**Performance & Security**
|
||||
- Security: [Basic Examples](./basic-examples.md#basic-troubleshooting-examples) → [Advanced Workflows](./advanced-workflows.md#enterprise-scale-security-implementation)
|
||||
- Performance: [Integration Patterns](./integration-patterns.md#performance-optimization-recipes)
|
||||
|
||||
## Verified Commands Reference
|
||||
|
||||
**Core Commands**:
|
||||
- `/sc:brainstorm` - Interactive requirements discovery
|
||||
- `/sc:analyze` - Codebase analysis and assessment
|
||||
- `/sc:implement` - Feature implementation with best practices
|
||||
- `/sc:troubleshoot` - Systematic problem diagnosis
|
||||
- `/sc:test` - Comprehensive testing and validation
|
||||
- `/sc:spawn` - Complex multi-agent coordination
|
||||
- `/sc:load` / `/sc:save` - Session management
|
||||
- `/sc:reflect` - Context analysis and optimization
|
||||
|
||||
**Verified Flags**:
|
||||
- `--think`, `--think-hard`, `--ultrathink` - Analysis depth control
|
||||
- `--uc` - Ultra-compressed token-efficient mode
|
||||
- `--orchestrate` - Intelligent coordination mode
|
||||
- `--c7`, `--serena`, `--all-mcp` - MCP server integration
|
||||
- `--focus [domain]` - Domain-specific optimization
|
||||
- `--scope [level]` - Analysis scope control
|
||||
|
||||
## Learning Progression Roadmap
|
||||
|
||||
### Phase 1: Foundation (Week 1-2)
|
||||
1. **Setup**: Complete [Installation Guide](../getting-started/installation.md)
|
||||
2. **Basics**: Practice [Basic Examples](./basic-examples.md#essential-one-liner-commands)
|
||||
3. **Patterns**: Learn [Basic Usage Patterns](./basic-examples.md#basic-usage-patterns)
|
||||
4. **Success**: Can execute common development tasks independently
|
||||
|
||||
### Phase 2: Coordination (Week 3-6)
|
||||
1. **Agents**: Understand [Multi-Agent Patterns](./advanced-workflows.md#multi-agent-collaboration-patterns)
|
||||
2. **Workflows**: Practice [Complex Project Workflows](./advanced-workflows.md#complex-project-workflows)
|
||||
3. **Orchestration**: Master [Advanced Orchestration](./advanced-workflows.md#advanced-orchestration-patterns)
|
||||
4. **Success**: Can coordinate complex multi-step projects
|
||||
|
||||
### Phase 3: Integration (Month 2+)
|
||||
1. **Frameworks**: Learn [Framework Integration](./integration-patterns.md#framework-integration-patterns)
|
||||
2. **Performance**: Master [Optimization Recipes](./integration-patterns.md#performance-optimization-recipes)
|
||||
3. **Troubleshooting**: Advanced [Debugging Workflows](./integration-patterns.md#advanced-troubleshooting-workflows)
|
||||
4. **Success**: Can integrate SuperClaude with any development stack
|
||||
|
||||
### Phase 4: Expertise (Month 3+)
|
||||
1. **Architecture**: Design custom integration patterns
|
||||
2. **Contribution**: Contribute to SuperClaude framework
|
||||
3. **Leadership**: Mentor community and solve complex problems
|
||||
4. **Success**: Framework development and community leadership
|
||||
|
||||
## Quick Reference Matrix
|
||||
|
||||
| Task Type | Beginner | Intermediate | Expert |
|
||||
|-----------|----------|--------------|--------|
|
||||
| **Analysis** | [Basic Analysis](./basic-examples.md#quick-analysis-commands) | [Multi-Agent Analysis](./advanced-workflows.md#performance-optimization-team) | [Integration Analysis](./integration-patterns.md#distributed-system-debugging) |
|
||||
| **Implementation** | [Simple Features](./basic-examples.md#simple-feature-implementation) | [Complex Projects](./advanced-workflows.md#complex-project-workflows) | [Framework Integration](./integration-patterns.md#framework-integration-patterns) |
|
||||
| **Testing** | [Basic Testing](./basic-examples.md#copy-paste-quick-solutions) | [Comprehensive Testing](./advanced-workflows.md#advanced-workflows) | [Testing Integration](./integration-patterns.md#advanced-testing-integration) |
|
||||
| **Troubleshooting** | [Common Issues](./basic-examples.md#basic-troubleshooting-examples) | [System Debugging](./advanced-workflows.md#advanced-workflows) | [Distributed Debugging](./integration-patterns.md#advanced-troubleshooting-workflows) |
|
||||
| **Performance** | [Basic Optimization](./basic-examples.md#quick-quality-improvements) | [System Optimization](./advanced-workflows.md#performance-optimization-strategies) | [Expert Optimization](./integration-patterns.md#performance-optimization-recipes) |
|
||||
|
||||
## Success Milestones
|
||||
|
||||
### ✅ Basic Proficiency
|
||||
- [ ] Can install and configure SuperClaude
|
||||
- [ ] Comfortable with 5-10 core commands
|
||||
- [ ] Can complete simple workflows independently
|
||||
- [ ] Understands basic flag usage
|
||||
|
||||
### ✅ Intermediate Mastery
|
||||
- [ ] Masters multi-agent coordination
|
||||
- [ ] Can orchestrate complex workflows
|
||||
- [ ] Understands session management
|
||||
- [ ] Comfortable with advanced flag combinations
|
||||
|
||||
### ✅ Expert Integration
|
||||
- [ ] Can integrate any development framework
|
||||
- [ ] Masters performance optimization
|
||||
- [ ] Develops custom integration patterns
|
||||
- [ ] Contributes to framework development
|
||||
|
||||
## Support Resources
|
||||
|
||||
**Documentation**:
|
||||
- [Commands Reference](../user-guide/commands.md) - Complete command documentation
|
||||
- [Agents Guide](../user-guide/agents.md) - Multi-agent coordination
|
||||
- [MCP Servers](../user-guide/mcp-servers.md) - Enhanced capabilities
|
||||
- [Advanced Workflows](./advanced-workflows.md) - Complex coordination patterns
|
||||
|
||||
**Community**:
|
||||
- [GitHub Discussions](https://github.com/SuperClaude-Org/SuperClaude_Framework/discussions) - Community support
|
||||
- [GitHub Issues](https://github.com/SuperClaude-Org/SuperClaude_Framework/issues) - Bug reports and features
|
||||
- [Contributing Guide](../CONTRIBUTING.md) - Framework contribution
|
||||
|
||||
**Advanced**:
|
||||
- [Technical Architecture](../developer-guide/technical-architecture.md) - Deep system understanding
|
||||
- [Troubleshooting Guide](./troubleshooting.md) - Common issues and solutions
|
||||
|
||||
---
|
||||
|
||||
**Your Journey**: Start with [Basic Examples](./basic-examples.md), progress through [Advanced Workflows](./advanced-workflows.md), and master [Integration Patterns](./integration-patterns.md). SuperClaude grows with you from simple commands to sophisticated development orchestration.
|
||||
|
||||
**Remember**: Every expert was once a beginner. Focus on practical application, experiment with different approaches, and leverage the community for support and learning.
|
||||
319
docs/reference/integration-patterns.md
Normal file
319
docs/reference/integration-patterns.md
Normal file
@@ -0,0 +1,319 @@
|
||||
# SuperClaude Integration Patterns Collection
|
||||
|
||||
**Status**: ✅ **Status: Current** - Context patterns for framework integration and tool coordination.
|
||||
|
||||
**Context Integration Guide**: Patterns for using SuperClaude commands effectively with different frameworks and tools. Remember: SuperClaude provides context to Claude Code - all actual work is done by Claude.
|
||||
|
||||
## Overview and Usage Guide
|
||||
|
||||
**Purpose**: Effective patterns for using SuperClaude context with various development frameworks and tools.
|
||||
|
||||
**What This Is**: Command combinations and flag patterns that work well for specific technologies
|
||||
**What This Isn't**: Performance optimization or parallel execution (no code runs)
|
||||
|
||||
**Key Principle**: SuperClaude tells Claude Code WHAT to do and HOW to think about it. Claude Code does the actual work.
|
||||
|
||||
## Framework Context Patterns
|
||||
|
||||
### React Development Patterns
|
||||
|
||||
```bash
|
||||
# React development with appropriate context
|
||||
/sc:implement "React 18 application with TypeScript" --c7
|
||||
# Context7 MCP can provide React documentation if available
|
||||
# Magic MCP can help with UI components if configured
|
||||
|
||||
# What Actually Happens:
|
||||
# 1. Claude reads implement.md for implementation patterns
|
||||
# 2. --c7 flag suggests using Context7 MCP for documentation
|
||||
# 3. Claude generates React code based on these contexts
|
||||
|
||||
# Component development pattern
|
||||
@agent-frontend-architect "design component architecture"
|
||||
/sc:implement "reusable component library"
|
||||
|
||||
# Testing pattern for React
|
||||
/sc:test --focus react
|
||||
# Claude will suggest React Testing Library patterns
|
||||
```
|
||||
|
||||
### Node.js Backend Patterns
|
||||
|
||||
```bash
|
||||
# Node.js backend development patterns
|
||||
/sc:implement "Express.js API with TypeScript" --c7
|
||||
# Claude will create Express API following Node.js patterns
|
||||
|
||||
# What This Means:
|
||||
# - Claude reads context about backend patterns
|
||||
# - Suggests appropriate middleware and structure
|
||||
# - NOT running or optimizing any code
|
||||
|
||||
# Database integration pattern
|
||||
/sc:implement "database models with Prisma"
|
||||
@agent-backend-architect "review database schema"
|
||||
|
||||
# API testing pattern
|
||||
/sc:test --focus api
|
||||
# Claude suggests API testing approaches
|
||||
```
|
||||
|
||||
### Python Development Patterns
|
||||
|
||||
```bash
|
||||
# Python web development
|
||||
/sc:implement "FastAPI application" --c7
|
||||
@agent-python-expert "review implementation"
|
||||
|
||||
# What Happens:
|
||||
# - Claude uses Python-specific context
|
||||
# - Follows FastAPI patterns from context
|
||||
# - Generates code (doesn't run it)
|
||||
|
||||
# Data science context
|
||||
/sc:implement "data analysis pipeline"
|
||||
@agent-python-expert "optimize pandas operations"
|
||||
# Claude provides optimization suggestions (not actual optimization)
|
||||
|
||||
# Testing patterns
|
||||
/sc:test --focus python
|
||||
# Claude suggests pytest patterns
|
||||
```
|
||||
|
||||
### Full-Stack Development Patterns
|
||||
|
||||
```bash
|
||||
# Full-stack application pattern
|
||||
/sc:brainstorm "full-stack application architecture"
|
||||
@agent-system-architect "design system components"
|
||||
|
||||
# Frontend implementation
|
||||
/sc:implement "React frontend with TypeScript"
|
||||
@agent-frontend-architect "review component structure"
|
||||
|
||||
# Backend implementation
|
||||
/sc:implement "Node.js API with authentication"
|
||||
@agent-backend-architect "review API design"
|
||||
|
||||
# Integration
|
||||
/sc:implement "connect frontend to backend API"
|
||||
```
|
||||
|
||||
## Tool Coordination Patterns
|
||||
|
||||
### Using MCP Servers Effectively
|
||||
|
||||
```bash
|
||||
# Context7 for documentation
|
||||
/sc:explain "React hooks" --c7
|
||||
# If Context7 is configured, it may fetch React docs
|
||||
|
||||
# Sequential for complex reasoning
|
||||
/sc:troubleshoot "complex bug" --seq
|
||||
# Sequential MCP helps with structured problem-solving
|
||||
|
||||
# Magic for UI components
|
||||
/sc:implement "UI components" --magic
|
||||
# Magic MCP can help generate modern UI patterns
|
||||
|
||||
# No MCP for simple tasks
|
||||
/sc:implement "utility function" --no-mcp
|
||||
# Uses only Claude's built-in knowledge
|
||||
```
|
||||
|
||||
### Agent and Command Combinations
|
||||
|
||||
```bash
|
||||
# Security-focused development
|
||||
@agent-security "review authentication requirements"
|
||||
/sc:implement "secure authentication system"
|
||||
/sc:analyze --focus security
|
||||
|
||||
# Quality-focused workflow
|
||||
/sc:implement "new feature"
|
||||
@agent-quality-engineer "review code quality"
|
||||
/sc:test --focus quality
|
||||
|
||||
# Architecture-focused approach
|
||||
@agent-system-architect "design microservices"
|
||||
/sc:design "service boundaries"
|
||||
/sc:implement "service communication"
|
||||
```
|
||||
|
||||
## Common Integration Patterns
|
||||
|
||||
### API Development Pattern
|
||||
|
||||
```bash
|
||||
# Step 1: Design
|
||||
/sc:design "REST API structure"
|
||||
|
||||
# Step 2: Implementation
|
||||
/sc:implement "API endpoints with validation"
|
||||
|
||||
# Step 3: Documentation
|
||||
/sc:document --type api
|
||||
|
||||
# Step 4: Testing
|
||||
/sc:test --focus api
|
||||
```
|
||||
|
||||
### Database Integration Pattern
|
||||
|
||||
```bash
|
||||
# Schema design
|
||||
@agent-backend-architect "design database schema"
|
||||
|
||||
# Model implementation
|
||||
/sc:implement "database models"
|
||||
|
||||
# Migration creation
|
||||
/sc:implement "database migrations"
|
||||
|
||||
# Query optimization suggestions
|
||||
@agent-backend-architect "suggest query optimizations"
|
||||
# Note: Claude suggests optimizations, doesn't actually optimize
|
||||
```
|
||||
|
||||
### Testing Strategy Pattern
|
||||
|
||||
```bash
|
||||
# Test planning
|
||||
/sc:design "testing strategy"
|
||||
|
||||
# Unit tests
|
||||
/sc:test --type unit
|
||||
|
||||
# Integration tests
|
||||
/sc:test --type integration
|
||||
|
||||
# E2E test suggestions
|
||||
/sc:test --type e2e
|
||||
# Claude provides test code, not execution
|
||||
```
|
||||
|
||||
## Technology-Specific Patterns
|
||||
|
||||
### React + TypeScript Pattern
|
||||
|
||||
```bash
|
||||
# Project setup guidance
|
||||
/sc:implement "React TypeScript project structure"
|
||||
|
||||
# Component development
|
||||
/sc:implement "TypeScript React components with props validation"
|
||||
|
||||
# State management
|
||||
@agent-frontend-architect "recommend state management approach"
|
||||
/sc:implement "state management with Zustand/Redux"
|
||||
|
||||
# Testing
|
||||
/sc:test --focus react --type unit
|
||||
```
|
||||
|
||||
### Python FastAPI Pattern
|
||||
|
||||
```bash
|
||||
# API structure
|
||||
/sc:implement "FastAPI project structure"
|
||||
|
||||
# Endpoint development
|
||||
@agent-python-expert "implement async endpoints"
|
||||
|
||||
# Database integration
|
||||
/sc:implement "SQLAlchemy models with Alembic"
|
||||
|
||||
# Testing
|
||||
/sc:test --focus python --type integration
|
||||
```
|
||||
|
||||
### Node.js Microservices Pattern
|
||||
|
||||
```bash
|
||||
# Architecture design
|
||||
@agent-system-architect "design microservices architecture"
|
||||
|
||||
# Service implementation
|
||||
/sc:implement "user service with Express"
|
||||
/sc:implement "auth service with JWT"
|
||||
|
||||
# Inter-service communication
|
||||
/sc:implement "service communication patterns"
|
||||
|
||||
# Testing approach
|
||||
/sc:test --focus microservices
|
||||
```
|
||||
|
||||
## Troubleshooting Patterns
|
||||
|
||||
### Debugging Workflow
|
||||
|
||||
```bash
|
||||
# Problem analysis
|
||||
/sc:troubleshoot "describe the issue"
|
||||
|
||||
# Root cause investigation
|
||||
@agent-root-cause-analyst "analyze symptoms"
|
||||
|
||||
# Solution implementation
|
||||
/sc:implement "fix based on analysis"
|
||||
|
||||
# Verification
|
||||
/sc:test --validate
|
||||
```
|
||||
|
||||
### Code Review Pattern
|
||||
|
||||
```bash
|
||||
# Code analysis
|
||||
/sc:analyze code/ --focus quality
|
||||
|
||||
# Security review
|
||||
@agent-security "review for vulnerabilities"
|
||||
|
||||
# Performance review
|
||||
@agent-performance-engineer "suggest improvements"
|
||||
# Note: Suggestions only, no actual performance measurement
|
||||
|
||||
# Implementation of improvements
|
||||
/sc:improve code/ --fix
|
||||
```
|
||||
|
||||
## Important Clarifications
|
||||
|
||||
### What These Patterns DO
|
||||
|
||||
- ✅ Provide structured approaches to development tasks
|
||||
- ✅ Combine commands and agents effectively
|
||||
- ✅ Suggest appropriate tools and frameworks
|
||||
- ✅ Guide Claude to generate better code
|
||||
|
||||
### What These Patterns DON'T DO
|
||||
|
||||
- ❌ Execute code or measure performance
|
||||
- ❌ Run tests or deploy applications
|
||||
- ❌ Optimize actual execution speed
|
||||
- ❌ Provide real monitoring or metrics
|
||||
- ❌ Coordinate parallel processes (everything is sequential text)
|
||||
|
||||
## Best Practices
|
||||
|
||||
### Effective Pattern Usage
|
||||
|
||||
1. **Start with context**: Use `/sc:load` to establish project understanding
|
||||
2. **Layer expertise**: Combine general commands with specific agents
|
||||
3. **Focus appropriately**: Use `--focus` flags for targeted results
|
||||
4. **Manage scope**: Work on specific modules rather than entire codebases
|
||||
5. **Document decisions**: Use `/sc:save` to create summaries
|
||||
|
||||
### Pattern Selection
|
||||
|
||||
- **Simple tasks**: Use basic commands without MCP
|
||||
- **Complex tasks**: Add appropriate agents and MCP servers
|
||||
- **Security-critical**: Always include `@agent-security`
|
||||
- **UI development**: Consider `--magic` flag if configured
|
||||
- **Documentation needs**: Use `--c7` for framework docs
|
||||
|
||||
## Summary
|
||||
|
||||
These integration patterns show how to combine SuperClaude commands, agents, and flags effectively for different development scenarios. Remember that all patterns are about providing better context to Claude Code - the actual code generation, not execution, is what Claude does based on these contexts.
|
||||
755
docs/reference/mcp-server-guide.md
Normal file
755
docs/reference/mcp-server-guide.md
Normal file
@@ -0,0 +1,755 @@
|
||||
# MCP Server Troubleshooting Guide
|
||||
|
||||
**MCP Server Focus**: Model Context Protocol (MCP) servers provide enhanced capabilities like documentation lookup (Context7), UI generation (Magic), and advanced reasoning (Sequential). This guide covers installation, configuration, and operational troubleshooting for all MCP servers.
|
||||
|
||||
**Server-Specific Solutions**: Each MCP server has unique requirements and common failure patterns. This guide provides targeted solutions for each server type and general MCP troubleshooting strategies.
|
||||
|
||||
## MCP Server Overview
|
||||
|
||||
### Available MCP Servers
|
||||
|
||||
**Core MCP Servers:**
|
||||
- **Context7**: Official documentation lookup and framework patterns
|
||||
- **Sequential**: Multi-step reasoning and complex analysis
|
||||
- **Magic**: Modern UI component generation from 21st.dev patterns
|
||||
- **Playwright**: Browser automation and E2E testing
|
||||
- **Morphllm**: Pattern-based code editing with token optimization
|
||||
- **Serena**: Semantic code understanding and project memory
|
||||
|
||||
**Server Requirements:**
|
||||
- Node.js 16.0.0 or higher
|
||||
- npm or yarn package manager
|
||||
- Stable network connection for some servers
|
||||
- Sufficient system memory (2GB+ recommended)
|
||||
|
||||
## Installation and Configuration Issues
|
||||
|
||||
### Node.js and npm Problems
|
||||
|
||||
#### Issue: Node.js Version Incompatibility
|
||||
**Error Message**: `ERROR: MCP servers require Node.js 16+ but found Node.js 14.x`
|
||||
|
||||
**Diagnosis**:
|
||||
```bash
|
||||
node --version
|
||||
npm --version
|
||||
```
|
||||
|
||||
**Solution 1**: Update Node.js (Linux/Ubuntu)
|
||||
```bash
|
||||
curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
|
||||
sudo apt-get install -y nodejs
|
||||
```
|
||||
|
||||
**Solution 2**: Use Node Version Manager (nvm)
|
||||
```bash
|
||||
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
|
||||
source ~/.bashrc
|
||||
nvm install node
|
||||
nvm use node
|
||||
```
|
||||
|
||||
**Solution 3**: Manual Node.js installation
|
||||
- Download from https://nodejs.org/
|
||||
- Follow platform-specific installation instructions
|
||||
|
||||
**Verification**:
|
||||
```bash
|
||||
node --version # Should be 16.0.0+
|
||||
npm --version # Should be 8.0.0+
|
||||
```
|
||||
|
||||
**Issue: npm Permission Problems**
|
||||
```bash
|
||||
# Error message
|
||||
ERROR: EACCES: permission denied, access '/usr/local/lib/node_modules'
|
||||
|
||||
# Solution 1: Configure npm for user directory
|
||||
mkdir ~/.npm-global
|
||||
npm config set prefix '~/.npm-global'
|
||||
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.profile
|
||||
source ~/.profile
|
||||
|
||||
# Solution 2: Fix npm permissions
|
||||
sudo chown -R $(whoami) $(npm config get prefix)/{lib/node_modules,bin,share}
|
||||
|
||||
# Solution 3: Use npx for package execution
|
||||
npx @context7/mcp-server --version
|
||||
|
||||
# Verification
|
||||
npm list -g --depth=0
|
||||
npm config get prefix
|
||||
```
|
||||
|
||||
### MCP Server Installation Failures
|
||||
|
||||
**Issue: Context7 MCP Server Installation Failed**
|
||||
```bash
|
||||
# Error message
|
||||
ERROR: Failed to install @context7/mcp-server
|
||||
|
||||
# Diagnosis
|
||||
npm list -g @context7/mcp-server
|
||||
node --version
|
||||
|
||||
# Solution 1: Clean npm cache and reinstall
|
||||
npm cache clean --force
|
||||
npm install -g @context7/mcp-server
|
||||
|
||||
# Solution 2: Use alternative registry
|
||||
npm install -g @context7/mcp-server --registry https://registry.npmjs.org/
|
||||
|
||||
# Solution 3: Manual installation verification
|
||||
npm info @context7/mcp-server
|
||||
npm install -g @context7/mcp-server@latest
|
||||
|
||||
# Verification
|
||||
npm list -g @context7/mcp-server
|
||||
node -e "console.log('Context7 installation test')"
|
||||
```
|
||||
|
||||
**Issue: Sequential MCP Server Dependencies Missing**
|
||||
```bash
|
||||
# Error message
|
||||
ERROR: Sequential MCP server missing required dependencies
|
||||
|
||||
# Diagnosis
|
||||
npm list -g @sequential/mcp-server
|
||||
npm list -g | grep -E "typescript|@types"
|
||||
|
||||
# Solution 1: Install dependencies explicitly
|
||||
npm install -g typescript @types/node
|
||||
npm install -g @sequential/mcp-server
|
||||
|
||||
# Solution 2: Force reinstall with dependencies
|
||||
npm uninstall -g @sequential/mcp-server
|
||||
npm install -g @sequential/mcp-server --save-dev
|
||||
|
||||
# Solution 3: Check package integrity
|
||||
npm audit --global
|
||||
npm update -g
|
||||
|
||||
# Verification
|
||||
npm list -g @sequential/mcp-server
|
||||
```
|
||||
|
||||
**Issue: Magic UI Generator Installation Problems**
|
||||
```bash
|
||||
# Error message
|
||||
ERROR: @magic/ui-generator installation failed - build dependencies missing
|
||||
|
||||
# Diagnosis
|
||||
npm list -g @magic/ui-generator
|
||||
which gcc make # Check build tools
|
||||
|
||||
# Solution 1: Install build dependencies (Linux)
|
||||
sudo apt install build-essential python3-dev
|
||||
|
||||
# Solution 2: Install build dependencies (macOS)
|
||||
xcode-select --install
|
||||
|
||||
# Solution 3: Use pre-built binaries
|
||||
npm install -g @magic/ui-generator --ignore-scripts
|
||||
|
||||
# Verification
|
||||
npm list -g @magic/ui-generator
|
||||
```
|
||||
|
||||
## Connection and Communication Issues
|
||||
|
||||
### MCP Server Connection Failures
|
||||
|
||||
**Issue: Context7 Server Not Connecting**
|
||||
```bash
|
||||
# Error message
|
||||
ERROR: MCP server 'context7' failed to connect
|
||||
|
||||
# Diagnosis
|
||||
# Check Node.js installation
|
||||
node --version # Should be 16.0.0 or higher
|
||||
npm list -g @context7/mcp-server
|
||||
|
||||
# Check server configuration
|
||||
cat ~/.claude/CLAUDE.md | grep -i context7
|
||||
|
||||
# Solution 1: Restart Claude Code session
|
||||
# MCP servers restart with Claude Code session restart
|
||||
|
||||
# Solution 2: Reconfigure MCP servers
|
||||
python3 -m SuperClaude install --components mcp --force
|
||||
|
||||
# Solution 3: Manual server testing
|
||||
node -e "console.log('Node.js working')"
|
||||
npm test @context7/mcp-server
|
||||
|
||||
# Solution 4: Check network connectivity
|
||||
ping context7-server.example.com # If server requires network
|
||||
curl -I https://context7-api.example.com/health # Health check
|
||||
|
||||
# Verification
|
||||
# Try Context7 functionality in Claude Code
|
||||
# Should respond to documentation requests
|
||||
```
|
||||
|
||||
**Issue: MCP Server Communication Timeout**
|
||||
```bash
|
||||
# Error message
|
||||
ERROR: MCP server request timeout after 30 seconds
|
||||
|
||||
# Diagnosis
|
||||
# Check network connectivity and server health
|
||||
ping 8.8.8.8 # Basic connectivity
|
||||
curl -I https://api.example.com/health # API health
|
||||
|
||||
# Check system resources
|
||||
top
|
||||
free -h
|
||||
|
||||
# Solution 1: Reduce operation complexity
|
||||
# Break complex tasks into smaller parts
|
||||
|
||||
# Solution 2: Restart Claude Code session
|
||||
# MCP servers restart with Claude Code session restart
|
||||
|
||||
# Solution 3: Disable problematic server temporarily
|
||||
# Use --no-mcp flag for operations
|
||||
|
||||
# Solution 4: Increase timeout (if configurable)
|
||||
# Check MCP server configuration files
|
||||
|
||||
# Verification
|
||||
# Test with simple operations first
|
||||
# Gradually increase complexity
|
||||
```
|
||||
|
||||
**Issue: Multiple MCP Servers Conflicting**
|
||||
```bash
|
||||
# Error message
|
||||
ERROR: MCP server port conflicts detected
|
||||
|
||||
# Diagnosis
|
||||
netstat -tlnp | grep :8000 # Check port usage
|
||||
ps aux | grep -E "context7|sequential|magic"
|
||||
|
||||
# Solution 1: Sequential server restart
|
||||
# Restart Claude Code to reset all MCP servers
|
||||
|
||||
# Solution 2: Configure different ports
|
||||
# Edit MCP server configuration files
|
||||
# Usually in ~/.claude/ or server-specific directories
|
||||
|
||||
# Solution 3: Use selective server activation
|
||||
# Use specific server flags instead of --all-mcp
|
||||
|
||||
# Verification
|
||||
netstat -tlnp | grep -E "8000|8001|8002" # Check port assignments
|
||||
```
|
||||
|
||||
## Server-Specific Troubleshooting
|
||||
|
||||
### Context7 Documentation Server
|
||||
|
||||
**Issue: Context7 Not Finding Documentation**
|
||||
```bash
|
||||
# Symptoms: Context7 activated but returns no documentation
|
||||
|
||||
# Diagnosis
|
||||
# Test Context7 connection
|
||||
node -e "const c7 = require('@context7/mcp-server'); console.log('Context7 loaded');"
|
||||
|
||||
# Solution 1: Update Context7 server
|
||||
npm update -g @context7/mcp-server
|
||||
|
||||
# Solution 2: Clear Context7 cache
|
||||
rm -rf ~/.context7/cache/ # If cache directory exists
|
||||
|
||||
# Solution 3: Use explicit library keywords
|
||||
# Use specific framework names in requests
|
||||
|
||||
# Solution 4: Verify internet connection
|
||||
curl -I https://docs.react.dev/ # Example API test
|
||||
|
||||
# Verification
|
||||
# Try specific documentation requests
|
||||
# Should return relevant framework information
|
||||
```
|
||||
|
||||
**Issue: Context7 Returning Outdated Information**
|
||||
```bash
|
||||
# Symptoms: Context7 returns old documentation versions
|
||||
|
||||
# Solution 1: Update Context7 server
|
||||
npm uninstall -g @context7/mcp-server
|
||||
npm install -g @context7/mcp-server@latest
|
||||
|
||||
# Solution 2: Clear documentation cache
|
||||
rm -rf ~/.context7/ # Clear cache if exists
|
||||
|
||||
# Solution 3: Force documentation refresh
|
||||
# Restart Claude Code session completely
|
||||
|
||||
# Verification
|
||||
# Check documentation dates in responses
|
||||
# Should return current framework versions
|
||||
```
|
||||
|
||||
### Sequential Reasoning Server
|
||||
|
||||
**Issue: Sequential Server Internal Errors**
|
||||
```bash
|
||||
# Error message
|
||||
ERROR: Sequential reasoning server encountered internal error
|
||||
|
||||
# Diagnosis
|
||||
# Check Sequential server logs
|
||||
tail -f ~/.claude/logs/sequential-mcp.log # If logs exist
|
||||
|
||||
# Check server installation
|
||||
npm list -g @sequential/mcp-server
|
||||
|
||||
# Solution 1: Restart Claude Code session
|
||||
# This restarts all MCP servers including Sequential
|
||||
|
||||
# Solution 2: Use alternative reasoning approach
|
||||
# Use native Claude reasoning without MCP servers
|
||||
|
||||
# Solution 3: Reinstall Sequential MCP
|
||||
npm uninstall -g @sequential/mcp-server
|
||||
npm install -g @sequential/mcp-server@latest
|
||||
|
||||
# Solution 4: Check memory availability
|
||||
free -h # Ensure sufficient memory for complex reasoning
|
||||
|
||||
# Verification
|
||||
# Test with simple analysis tasks first
|
||||
# Should provide structured reasoning output
|
||||
```
|
||||
|
||||
**Issue: Sequential Server Memory Overload**
|
||||
```bash
|
||||
# Symptoms: Sequential server crashes or becomes unresponsive
|
||||
|
||||
# Diagnosis
|
||||
top | grep -E "sequential|node"
|
||||
free -h
|
||||
|
||||
# Solution 1: Reduce analysis complexity
|
||||
# Break complex problems into smaller parts
|
||||
|
||||
# Solution 2: Increase system memory or swap
|
||||
sudo swapon --show # Check swap status
|
||||
|
||||
# Solution 3: Use scope limiting
|
||||
# Focus analysis on specific components
|
||||
|
||||
# Verification
|
||||
ps aux | grep sequential # Check process status
|
||||
```
|
||||
|
||||
### Magic UI Generator
|
||||
|
||||
**Issue: Magic Not Generating UI Components**
|
||||
```bash
|
||||
# Symptoms: UI component requests not producing expected output
|
||||
|
||||
# Diagnosis
|
||||
# Check Magic server installation
|
||||
npm list -g @magic/ui-generator
|
||||
cat ~/.claude/CLAUDE.md | grep -i magic
|
||||
|
||||
# Solution 1: Verify Magic server installation
|
||||
npm list -g @magic/ui-generator
|
||||
npm install -g @magic/ui-generator@latest
|
||||
|
||||
# Solution 2: Use explicit Magic activation
|
||||
# Include "component", "UI", or "interface" keywords
|
||||
|
||||
# Solution 3: Check component request format
|
||||
# Use descriptive requests for better Magic activation
|
||||
|
||||
# Solution 4: Test Magic server directly
|
||||
node -e "const magic = require('@magic/ui-generator'); console.log('Magic loaded');"
|
||||
|
||||
# Verification
|
||||
# Should produce complete UI components with modern patterns
|
||||
```
|
||||
|
||||
**Issue: Magic Components Not Framework-Compliant**
|
||||
```bash
|
||||
# Symptoms: Generated components don't match framework patterns
|
||||
|
||||
# Solution 1: Use framework-specific keywords
|
||||
# Include "React", "Vue", "Angular" in requests
|
||||
|
||||
# Solution 2: Combine with Context7
|
||||
# Use both Magic and Context7 for framework-compliant components
|
||||
|
||||
# Solution 3: Update Magic server
|
||||
npm update -g @magic/ui-generator
|
||||
|
||||
# Verification
|
||||
# Generated components should follow framework conventions
|
||||
```
|
||||
|
||||
### Playwright Browser Automation
|
||||
|
||||
**Issue: Playwright Browser Installation Failures**
|
||||
```bash
|
||||
# Error message
|
||||
ERROR: Playwright browser automation failed - browser not installed
|
||||
|
||||
# Diagnosis
|
||||
npm list -g playwright
|
||||
npx playwright --version
|
||||
|
||||
# Solution 1: Install Playwright browsers
|
||||
npx playwright install
|
||||
npx playwright install-deps
|
||||
|
||||
# Solution 2: Install specific browsers
|
||||
npx playwright install chromium
|
||||
npx playwright install firefox
|
||||
npx playwright install webkit
|
||||
|
||||
# Solution 3: Fix browser dependencies (Linux)
|
||||
sudo apt-get install libnss3 libatk-bridge2.0-0 libdrm2 libgtk-3-0
|
||||
|
||||
# Verification
|
||||
npx playwright --version
|
||||
ls ~/.cache/ms-playwright/ # Check browser installations
|
||||
```
|
||||
|
||||
**Issue: Playwright Browser Launch Failures**
|
||||
```bash
|
||||
# Error message
|
||||
ERROR: Browser launch failed - display not available
|
||||
|
||||
# Diagnosis
|
||||
echo $DISPLAY # Check X11 display
|
||||
ps aux | grep Xvfb # Check virtual display
|
||||
|
||||
# Solution 1: Use headless mode
|
||||
# Set headless: true in Playwright configuration
|
||||
|
||||
# Solution 2: Install virtual display (Linux)
|
||||
sudo apt-get install xvfb
|
||||
export DISPLAY=:99
|
||||
Xvfb :99 -screen 0 1024x768x24 &
|
||||
|
||||
# Solution 3: Use Docker for browser testing
|
||||
docker run -it --rm playwright:latest
|
||||
|
||||
# Verification
|
||||
# Should successfully launch browsers in headless mode
|
||||
```
|
||||
|
||||
### Morphllm Pattern Editor
|
||||
|
||||
**Issue: Morphllm Pattern Application Failures**
|
||||
```bash
|
||||
# Symptoms: Pattern-based edits not applying correctly
|
||||
|
||||
# Diagnosis
|
||||
npm list -g @morphllm/mcp-server
|
||||
|
||||
# Solution 1: Update Morphllm server
|
||||
npm update -g @morphllm/mcp-server
|
||||
|
||||
# Solution 2: Use more specific patterns
|
||||
# Provide explicit pattern descriptions
|
||||
|
||||
# Solution 3: Check file permissions
|
||||
ls -la target-files/ # Ensure write permissions
|
||||
|
||||
# Verification
|
||||
# Pattern edits should be applied consistently across files
|
||||
```
|
||||
|
||||
### Serena Project Memory
|
||||
|
||||
**Issue: Serena Session Persistence Failures**
|
||||
```bash
|
||||
# Symptoms: Project context not persisting between sessions
|
||||
|
||||
# Diagnosis
|
||||
ls ~/.claude/sessions/ # Check session storage
|
||||
ls ~/.serena/ # Check Serena-specific storage
|
||||
|
||||
# Solution 1: Verify session save operations
|
||||
# Ensure proper session saving before closing
|
||||
|
||||
# Solution 2: Check storage permissions
|
||||
ls -la ~/.claude/sessions/
|
||||
chmod 755 ~/.claude/sessions/
|
||||
|
||||
# Solution 3: Reinstall Serena server
|
||||
# Remove existing Serena registration
|
||||
claude mcp remove serena
|
||||
# Reinstall using uvx
|
||||
uvx --from git+https://github.com/oraios/serena serena --help
|
||||
# Re-register with Claude
|
||||
claude mcp add serena -- uvx --from git+https://github.com/oraios/serena serena start-mcp-server --context ide-assistant
|
||||
|
||||
# Verification
|
||||
# Session context should persist across Claude Code restarts
|
||||
```
|
||||
|
||||
## Performance and Optimization
|
||||
|
||||
### MCP Server Performance Issues
|
||||
|
||||
**Issue: Slow MCP Server Response Times**
|
||||
```bash
|
||||
# Symptoms: MCP server operations causing delays
|
||||
|
||||
# Diagnosis
|
||||
# Check MCP server installation and health
|
||||
npm list -g | grep -E "context7|sequential|magic|playwright"
|
||||
top | grep node
|
||||
|
||||
# Solution 1: Selective MCP server usage
|
||||
# Use only needed servers for specific tasks
|
||||
|
||||
# Solution 2: Restart Claude Code session
|
||||
# This restarts all MCP servers fresh
|
||||
|
||||
# Solution 3: Local fallback mode
|
||||
# Use --no-mcp flag for pure native operations
|
||||
|
||||
# Solution 4: Update all MCP servers
|
||||
npm update -g
|
||||
|
||||
# Verification
|
||||
time node -e "console.log('Node.js speed test')"
|
||||
# Should complete successfully
|
||||
```
|
||||
|
||||
**Issue: MCP Server Memory Leaks**
|
||||
```bash
|
||||
# Symptoms: Increasing memory usage over time
|
||||
|
||||
# Diagnosis
|
||||
top | grep node # Monitor Node.js processes
|
||||
ps aux --sort=-%mem | head -10
|
||||
|
||||
# Solution 1: Regular Claude Code session restarts
|
||||
# Restart sessions periodically during heavy usage
|
||||
|
||||
# Solution 2: Monitor specific servers
|
||||
htop # Monitor individual MCP server processes
|
||||
|
||||
# Solution 3: Use memory-efficient patterns
|
||||
# Avoid keeping large data sets in MCP server memory
|
||||
|
||||
# Verification
|
||||
free -h # Monitor memory usage trends
|
||||
```
|
||||
|
||||
### Resource Management
|
||||
|
||||
**Issue: Multiple MCP Servers Competing for Resources**
|
||||
```bash
|
||||
# Symptoms: System slowdown when multiple servers active
|
||||
|
||||
# Diagnosis
|
||||
top | grep -E "node|mcp"
|
||||
iostat 1 3 # Check I/O usage
|
||||
|
||||
# Solution 1: Use targeted server activation
|
||||
# Activate only needed servers per task
|
||||
|
||||
# Solution 2: Increase system resources
|
||||
# Add more RAM or CPU cores if possible
|
||||
|
||||
# Solution 3: Queue MCP operations
|
||||
# Avoid simultaneous heavy operations
|
||||
|
||||
# Solution 4: Use MCP server priorities
|
||||
# Configure resource allocation in MCP settings
|
||||
|
||||
# Verification
|
||||
top # Monitor resource usage during operations
|
||||
```
|
||||
|
||||
## Advanced MCP Configuration
|
||||
|
||||
### Custom MCP Server Configuration
|
||||
|
||||
**Issue: Default MCP Configuration Not Optimal**
|
||||
```bash
|
||||
# Symptoms: MCP servers not performing optimally for specific use cases
|
||||
|
||||
# Solution 1: Locate configuration files
|
||||
find ~/.claude/ -name "*mcp*" -type f
|
||||
find ~/.config/ -name "*mcp*" -type f
|
||||
|
||||
# Solution 2: Customize server settings
|
||||
# Edit server-specific configuration files
|
||||
# Common locations: ~/.claude/mcp-config.json
|
||||
|
||||
# Solution 3: Environment variable configuration
|
||||
export MCP_CONTEXT7_TIMEOUT=60
|
||||
export MCP_SEQUENTIAL_MEMORY_LIMIT=2048
|
||||
|
||||
# Verification
|
||||
# Test with custom configuration
|
||||
# Should show improved performance for specific use cases
|
||||
```
|
||||
|
||||
**Issue: MCP Server Load Balancing**
|
||||
```bash
|
||||
# Symptoms: Uneven load distribution across MCP servers
|
||||
|
||||
# Solution 1: Configure server priorities
|
||||
# Edit MCP configuration to balance loads
|
||||
|
||||
# Solution 2: Use round-robin server selection
|
||||
# Implement rotation logic in server calls
|
||||
|
||||
# Solution 3: Monitor server performance
|
||||
# Track response times and adjust accordingly
|
||||
|
||||
# Verification
|
||||
# Observe balanced resource usage across servers
|
||||
```
|
||||
|
||||
## Debugging and Diagnostics
|
||||
|
||||
### MCP Server Health Monitoring
|
||||
|
||||
**Comprehensive MCP Health Check:**
|
||||
```bash
|
||||
# MCP Server System Diagnostics
|
||||
echo "=== MCP Server Health Check ==="
|
||||
|
||||
# Node.js environment
|
||||
echo "Node.js version: $(node --version)"
|
||||
echo "npm version: $(npm --version)"
|
||||
|
||||
# Server installations
|
||||
echo "=== Installed MCP Servers ==="
|
||||
npm list -g | grep -E "context7|sequential|magic|playwright|morphllm|serena"
|
||||
|
||||
# Process monitoring
|
||||
echo "=== Running MCP Processes ==="
|
||||
ps aux | grep -E "node.*mcp|mcp.*server" | head -5
|
||||
|
||||
# Resource usage
|
||||
echo "=== Resource Usage ==="
|
||||
echo "Memory: $(free -h | grep Mem | awk '{print $3 "/" $2}')"
|
||||
echo "CPU Load: $(uptime | awk -F'load average:' '{print $2}')"
|
||||
|
||||
# Network connectivity (if required)
|
||||
echo "=== Network Status ==="
|
||||
ping -c 1 8.8.8.8 > /dev/null && echo "✅ Network OK" || echo "❌ Network Issue"
|
||||
```
|
||||
|
||||
**MCP Server Functionality Test:**
|
||||
```bash
|
||||
# Test each MCP server individually
|
||||
echo "=== MCP Server Functionality Test ==="
|
||||
|
||||
# Context7 test
|
||||
if npm list -g @context7/mcp-server > /dev/null 2>&1; then
|
||||
echo "✅ Context7 installed"
|
||||
else
|
||||
echo "❌ Context7 missing"
|
||||
fi
|
||||
|
||||
# Sequential test
|
||||
if npm list -g @sequential/mcp-server > /dev/null 2>&1; then
|
||||
echo "✅ Sequential installed"
|
||||
else
|
||||
echo "❌ Sequential missing"
|
||||
fi
|
||||
|
||||
# Magic test
|
||||
if npm list -g @magic/ui-generator > /dev/null 2>&1; then
|
||||
echo "✅ Magic installed"
|
||||
else
|
||||
echo "❌ Magic missing"
|
||||
fi
|
||||
|
||||
# Playwright test
|
||||
if npx playwright --version > /dev/null 2>&1; then
|
||||
echo "✅ Playwright installed"
|
||||
else
|
||||
echo "❌ Playwright missing"
|
||||
fi
|
||||
```
|
||||
|
||||
### MCP Server Log Analysis
|
||||
|
||||
**Log Collection and Analysis:**
|
||||
```bash
|
||||
# Collect MCP server logs
|
||||
echo "=== MCP Server Logs ==="
|
||||
|
||||
# Check common log locations
|
||||
find ~/.claude/ -name "*.log" -type f 2>/dev/null
|
||||
find /tmp/ -name "*mcp*.log" -type f 2>/dev/null
|
||||
find /var/log/ -name "*mcp*.log" -type f 2>/dev/null
|
||||
|
||||
# Check npm logs
|
||||
npm config get logs-max
|
||||
ls ~/.npm/_logs/ 2>/dev/null | tail -5
|
||||
|
||||
# System logs for Node.js processes
|
||||
journalctl -u node* --since "1 hour ago" 2>/dev/null | tail -10
|
||||
```
|
||||
|
||||
## Emergency Recovery
|
||||
|
||||
### Complete MCP Reset
|
||||
|
||||
**Full MCP Server Reset Procedure:**
|
||||
```bash
|
||||
# Emergency MCP Reset
|
||||
echo "=== Emergency MCP Server Reset ==="
|
||||
|
||||
# Step 1: Stop all Claude Code sessions
|
||||
echo "Stop all Claude Code sessions and wait 30 seconds"
|
||||
|
||||
# Step 2: Backup current state
|
||||
cp -r ~/.claude ~/.claude.mcp.backup.$(date +%Y%m%d)
|
||||
|
||||
# Step 3: Remove all MCP servers
|
||||
npm list -g | grep -E "context7|sequential|magic|playwright|morphllm|serena" | awk '{print $2}' | xargs npm uninstall -g
|
||||
|
||||
# Step 4: Clear npm cache
|
||||
npm cache clean --force
|
||||
|
||||
# Step 5: Reinstall MCP servers
|
||||
python3 -m SuperClaude install --components mcp --force
|
||||
|
||||
# Step 6: Verification
|
||||
npm list -g | grep -E "context7|sequential|magic|playwright|morphllm|serena"
|
||||
|
||||
# Step 7: Test functionality
|
||||
echo "Test MCP servers in Claude Code after restart"
|
||||
```
|
||||
|
||||
## Related Resources
|
||||
|
||||
### MCP-Specific Documentation
|
||||
- **Core SuperClaude Guide**: [../user-guide/mcp-servers.md](../user-guide/mcp-servers.md) - MCP server overview and usage
|
||||
- **Common Issues**: [common-issues.md](./common-issues.md) - General troubleshooting procedures
|
||||
- **Diagnostic Reference**: [diagnostic-reference.md](./diagnostic-reference.md) - Advanced diagnostic procedures
|
||||
|
||||
### External Resources
|
||||
- **Node.js Official**: [https://nodejs.org/](https://nodejs.org/) - Node.js installation and documentation
|
||||
- **npm Documentation**: [https://docs.npmjs.com/](https://docs.npmjs.com/) - Package manager documentation
|
||||
- **Playwright Guide**: [https://playwright.dev/](https://playwright.dev/) - Browser automation documentation
|
||||
|
||||
### Support Channels
|
||||
- **GitHub Issues**: [MCP-specific problems](https://github.com/SuperClaude-Org/SuperClaude_Framework/issues)
|
||||
- **GitHub Discussions**: [MCP server community support](https://github.com/SuperClaude-Org/SuperClaude_Framework/discussions)
|
||||
|
||||
---
|
||||
|
||||
**MCP Server Priority**: When troubleshooting, address servers in order of dependency: Node.js → npm → individual servers → Claude Code integration. Most MCP issues resolve with proper Node.js setup and server reinstallation.
|
||||
|
||||
**Verification Pattern**: After MCP solutions, always verify with:
|
||||
- ✅ `node --version` - Should be 16.0.0+
|
||||
- ✅ `npm list -g | grep mcp` - Should show installed servers
|
||||
- ✅ Test server functionality in Claude Code - Should respond without errors
|
||||
124
docs/reference/troubleshooting.md
Normal file
124
docs/reference/troubleshooting.md
Normal file
@@ -0,0 +1,124 @@
|
||||
# SuperClaude Troubleshooting Guide 🔧
|
||||
|
||||
Quick fixes to advanced diagnostics for SuperClaude Framework issues.
|
||||
|
||||
## Quick Fixes (90% of problems)
|
||||
|
||||
**Installation Verification:**
|
||||
```bash
|
||||
python3 -m SuperClaude --version # Should show 4.1.5
|
||||
SuperClaude install --list-components
|
||||
```
|
||||
|
||||
**Command Issues:**
|
||||
```bash
|
||||
# Test in Claude Code:
|
||||
/sc:brainstorm "test project" # Should ask discovery questions
|
||||
|
||||
# If no response: Restart Claude Code session
|
||||
```
|
||||
|
||||
**Resolution Checklist:**
|
||||
- [ ] Version commands work and show 4.1.5
|
||||
- [ ] `/sc:` commands respond in Claude Code
|
||||
- [ ] MCP servers listed: `SuperClaude install --list-components | grep mcp`
|
||||
|
||||
## Common Issues
|
||||
|
||||
### Installation Problems
|
||||
|
||||
**Package Installation Fails:**
|
||||
```bash
|
||||
# For pipx users
|
||||
pipx uninstall SuperClaude
|
||||
pipx install SuperClaude
|
||||
|
||||
# For pip users
|
||||
pip uninstall SuperClaude
|
||||
pip install --upgrade pip
|
||||
pip install SuperClaude
|
||||
```
|
||||
|
||||
**Permission Denied / PEP 668 Error:**
|
||||
```bash
|
||||
# Option 1: Use pipx (recommended)
|
||||
pipx install SuperClaude
|
||||
|
||||
# Option 2: Use pip with --user flag
|
||||
pip install --user SuperClaude
|
||||
|
||||
# Option 3: Fix permissions
|
||||
sudo chown -R $USER ~/.claude
|
||||
|
||||
# Option 4: Force installation (use with caution)
|
||||
pip install --break-system-packages SuperClaude
|
||||
```
|
||||
|
||||
**Component Missing:**
|
||||
```bash
|
||||
python3 -m SuperClaude install --components core commands agents modes --force
|
||||
```
|
||||
|
||||
### Command Issues
|
||||
|
||||
**Commands Not Recognized:**
|
||||
1. Restart Claude Code completely
|
||||
2. Verify: `python3 -m SuperClaude --version`
|
||||
3. Test: `/sc:brainstorm "test"`
|
||||
|
||||
**Agents Not Activating:**
|
||||
- Use specific keywords: `/sc:implement "secure JWT authentication"`
|
||||
- Manual activation: `@agent-security "review auth code"`
|
||||
|
||||
**Slow Performance:**
|
||||
```bash
|
||||
/sc:analyze . --no-mcp # Test without MCP servers
|
||||
/sc:analyze src/ --scope file # Limit scope
|
||||
```
|
||||
|
||||
### MCP Server Issues
|
||||
|
||||
**Server Connection Fails:**
|
||||
```bash
|
||||
ls ~/.claude/.claude.json # Check config exists
|
||||
node --version # Verify Node.js 16+
|
||||
SuperClaude install --components mcp --force
|
||||
```
|
||||
|
||||
**API Key Required (Magic/Morphllm):**
|
||||
```bash
|
||||
export TWENTYFIRST_API_KEY="your_key"
|
||||
export MORPH_API_KEY="your_key"
|
||||
# Or use: /sc:command --no-mcp
|
||||
```
|
||||
|
||||
## Advanced Diagnostics
|
||||
|
||||
**System Analysis:**
|
||||
```bash
|
||||
SuperClaude install --diagnose
|
||||
cat ~/.claude/logs/superclaude.log | tail -50
|
||||
```
|
||||
|
||||
**Component Analysis:**
|
||||
```bash
|
||||
ls -la ~/.claude/ # Check installed files
|
||||
grep -r "@" ~/.claude/CLAUDE.md # Verify imports
|
||||
```
|
||||
|
||||
**Reset Installation:**
|
||||
```bash
|
||||
SuperClaude backup --create # Backup first
|
||||
SuperClaude uninstall
|
||||
SuperClaude install --fresh
|
||||
```
|
||||
|
||||
## Get Help
|
||||
|
||||
**Documentation:**
|
||||
- [Installation Guide](../getting-started/installation.md) - Setup issues
|
||||
- [Commands Guide](../user-guide/commands.md) - Usage issues
|
||||
|
||||
**Community:**
|
||||
- [GitHub Issues](https://github.com/SuperClaude-Org/SuperClaude_Framework/issues)
|
||||
- Include: OS, Python version, error message, steps to reproduce
|
||||
Reference in New Issue
Block a user