SuperClaude/CLAUDE.md

CLAUDE.md

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

🐍 Python Environment Rules

CRITICAL: This project uses UV for all Python operations.

Required Commands

# ❌ WRONG - Never use these
python -m pytest
pip install package
python script.py

# ✅ CORRECT - Always use UV
uv run pytest
uv pip install package
uv run python script.py

Why UV?

• Fast: 10-100x faster than pip
• Reliable: Lock file ensures reproducibility
• Clean: No system Python pollution
• Standard: Project convention for consistency

Common Operations

# Run tests
uv run pytest tests/ -v

# Install dependencies
uv pip install -r requirements.txt

# Run specific script
uv run python scripts/analyze_workflow_metrics.py

# Create virtual environment (if needed)
uv venv

Integration with Docker

When using Docker for development:

# Inside Docker container
docker compose exec workspace uv run pytest

📂 Project Structure

SuperClaude_Framework/
├── superclaude/           # Framework source
│   ├── commands/          # Slash commands
│   ├── agents/            # Agent personas
│   ├── modes/             # Behavior modes
│   ├── framework/         # Core principles/rules/flags
│   ├── business/          # Business analysis patterns
│   └── research/          # Research configurations
├── setup/                 # Installation system
│   ├── components/        # Installable components
│   │   ├── knowledge_base.py       # Framework knowledge
│   │   ├── behavior_modes.py       # Mode definitions
│   │   ├── agent_personas.py       # Agent definitions
│   │   ├── slash_commands.py       # Command registration
│   │   └── mcp_integration.py      # External tool integration
│   └── core/              # Installation logic
└── tests/                 # Test suite

🔧 Development Workflow

Makefile Commands (Recommended)

# Development setup
make dev              # Install in editable mode with [dev] dependencies (RECOMMENDED)
make verify           # Verify installation health (package, version, plugin, doctor)

# Testing
make test             # Run full test suite with pytest
make test-plugin      # Verify pytest plugin auto-discovery

# Code quality
make lint             # Run ruff linter
make format           # Format code with ruff

# Maintenance
make doctor           # Run health check diagnostics
make clean            # Remove build artifacts and caches
make translate        # Translate README to zh/ja (requires neural-cli)

Running Tests Directly

# All tests
uv run pytest

# Specific test file
uv run pytest tests/pm_agent/test_confidence_check.py -v

# By directory
uv run pytest tests/pm_agent/ -v

# By marker
uv run pytest -m confidence_check
uv run pytest -m "unit and not integration"

# With coverage
uv run pytest --cov=superclaude --cov-report=html

Code Quality

# Linting
uv run ruff check .

# Formatting
uv run ruff format .

# Type checking (if configured)
uv run mypy superclaude/

📦 Core Architecture

Pytest Plugin System (Auto-loaded)

SuperClaude includes an auto-loaded pytest plugin registered via entry points in pyproject.toml:66-67:

[project.entry-points.pytest11]
superclaude = "superclaude.pytest_plugin"

Provides:

• Custom fixtures: confidence_checker, self_check_protocol, reflexion_pattern, token_budget, pm_context
• Auto-markers: Tests in /unit/ → @pytest.mark.unit, /integration/ → @pytest.mark.integration
• Custom markers: @pytest.mark.confidence_check, @pytest.mark.self_check, @pytest.mark.reflexion
• PM Agent integration for test lifecycle hooks

PM Agent - Three Core Patterns

Located in src/superclaude/pm_agent/:

1. ConfidenceChecker (Pre-execution)

• Prevents wrong-direction execution by assessing confidence BEFORE starting
• Token budget: 100-200 tokens
• ROI: 25-250x token savings when stopping wrong implementations
• Confidence levels:
  • High (≥90%): Proceed immediately
  • Medium (70-89%): Present alternatives
  • Low (<70%): STOP → Ask specific questions

2. SelfCheckProtocol (Post-implementation)

• Evidence-based validation after implementation
• No speculation allowed - verify with actual tests/docs
• Ensures implementation matches requirements

3. ReflexionPattern (Error learning)

• Records failures for future prevention
• Pattern matching for similar errors
• Cross-session learning and improvement

Module Structure

src/superclaude/
├── __init__.py              # Exports: ConfidenceChecker, SelfCheckProtocol, ReflexionPattern
├── pytest_plugin.py         # Auto-loaded pytest integration (fixtures, hooks, markers)
├── pm_agent/                # PM Agent core (confidence, self-check, reflexion)
├── cli/                     # CLI commands (main, doctor, install_skill)
└── execution/               # Execution patterns (parallel, reflection, self_correction)

Parallel Execution Engine

Located in src/superclaude/execution/parallel.py:

