cleverclaude-core/CLAUDE.md

CLAUDE.md

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

Repository Overview

This is a modern Python 3.13 micro-service starter project that demonstrates cutting-edge Python development practices. It serves as a template for new Python projects, replacing legacy setuptools-based workflows with modern tooling focused on performance, type safety, and developer experience.

Development Commands

Environment Setup

# Use uv (Rust-powered package manager, 10-100x faster than pip)
uv venv
source .venv/bin/activate
uv pip install -e .[dev]

# Or use development container (recommended)
docker build -f .devcontainer/Dockerfile -t boilerplate-dev .
docker run -it -v $(pwd):/workspaces/boilerplate boilerplate-dev bash

Essential Commands

# Quality checks (primary workflow)
nox -s lint        # Ruff linting and formatting check
nox -s format      # Auto-format code with ruff
nox -s typecheck   # Pyright type checking in strict mode

# Testing
nox -s behave      # BDD tests across Python 3.11, 3.12, 3.13
behave -q          # Quick BDD test run
behave -t @wip     # Run work-in-progress tests only
behave -t ~@wip    # Skip work-in-progress tests

# Documentation
nox -s docs        # Build MkDocs documentation
nox -s serve_docs  # Serve docs at http://localhost:8000

# Build and deploy
nox -s build       # Build wheel package
python -m build --wheel

# Run everything
nox                # All quality checks and tests

# Claude Code + MCP integration
claude             # Start Claude Code with MCP servers
mcp-status         # Check MCP server status  
mcp-logs           # View MCP server logs

Single Test/Scenario Execution

# Run specific BDD scenario by line number
behave features/cli.feature:9

# Run scenarios by tag
behave -t @hypothesis    # Property-based fuzzing tests
behave -t @smoke        # Smoke tests

# Run with verbose output for debugging
behave -v --no-capture

Architecture Overview

Modern Python Stack

This project uses bleeding-edge Python tooling that replaces 5+ legacy tools:

• uv: Package management (replaces pip, 10-100x faster)
• ruff: Linting + formatting + import sorting (replaces black, isort, flake8, pylint, bandit)
• pyright: Type checking in strict mode (replaces mypy, 5x faster)
• behave + hypothesis: BDD testing with property-based fuzzing (replaces pytest)
• nox: Test automation (replaces tox, Python-based configuration)
• hatchling: PEP 621 build backend (replaces setuptools)

Configuration Architecture

Single file (pyproject.toml) replaces 4+ legacy configuration files:

• Project metadata, dependencies, build config
• Tool configurations for ruff, type checking
• Entry points and package discovery
• Development dependencies and optional extras

Testing Philosophy

Behavior-Driven Development (BDD): Tests are written as natural language scenarios in Gherkin format that serve as both executable tests and living documentation. This replaces traditional unit tests with stakeholder-readable specifications.

Property-Based Testing: Hypothesis integration automatically generates thousands of test cases to discover edge cases that manual testing would miss.

Source Structure

src/boilerplate/           # Importable package code
├── __init__.py           # Package version and exports
├── __main__.py           # Entry point for `python -m boilerplate`
└── cli.py                # Click-based CLI with type hints

features/                  # BDD test specifications (not traditional tests/)
├── environment.py        # Behave test environment setup
├── steps/cli_steps.py    # Step definitions with Hypothesis integration
└── cli.feature          # Gherkin scenarios serving as living docs

Container & Deployment Architecture

• Multi-stage Docker builds: Optimized 20MB runtime images
• Development containers: Zero-config development environment with Claude Code + MCP servers
• Kubernetes ready: Production Helm charts with HPA, security contexts
• CI/CD: 60-second cold clone to green pipeline using Forgejo Actions
• Claude Code MCP Integration: Pre-configured with 9 MCP servers for end-to-end development

Key Implementation Patterns

Type Safety

• Strict type checking enabled via pyrightconfig.json
• All functions have type hints including return types
• Use from typing import for complex types
• CLI functions use Click's type system alongside Python types

BDD Test Structure

