cleverclaude/cleverclaude-core
0
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Modernized build tooling

Browse Source
This commit is contained in:
Jeffrey Phillips Freeman
2025-08-01 05:00:24 +00:00
committed by Your Name
parent 8a93f794d6
commit f7a5d26c41
71 changed files with 6685 additions and 813 deletions
Download Patch File Download Diff File Expand all files Collapse all files
CLAUDE.md
+469
View File
@@ -0,0 +1,469 @@
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```gherkin
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
```bash
# 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:
```bash
cp ~/.local/share/mcp-env-template ~/.bashrc
# Edit tokens and endpoints for your infrastructure
```
Required environment variables:
```bash
# 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:
```bash
# 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.