• Automatic parallelization: Analyzes task dependencies and executes independent operations concurrently
• Wave → Checkpoint → Wave pattern: 3.5x faster than sequential execution
• Dependency graph: Topological sort for optimal grouping
• ThreadPoolExecutor: Concurrent execution with result aggregation

Example pattern:

# Wave 1: Read files in parallel
tasks = [read_file1, read_file2, read_file3]

# Checkpoint: Analyze results

# Wave 2: Edit files in parallel based on analysis
tasks = [edit_file1, edit_file2, edit_file3]

Component Responsibility

• knowledge_base: Framework knowledge initialization
• behavior_modes: Execution mode definitions
• agent_personas: AI agent personality definitions
• slash_commands: CLI command registration
• mcp_integration: External tool integration

🧪 Testing with PM Agent Markers

Custom Pytest Markers

# Pre-execution confidence check (skips if confidence < 70%)
@pytest.mark.confidence_check
def test_feature(confidence_checker):
    context = {"test_name": "test_feature", "has_official_docs": True}
    assert confidence_checker.assess(context) >= 0.7

# Post-implementation validation with evidence requirement
@pytest.mark.self_check
def test_implementation(self_check_protocol):
    implementation = {"code": "...", "tests": [...]}
    passed, issues = self_check_protocol.validate(implementation)
    assert passed, f"Validation failed: {issues}"

# Error learning and prevention
@pytest.mark.reflexion
def test_error_prone_feature(reflexion_pattern):
    # If this test fails, reflexion records the error for future prevention
    pass

# Token budget allocation (simple: 200, medium: 1000, complex: 2500)
@pytest.mark.complexity("medium")
def test_with_budget(token_budget):
    assert token_budget.limit == 1000

Available Fixtures

From src/superclaude/pytest_plugin.py:

• confidence_checker - Pre-execution confidence assessment
• self_check_protocol - Post-implementation validation
• reflexion_pattern - Error learning pattern
• token_budget - Token allocation management
• pm_context - PM Agent context (memory directory structure)

🌿 Git Workflow

Branch Strategy

master          # Production-ready releases
├── integration # Integration testing branch (current)
    ├── feature/*       # Feature development
    ├── fix/*           # Bug fixes
    └── docs/*          # Documentation updates

Workflow:

1. Create feature branch from integration: git checkout -b feature/your-feature
2. Develop with tests: uv run pytest
3. Commit with conventional commits: git commit -m "feat: description"
4. Merge to integration for integration testing
5. After validation: integration → master

Current branch: integration (see gitStatus above)

🚀 Contributing

When making changes:

1. Create feature branch from integration
2. Make changes with tests (maintain coverage)
3. Commit with conventional commits (feat:, fix:, docs:, refactor:, test:)
4. Merge to integration for integration testing
5. Small, reviewable PRs preferred

📝 Essential Documentation

Read these files IN ORDER at session start:

1. PLANNING.md - Architecture, design principles, absolute rules
2. TASK.md - Current tasks and priorities
3. KNOWLEDGE.md - Accumulated insights and troubleshooting

These documents are the source of truth for development standards.

Additional Resources:

• User guides: docs/user-guide/
• Development docs: docs/Development/
• Research reports: docs/research/

💡 Core Development Principles

From KNOWLEDGE.md and PLANNING.md:

1. Evidence-Based Development

• Never guess - verify with official docs (Context7 MCP, WebFetch, WebSearch)
• Example: Don't assume port configuration - check official documentation first
• Prevents wrong-direction implementations

2. Token Efficiency

• Every operation has a token budget:
  • Simple (typo fix): 200 tokens
  • Medium (bug fix): 1,000 tokens
  • Complex (feature): 2,500 tokens
• Confidence check ROI: Spend 100-200 to save 5,000-50,000

3. Parallel-First Execution

• Wave → Checkpoint → Wave pattern (3.5x faster)
• Good: [Read file1, Read file2, Read file3] → Analyze → [Edit file1, Edit file2, Edit file3]
• Bad: Sequential reads then sequential edits

4. Confidence-First Implementation

• Check confidence BEFORE implementation, not after
• ≥90%: Proceed immediately
• 70-89%: Present alternatives
• <70%: STOP → Ask specific questions

🔧 MCP Server Integration

This framework integrates with multiple MCP servers:

Priority Servers:

• Context7: Official documentation (prevent hallucination)
• Sequential: Complex analysis and multi-step reasoning
• Tavily: Web search for Deep Research

Optional Servers:

• Serena: Session persistence and memory
• Playwright: Browser automation testing
• Magic: UI component generation

Always prefer MCP tools over speculation when documentation or research is needed.

🔗 Related

• Global rules: ~/.claude/CLAUDE.md (workspace-level)
• MCP servers: Unified gateway via airis-mcp-gateway
• Framework docs: Auto-installed to ~/.claude/superclaude/