admin123
/
translation
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
translation/source/documents/SuperClaude/CLAUDE.md

7.6 KiB
Raw Blame History

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Quick Reference

Common Commands

Installation & Setup:

# Install in development mode
uv sync

# Run the installer (various options)
SuperClaude install                    # Quick setup (recommended)
SuperClaude install --interactive      # Interactive component selection
SuperClaude install --minimal          # Minimal installation
SuperClaude install --profile developer # Full developer setup
SuperClaude install --dry-run          # Preview changes without applying

# Alternative installation methods
python3 -m SuperClaude install
SuperClaude update --verbose
SuperClaude backup --create
SuperClaude uninstall --yes

Package Management:

# From PyPI (recommended)
uv add SuperClaude

# From source
git clone https://github.com/SuperClaude-Org/SuperClaude_Framework.git
cd SuperClaude_Framework
uv sync

Testing (Limited):

# Note: No formal test suite exists yet
# Referenced in docs but not implemented:
python Tests/comprehensive_test.py
python Tests/task_management_test.py
python Tests/performance_test_suite.py

Architecture Overview

SuperClaude Framework v3.0 is a Python-based enhancement system for Claude Code that extends AI-assisted development through specialized commands, personas, and MCP server integration.

Core Structure

SuperClaude_Framework/
├── SuperClaude/              # Framework files (installed to ~/.claude/)
│   ├── Core/                 # 9 documentation files defining behavior
│   │   ├── CLAUDE.md         # Main entry point
│   │   ├── COMMANDS.md       # Command execution framework
│   │   ├── FLAGS.md          # Flag reference
│   │   ├── PERSONAS.md       # 11 specialized personas
│   │   ├── MCP.md            # MCP server integration
│   │   ├── ORCHESTRATOR.md   # Intelligent routing system
│   │   PRINCIPLES.md         # Core principles
│   │   RULES.md              # Operational rules
│   │   MODES.md              # Operational modes
│   ├── Commands/             # 16 markdown-based slash commands
│   │   ├── analyze.md
│   │   ├── build.md
│   │   ├── implement.md      # NEW in v3 (replaces v2 /build for features)
│   │   └── ...
│   └── Hooks/                # Removed in v3, returning in v4
│
├── setup/                    # Installation system
│   ├── base/                 # Core installer infrastructure
│   ├── components/           # Component installers
│   ├── core/                 # Registry and validation
│   ├── managers/             # Config, file, settings managers
│   ├── operations/           # Install, update, uninstall, backup
│   └── utils/                # UI, logging, security utilities
│
├── config/                   # Configuration
│   ├── features.json         # Feature definitions
│   └── requirements.json     # System requirements
│
├── profiles/                 # Installation profiles
│   ├── quick.json            # Quick setup
│   ├── minimal.json          # Minimal installation
│   └── developer.json        # Full developer setup
│
├── Docs/                     # User documentation (5 guides)
└── SuperClaude/__main__.py   # Unified CLI entry point

Key Components

1. Installation System (setup/ module)

  • Modular installer with component-based installation
  • Entry point: SuperClaude/__main__.py (254 lines)
  • Operations: install, update, uninstall, backup
  • Profiles: quick, minimal, developer

2. Framework Files (SuperClaude/ directory)

  • 9 core documentation files guide Claude's behavior
  • 16 slash command definitions in markdown
  • Installed to ~/.claude/ for Claude Code integration

3. MCP Integration

  • Context7: Documentation lookup
  • Sequential: Complex analysis
  • Magic: UI component generation
  • Playwright: Browser automation

4. Personas System

  • 11 specialized AI personas: architect, frontend, backend, analyzer, security, scribe, and 5 others
  • Smart routing attempts to pick the right expert

Development Workflow

Development Setup

# Clone and setup
git clone https://github.com/SuperClaude-Org/SuperClaude_Framework.git
cd SuperClaude_Framework
uv sync

# Install in development mode
SuperClaude install --profile developer

Key Development Areas

Framework Files - Modify SuperClaude/Core/ and SuperClaude/Commands/ for:

  • Documentation and behavior changes
  • Command definitions and updates
  • Persona configurations

Installation System - Work in setup/ module for:

  • Installer improvements
  • Component management
  • Profile adjustments

Configuration - Update files in:

  • config/requirements.json - System requirements
  • config/features.json - Feature definitions
  • profiles/*.json - Installation profiles

Code Organization Patterns

  • Modular Architecture: Separate concerns across modules
  • Documentation-Driven: Markdown files define behavior
  • Component-Based: Installation broken into discrete components
  • Profile-Driven: Multiple installation profiles for different use cases
  • Error Handling: Comprehensive error handling with fallbacks

Important Notes

v2 to v3 Migration

Breaking Change: The /build command changed!

  • v2: /build myFeature = feature implementation
  • v3: /sc:build = compilation/packaging only
  • v3: /sc:implement = feature implementation (NEW!)

Migration: Replace v2 /build myFeature with v3 /sc:implement myFeature

Known Issues

  • This is an initial v3.0 release - expect bugs
  • Hooks system removed (returning in v4)
  • No formal test suite exists (referenced in docs but not implemented)
  • No linting/formatting configuration
  • MCP integration partially working

Build System

  • Build Backend: Hatchling (via pyproject.toml)
  • Package Manager: uv (modern Python package manager)
  • Dependencies: Minimal (only setuptools>=45.0.0)
  • Language: Python 3.8+ (standard library focused)

Important Documentation

  • README.md (342 lines) - Main project documentation, installation guide
  • CONTRIBUTING.md - Contribution guidelines, code standards
  • Docs/superclaude-user-guide.md - Complete user overview
  • Docs/commands-guide.md - All 16 slash commands explained
  • Docs/flags-guide.md - Command flags and options
  • Docs/installation-guide.md - Detailed installation instructions

Daily Development Commands

# Quick installation test
SuperClaude install --dry-run

# Update installation
SuperClaude update --verbose

# Create backup before changes
SuperClaude backup --create

# View all installation options
SuperClaude install --help

# Run installer with specific profile
SuperClaude install --profile developer

Configuration

After installation, users can customize via:

  • ~/.claude/settings.json - Main configuration
  • ~/.claude/*.md - Framework behavior files

Future Roadmap (v4)

  • Hooks system redesign and return
  • Enhanced MCP suite
  • Performance improvements
  • Additional personas
  • Cross-CLI support

Troubleshooting

Installation Issues:

  • Check Python 3.8+ is installed
  • Ensure ~/.claude/ directory permissions
  • Run with --verbose flag for detailed output
  • Backup and clean install if upgrading from v2

Development Issues:

  • Framework files are in SuperClaude/ (installed to ~/.claude/)
  • Installation system is in setup/ module
  • Entry point is SuperClaude/__main__.py