Feature: Business-readable feature description
  Background: Common setup steps
  
  Scenario: Specific behavior description
    Given initial conditions
    When actions are performed  
    Then expected outcomes occur
  
  @hypothesis
  Scenario: Property-based testing
    When I test with randomly generated inputs
    Then invariant properties should hold

Modern CLI Development

• Use Click for CLI with proper type annotations
• Implement __main__.py for python -m package execution
• Version info from package metadata, not hardcoded
• Rich help messages and proper option handling

Configuration Management

All project configuration lives in pyproject.toml:

• Project metadata following PEP 621
• Tool configurations in [tool.toolname] sections
• Dependencies with version constraints
• Build system specification

Development Workflow

Code Quality Standards

1. Format first: nox -s format auto-fixes style issues
2. Type check: nox -s typecheck catches type errors early
3. Test behavior: nox -s behave validates functionality
4. Document changes: Update BDD scenarios for new features

Adding New Features

1. Write BDD scenario first (test-driven development)
2. Implement minimal code to make scenario pass
3. Add type hints and proper error handling
4. Run full test suite across Python versions
5. Update documentation if needed

Container Development

The development container provides comprehensive AI-powered environment with:

• Pre-installed tools and dependencies (Python 3.13, Node.js 20, Go 1.22+)
• Shell aliases (dev-test, dev-lint, claude, mcp-status)
• Port forwarding for development servers and monitoring stack (8000, 8080, 3000, 9090, 3001)
• Volume mounts for persistent data and MCP logging
• Claude Code + 9 MCP servers for end-to-end AI-driven development
• Docker-in-Docker for containerized MCP servers
• Kubernetes tools (kubectl, helm) for deployment automation

Use terminal-first approach with IDE integration options for Emacs, Vim, VS Code, and PyCharm, enhanced by Claude Code's AI capabilities.

Performance Considerations

This project prioritizes performance through:

• Rust-powered tools: uv and ruff provide 10-100x speedups
• Parallel execution: nox runs tests across Python versions simultaneously
• Optimized containers: Multi-stage builds minimize image size
• Fast CI: Pipeline completes in ≤60 seconds

When making changes, maintain performance characteristics by preferring modern tools over legacy alternatives.

Claude Code + MCP Integration

The development container includes Claude Code with a comprehensive suite of MCP (Model Context Protocol) servers that enable AI-driven end-to-end development workflows spanning code quality, testing, containerization, deployment, monitoring, and infrastructure management.

Pre-configured MCP Servers

Code Quality & Testing

• ruff: Python linting, formatting, and import optimization
• uv: Lightning-fast Python package management
• tests: Universal test runner supporting pytest, behave, nox, and custom commands

Development Environment

• devcontainers: Development container lifecycle management
• forgejo: Git repository operations, branch management, PR creation

Infrastructure & Operations

• kubernetes: Cluster operations, pod management, Helm deployments
• prometheus: Metrics queries, alerting rules, performance monitoring
• grafana: Dashboard management, visualization, incident response
• tofu: Infrastructure as Code with OpenTofu/Terraform

Quick Start with MCP

# Start Claude Code with all MCP servers
claude

# Check MCP server status
mcp-status

# View server logs
mcp-logs

MCP Environment Configuration

Copy and customize the environment template:

cp ~/.local/share/mcp-env-template ~/.bashrc
# Edit tokens and endpoints for your infrastructure

Required environment variables:

# Repository management
export FORGEJO_PAT="your-forgejo-personal-access-token"

# Monitoring stack
export PROMETHEUS_URL="http://localhost:9090"
export GRAFANA_API_TOKEN="your-grafana-api-token"

# Container orchestration
export KUBECONFIG="~/.kube/config"

End-to-End Workflow Examples

CI/CD Pipeline: Lint → Test → Deploy

%%tool ruff
ruff_check path="src/" format="text"

%%tool tests  
run_tests framework="behave" command="nox -s behave"

%%tool forgejo
create_pull_request repo="boilerplate" title="feat: new feature" branch="feature-branch"

Production Debugging: Metrics → Logs → Fix

%%tool prometheus
execute_query query="rate(http_requests_total[5m])"

