mev-beta/.claude/CLAUDE.md

Claude CLI Configuration

This directory contains Claude Code configuration and tools for the MEV Bot project.

🚀 Quick Start Commands

Essential Build & Test Commands

# Build the MEV bot binary
make build

# Run tests
make test

# Start development server with hot reload
./scripts/run.sh

# Build and run with logging
./scripts/build.sh && ./mev-bot start

# Check for Go modules issues
go mod tidy && go mod verify

# Run linter
golangci-lint run

# Run security analysis
gosec ./...

Development Workflow Commands

# Setup development environment
export ARBITRUM_RPC_ENDPOINT="wss://arbitrum-mainnet.core.chainstack.com/f69d14406bc00700da9b936504e1a870"
export ARBITRUM_WS_ENDPOINT="wss://arbitrum-mainnet.core.chainstack.com/f69d14406bc00700da9b936504e1a870"
export METRICS_ENABLED="false"

# Run with timeout for testing
timeout 30 ./mev-bot start

# Debug with verbose logging
LOG_LEVEL=debug ./mev-bot start

# Profile performance
go tool pprof http://localhost:6060/debug/pprof/profile

Claude Commands Directory

The .claude/commands/ directory contains predefined commands for common development tasks:

• analyze-performance.md - Analyze application performance
• debug-issue.md - Debug issues in the codebase
• implement-feature.md - Implement new features
• optimize-performance.md - Optimize performance
• security-audit.md - Perform security audits

Claude Settings

The .claude/settings.local.json file contains Claude's permissions configuration:

{
  "permissions": {
    "allow": [
      "Bash(find:*)",
      "Bash(go mod:*)",
      "Bash(go list:*)",
      "mcp__ide__getDiagnostics",
      "Bash(go test:*)",
      "Bash(go build:*)",
      "Read(//tmp/**)",
      "Bash(./mev-bot start --help)",
      "Bash(xargs ls:*)",
      "Bash(timeout:*)",
      "WebSearch",
      "WebFetch(domain:docs.uniswap.org)",
      "WebFetch(domain:github.com)",
      "WebFetch(domain:raw.githubusercontent.com)",
      "WebFetch(domain:htdocs.dev)"
    ],
    "deny": [],
    "ask": []
  }
}

📋 Development Guidelines & Code Style

Go Best Practices

• Error Handling: Always wrap errors with context using fmt.Errorf("operation failed: %w", err)
• Concurrency: Use worker pools for processing large datasets (see pkg/market/pipeline.go)
• Interfaces: Keep interfaces small and focused (1-3 methods maximum)
• Testing: Aim for >90% test coverage with table-driven tests
• Logging: Use structured logging with slog package
• Performance: Profile regularly with go tool pprof

Code Organization Rules

• File Size: Keep files under 500 lines (split larger files into logical components)
• Package Structure: Follow Go standard layout (cmd/, internal/, pkg/)
• Naming: Use Go naming conventions (PascalCase for exports, camelCase for private)
• Documentation: Document all exported functions with examples
• Constants: Group related constants in blocks with iota when appropriate

Required Checks Before Commit

# Run all checks before committing
make test && make lint && go mod tidy

# Security scan
gosec ./...

# Dependency vulnerability check
go list -json -m all | nancy sleuth

Claude's Primary Focus Areas

As Claude, you're particularly skilled at:

1. Code Architecture and Design Patterns

   • Implementing clean, maintainable architectures
   • Applying appropriate design patterns (pipeline, worker pool, etc.)
   • Creating well-structured interfaces between components
   • Ensuring loose coupling and high cohesion

2. System Integration and APIs

   • Designing clear APIs between components
   • Implementing proper data flow between modules
   • Creating robust configuration management
   • Building error handling and recovery mechanisms

3. Writing Clear Documentation

   • Documenting complex algorithms and mathematical calculations
   • Creating clear API documentation
   • Writing architectural decision records
   • Producing user guides and examples

4. Implementing Robust Error Handling

   • Using Go's error wrapping with context
   • Implementing retry mechanisms with exponential backoff
   • Handling timeouts appropriately
   • Creating comprehensive logging strategies

5. Creating Maintainable and Scalable Code Structures

   • Organizing code for easy testing and maintenance
   • Implementing performance monitoring and metrics
   • Designing for horizontal scalability
   • Ensuring code follows established patterns and conventions

🛠 Claude Code Optimization Settings

Workflow Preferences

• Always commit changes: Use git commit -am "descriptive message" after significant changes
• Branch naming: Use hyphens (feat-add-new-parser, fix-memory-leak)
• Context management: Use /compact to manage long conversations
• Parallel processing: Leverage Go's concurrency patterns extensively

File Organization Preferences

• Never save temporary files to root: Use /tmp/ or internal/temp/
• Log files: Always save to logs/ directory
• Test files: Place alongside source files with _test.go suffix
• Documentation: Keep in docs/ with clear naming

Performance Monitoring

# Enable metrics endpoint
export METRICS_ENABLED="true"
export METRICS_PORT="9090"

# Monitor memory usage
go tool pprof http://localhost:9090/debug/pprof/heap

# Monitor CPU usage
go tool pprof http://localhost:9090/debug/pprof/profile?seconds=30

# Monitor goroutines
go tool pprof http://localhost:9090/debug/pprof/goroutine

🔧 Environment Configuration

Required Environment Variables

# Arbitrum RPC Configuration
export ARBITRUM_RPC_ENDPOINT="wss://arbitrum-mainnet.core.chainstack.com/f69d14406bc00700da9b936504e1a870"
export ARBITRUM_WS_ENDPOINT="wss://arbitrum-mainnet.core.chainstack.com/f69d14406bc00700da9b936504e1a870"

# Application Configuration
export LOG_LEVEL="info"
export METRICS_ENABLED="false"
export METRICS_PORT="9090"

# Development Configuration
export GO_ENV="development"
export DEBUG="true"

Optional Environment Variables

# Performance Tuning
export GOMAXPROCS=4
export GOGC=100

# Logging Configuration
export LOG_FORMAT="json"
export LOG_OUTPUT="logs/mev-bot.log"

# Rate Limiting
export MAX_RPS=100
export RATE_LIMIT_BURST=200

📝 Commit Message Conventions

Format

type(scope): brief description

- Detailed explanation of changes
- Why the change was needed
- Any breaking changes or migration notes

🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>

Types

• feat: New feature implementation
• fix: Bug fix
• perf: Performance improvement
• refactor: Code restructuring without feature changes
• test: Adding or updating tests
• docs: Documentation updates
• build: Build system or dependency changes
• ci: CI/CD pipeline changes

🚨 Security Guidelines

Never Commit

• Private keys or wallet seeds
• API keys or secrets
• RPC endpoints with authentication
• Personal configuration files

Always Validate

• Input parameters for all functions
• RPC responses before processing
• Mathematical calculations for overflow
• Memory allocations for bounds

Security Commands

# Scan for secrets
git-secrets --scan

# Security audit
gosec ./...

# Dependency vulnerabilities
go list -json -m all | nancy sleuth

# Check for hardcoded credentials
grep -r "password\|secret\|key" --exclude-dir=.git .