%%tool kubernetes
pods_logs name="api-7d9f6ccbdc-4tnqz" namespace="prod" container="api"

%%tool devcontainers
devcontainer_exec workspaceFolder="." command=["bash", "-c", "nox -s format && git commit -am 'fix: performance issue'"]

Infrastructure Provisioning

%%tool tofu
search-opentofu-registry query="aws_vpc"

%%tool tests
run_tests framework="custom" command="tofu plan -var-file=prod.tfvars"

%%tool kubernetes
helm_install chart="./charts/web" name="web" namespace="prod"

MCP Server Architecture

Containerized Servers

• prometheus-mcp: Runs in isolated Docker container
• grafana-mcp: Containerized with API token injection
• kubernetes-mcp: Direct kubectl/helm integration

Native Servers

• ruff-mcp: Python-based, direct filesystem access
• uv-mcp: uvx-managed, integrated with local Python environment
• test-runner-mcp: Node.js-based, supports arbitrary shell commands

Remote Servers

• tofu-mcp: Hosted service at https://mcp.opentofu.org/sse
• forgejo-mcp: Local binary built from Go source

Security & Isolation

MCP servers follow security best practices:

• Token isolation: Environment variables with restricted scopes
• Network containment: Docker containers with minimal network access
• Audit logging: All MCP interactions logged to ~/.local/share/mcp-logs/
• Read-only modes: Most servers support --read-only flags for safe exploration

Advanced MCP Usage

Custom MCP Server Development

The development container includes all dependencies for building custom MCP servers:

• Node.js 20+ for TypeScript/JavaScript servers
• Python 3.13 + uv for Python servers
• Go 1.22+ for compiled servers
• Docker for containerized servers

Multi-Server Orchestration

Claude Code can coordinate multiple MCP servers in a single conversation:

# Quality gate: format, lint, test, deploy
%%tool ruff ruff_format path="."
%%tool tests run_tests framework="nox" command="nox -s lint typecheck behave"
%%tool forgejo create_pull_request title="feat: quality improvements"
%%tool kubernetes helm_upgrade release="app" chart="./charts"

Development Container Integration

MCP servers are tightly integrated with the development container:

• Automatic server health checks on container startup
• Pre-configured logging and monitoring
• Shared volume mounts for persistent data
• Port forwarding for web-based servers (Prometheus, Grafana, Forgejo)

This MCP integration transforms the development container into a comprehensive AI-powered development environment that can handle the entire software lifecycle from code quality to production deployment.

Advanced Claude Code Subagent Network

Beyond the MCP servers, this project includes a sophisticated network of specialized Claude Code subagents that collaborate to solve complex development challenges. These subagents form an intelligent network that can handle everything from code quality to production deployment through coordinated AI-powered workflows.

Subagent Architecture Overview

The subagent system consists of 16 specialized subagents organized into 6 categories:

Core Development (3 subagents)

• python-quality-analyst: Advanced Python code quality analysis with ruff, pyright, and modern tooling
• dependency-manager: UV-based dependency management, security scanning, and package optimization
• performance-optimizer: Python performance analysis, profiling, and optimization recommendations

Testing & Quality (4 subagents)

• test-architect: BDD test design, Behave scenario creation, and testing strategy
• hypothesis-fuzzer: Property-based testing with Hypothesis, edge case discovery, and fuzz testing
• test-executor: Nox-based test execution, multi-version testing, and CI/CD integration
• quality-gatekeeper: Quality gate enforcement, pre-commit integration, and release readiness

Deployment & Infrastructure (3 subagents)

• container-architect: Docker/DevContainer optimization, multi-stage builds, and security hardening
• kubernetes-specialist: Kubernetes deployment, Helm charts, HPA, and production readiness
• ci-cd-orchestrator: Forgejo Actions, pipeline optimization, and deployment automation

Documentation & API (2 subagents)

• documentation-architect: MkDocs Material, API documentation, and technical writing
• api-specialist: FastAPI/Click integration, OpenAPI specs, and API design patterns

Monitoring & Security (3 subagents)

• monitoring-specialist: Prometheus metrics, Grafana dashboards, and observability patterns
• security-auditor: Security scanning, vulnerability assessment, and compliance monitoring
• incident-responder: Log analysis, debugging assistance, and production issue resolution

Orchestration & Workflows (4 subagents)

• project-coordinator: High-level project coordination, task delegation, and workflow orchestration
• feature-delivery-manager: End-to-end feature delivery, from conception to production deployment
• code-review-assistant: Comprehensive code review, best practices enforcement, and mentoring
• refactoring-specialist: Code refactoring, architecture improvements, and technical debt management

Intelligent Collaboration Patterns

The subagents use predefined collaboration patterns for common workflows:

Quality Pipeline

python-quality-analyst → test-architect → quality-gatekeeper

Comprehensive code quality validation with testing integration.

Deployment Pipeline

container-architect → kubernetes-specialist → ci-cd-orchestrator → monitoring-specialist

End-to-end deployment from container creation to production monitoring.

Feature Development

project-coordinator → test-architect → python-quality-analyst → api-specialist → documentation-architect

Complete feature development with testing, quality, and documentation.

Incident Response

incident-responder → monitoring-specialist → kubernetes-specialist → security-auditor

Coordinated incident response across observability and security domains.

Performance Optimization

performance-optimizer → monitoring-specialist → test-architect → kubernetes-specialist

Performance analysis with monitoring integration and validation testing.

Subagent Management System

The project includes a comprehensive subagent management system:

# View system status
python .claude-code/subagents/subagent-manager.py --status

# List available workflows
python .claude-code/subagents/subagent-manager.py --workflows

# Get subagent recommendations for a task
python .claude-code/subagents/subagent-manager.py --recommend "optimize API performance"

# Execute a workflow
python .claude-code/subagents/subagent-manager.py --execute quality_pipeline

Advanced Workflow Examples

Comprehensive Feature Development

When implementing a new feature, the project-coordinator subagent orchestrates:

1. Requirements Analysis: test-architect analyzes testing requirements
2. Security Assessment: security-auditor evaluates security implications
3. Performance Planning: performance-optimizer analyzes performance requirements
4. Implementation Coordination: Multiple subagents work in parallel on code, tests, and docs
5. Quality Validation: Comprehensive quality gates across all domains
6. Deployment Planning: Container and Kubernetes deployment preparation

Advanced Code Review Process

The code-review-assistant coordinates with multiple subagents:

1. Static Analysis: python-quality-analyst performs comprehensive code analysis
2. Security Review: security-auditor scans for vulnerabilities
3. Test Coverage: test-architect validates test coverage and scenarios
4. Performance Impact: performance-optimizer assesses performance implications
5. Documentation: documentation-architect ensures proper documentation

Production Issue Resolution

The incident-responder leads coordinated troubleshooting:

1. Log Analysis: Automated log parsing and pattern recognition
2. Performance Correlation: monitoring-specialist correlates metrics
3. Infrastructure Assessment: kubernetes-specialist checks cluster health
4. Security Validation: security-auditor rules out security incidents
5. Resolution Planning: Coordinated resolution across all affected systems

Subagent Configuration

Each subagent has comprehensive configuration defining:

• Capabilities: Specific technical capabilities and expertise areas
• Collaboration Protocols: How they coordinate with other subagents
• Tools Used: Integration with specific tools and technologies
• System Prompts: Detailed expertise and operational guidance (1000+ lines each)
• Output Formats: Structured deliverables and reporting formats

Key Advantages

1. Specialized Expertise: Each subagent is a deep specialist in their domain
2. Intelligent Coordination: Subagents collaborate based on predefined patterns and dynamic analysis
3. Comprehensive Coverage: End-to-end coverage from development to production
4. Quality Integration: Quality considerations integrated across all workflows
5. Scalable Architecture: New subagents can be added without disrupting existing ones
6. Context Awareness: Subagents understand project-specific context and constraints

This advanced subagent network transforms Claude Code into a comprehensive AI development team that can handle complex, multi-faceted development challenges through intelligent collaboration and specialized expertise.