feat: Enhanced Claude Code configuration with comprehensive best practices

- Updated project CLAUDE.md with detailed commands, workflows, and guidelines - Added environment configuration and performance monitoring commands - Enhanced security guidelines and commit message conventions - Created 5 custom slash commands for common MEV bot development tasks: * /analyze-performance - Comprehensive performance analysis * /debug-issue - Structured debugging workflow * /implement-feature - Feature implementation framework * /security-audit - Security audit checklist * /optimize-performance - Performance optimization strategy - Updated global CLAUDE.md with universal best practices - Improved file organization and development standards 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
2025-09-14 07:41:04 -05:00
parent be7b1b55d0
commit 38cce575f5
6 changed files with 461 additions and 9 deletions
--- a/.claude/commands/analyze-performance.md
+++ b/.claude/commands/analyze-performance.md
@@ -0,0 +1,34 @@
+# Analyze Performance Issues
+
+Perform a comprehensive performance analysis of the MEV bot: $ARGUMENTS
+
+## Analysis Steps:
+1. **Memory Profiling**: Check for memory leaks and high allocation patterns
+2. **CPU Profiling**: Identify CPU bottlenecks and hot paths
+3. **Goroutine Analysis**: Look for goroutine leaks and blocking operations
+4. **I/O Performance**: Analyze network and disk I/O patterns
+5. **Concurrency Issues**: Check for race conditions and lock contention
+
+## Performance Commands to Run:
+```bash
+# Memory profile
+go tool pprof http://localhost:9090/debug/pprof/heap
+
+# CPU profile
+go tool pprof http://localhost:9090/debug/pprof/profile?seconds=30
+
+# Goroutine analysis
+go tool pprof http://localhost:9090/debug/pprof/goroutine
+
+# Enable race detector
+go run -race ./cmd/mev-bot
+```
+
+## Analysis Focus Areas:
+- Worker pool efficiency in `pkg/market/pipeline.go`
+- Event parsing performance in `pkg/events/`
+- Uniswap math calculations in `pkg/uniswap/`
+- Memory usage in large transaction processing
+- Rate limiting effectiveness in `internal/ratelimit/`
+
+Please provide specific performance metrics and recommendations for optimization.
--- a/.claude/commands/debug-issue.md
+++ b/.claude/commands/debug-issue.md
@@ -0,0 +1,43 @@
+# Debug MEV Bot Issue
+
+Debug the following MEV bot issue: $ARGUMENTS
+
+## Debugging Protocol:
+1. **Issue Understanding**: Analyze the problem description and expected vs actual behavior
+2. **Log Analysis**: Examine relevant log files in `logs/` directory
+3. **Code Investigation**: Review related source code and recent changes
+4. **Reproduction**: Attempt to reproduce the issue in a controlled environment
+5. **Root Cause**: Identify the underlying cause and contributing factors
+
+## Debugging Commands:
+```bash
+# Check logs
+tail -f logs/mev-bot.log
+
+# Run with debug logging
+LOG_LEVEL=debug ./mev-bot start
+
+# Check system resources
+htop
+iostat -x 1 5
+
+# Network connectivity
+nc -zv arbitrum-mainnet.core.chainstack.com 443
+
+# Go runtime stats
+curl http://localhost:9090/debug/vars | jq
+```
+
+## Investigation Areas:
+- **Connection Issues**: RPC endpoint connectivity and WebSocket stability
+- **Parsing Errors**: Transaction and event parsing failures
+- **Performance**: High CPU/memory usage or processing delays  
+- **Concurrency**: Race conditions or deadlocks
+- **Configuration**: Environment variables and configuration issues
+
+## Output Requirements:
+- Clear problem identification
+- Step-by-step reproduction instructions
+- Root cause analysis
+- Proposed solution with implementation steps
+- Test plan to verify the fix
--- a/.claude/commands/implement-feature.md
+++ b/.claude/commands/implement-feature.md
@@ -0,0 +1,38 @@
+# Implement MEV Bot Feature
+
+Implement the following feature for the MEV bot: $ARGUMENTS
+
+## Implementation Framework:
+1. **Requirements Analysis**: Break down the feature requirements and acceptance criteria
+2. **Architecture Design**: Design the solution following existing patterns
+3. **Interface Design**: Define clean interfaces between components
+4. **Implementation**: Write the code following Go best practices
+5. **Testing**: Create comprehensive unit and integration tests
+6. **Documentation**: Update relevant documentation and examples
+
+## Implementation Standards:
+- **Code Quality**: Follow Go conventions and project coding standards
+- **Error Handling**: Implement robust error handling with context
+- **Logging**: Add appropriate logging with structured fields
+- **Testing**: Achieve >90% test coverage
+- **Performance**: Consider performance implications and add metrics
+- **Security**: Validate all inputs and handle edge cases
+
+## File Organization:
+- **Core Logic**: Place in appropriate `pkg/` subdirectory
+- **Configuration**: Add to `internal/config/` if needed  
+- **Tests**: Co-locate with source files (`*_test.go`)
+- **Documentation**: Update `docs/` and inline comments
+
+## Integration Points:
+- **Event System**: Integrate with `pkg/events/` for transaction processing
+- **Market Pipeline**: Connect to `pkg/market/pipeline.go` for processing
+- **Monitoring**: Add metrics and health checks
+- **Configuration**: Add necessary environment variables
+
+## Deliverables:
+- Working implementation with tests
+- Updated documentation
+- Configuration updates
+- Performance benchmarks if applicable
+- Migration guide for existing deployments
--- a/.claude/commands/optimize-performance.md
+++ b/.claude/commands/optimize-performance.md
@@ -0,0 +1,84 @@
+# Optimize MEV Bot Performance
+
+Optimize the performance of the MEV bot in the following area: $ARGUMENTS
+
+## Performance Optimization Strategy:
+
+### 1. **Profiling and Measurement**
+```bash
+# CPU profiling
+go tool pprof http://localhost:9090/debug/pprof/profile?seconds=30
+
+# Memory profiling
+go tool pprof http://localhost:9090/debug/pprof/heap
+
+# Trace analysis
+go tool trace trace.out
+
+# Benchmark testing
+go test -bench=. -benchmem ./...
+```
+
+### 2. **Optimization Areas**
+
+#### **Concurrency Optimization**
+- Worker pool sizing and configuration
+- Channel buffer optimization
+- Goroutine pooling and reuse
+- Lock contention reduction
+- Context cancellation patterns
+
+#### **Memory Optimization**
+- Object pooling for frequent allocations
+- Buffer reuse patterns
+- Garbage collection tuning
+- Memory leak prevention
+- Slice and map pre-allocation
+
+#### **I/O Optimization**
+- Connection pooling for RPC calls
+- Request batching and pipelining
+- Caching frequently accessed data
+- Asynchronous processing patterns
+- Rate limiting optimization
+
+#### **Algorithm Optimization**
+- Uniswap math calculation efficiency
+- Event parsing performance
+- Data structure selection
+- Caching strategies
+- Indexing improvements
+
+### 3. **MEV Bot Specific Optimizations**
+
+#### **Transaction Processing Pipeline**
+- Parallel transaction processing
+- Event filtering optimization
+- Batch processing strategies
+- Pipeline stage optimization
+
+#### **Market Analysis**
+- Price calculation caching
+- Pool data caching
+- Historical data indexing
+- Real-time processing optimization
+
+#### **Arbitrage Detection**
+- Opportunity scanning efficiency
+- Profit calculation optimization
+- Market impact analysis speed
+- Cross-DEX comparison performance
+
+## Implementation Guidelines:
+- Measure before optimizing (baseline metrics)
+- Focus on bottlenecks identified through profiling
+- Maintain code readability and maintainability
+- Add performance tests for regressions
+- Document performance characteristics
+
+## Deliverables:
+- Performance benchmark results (before/after)
+- Optimized code with maintained functionality
+- Performance monitoring enhancements
+- Optimization documentation
+- Regression test suite
--- a/.claude/commands/security-audit.md
+++ b/.claude/commands/security-audit.md
@@ -0,0 +1,72 @@
+# MEV Bot Security Audit
+
+Perform a comprehensive security audit of the MEV bot focusing on: $ARGUMENTS
+
+## Security Audit Checklist:
+
+### 1. **Code Security Analysis**
+```bash
+# Static security analysis
+gosec ./...
+
+# Dependency vulnerabilities
+go list -json -m all | nancy sleuth
+
+# Secret scanning
+git-secrets --scan
+```
+
+### 2. **Input Validation Review**
+- Transaction data parsing validation
+- RPC response validation
+- Configuration parameter validation
+- Mathematical overflow/underflow checks
+- Buffer overflow prevention
+
+### 3. **Cryptographic Security**
+- Private key handling and storage
+- Signature verification processes
+- Random number generation
+- Hash function usage
+- Encryption at rest and in transit
+
+### 4. **Network Security**
+- RPC endpoint authentication
+- TLS/SSL configuration
+- Rate limiting implementation
+- DDoS protection mechanisms
+- WebSocket connection security
+
+### 5. **Runtime Security**
+- Memory safety in Go code
+- Goroutine safety and race conditions
+- Resource exhaustion protection
+- Error information disclosure
+- Logging security (no sensitive data)
+
+## Specific MEV Bot Security Areas:
+
+### **Transaction Processing**
+- Validate all transaction inputs
+- Prevent transaction replay attacks  
+- Secure handling of swap calculations
+- Protection against malicious contract calls
+
+### **Market Data Integrity**
+- Price feed validation
+- Oracle manipulation detection
+- Historical data integrity
+- Real-time data verification
+
+### **Financial Security**
+- Gas estimation accuracy
+- Slippage protection
+- Minimum profit validation
+- MEV protection mechanisms
+
+## Output Requirements:
+- Detailed security findings report
+- Risk assessment (Critical/High/Medium/Low)
+- Remediation recommendations
+- Implementation timeline for fixes
+- Security testing procedures
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -1,6 +1,49 @@
-# MEV Bot Project - Claude Context
+# MEV Bot Project - Claude Code Configuration

-This file contains context information for Claude about the MEV Bot project.
+This file contains comprehensive Claude Code configuration and context information for the MEV Bot project.
+
+## 🚀 Quick Start Commands
+
+### Essential Build & Test Commands
+```bash
+# 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
+```bash
+# Setup development environment
+export ARBITRUM_RPC_ENDPOINT="wss://arbitrum-mainnet.core.chainstack.com/73bc682fe9c5bd23b42ef40f752fa89a"
+export ARBITRUM_WS_ENDPOINT="wss://arbitrum-mainnet.core.chainstack.com/73bc682fe9c5bd23b42ef40f752fa89a"
+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
+```

 ## Project Overview
 This is an MEV (Maximal Extractable Value) bot written in Go 1.24+ that monitors the Arbitrum sequencer for potential swap opportunities. When a potential swap is detected, the bot scans the market to determine if the swap is large enough to move the price using off-chain methods.
@@ -30,12 +73,34 @@ This is an MEV (Maximal Extractable Value) bot written in Go 1.24+ that monitors
 - Use the universal message bus for inter-module communication
 - Adhere to the standards defined in the project plan

-## Development Guidelines
- Focus on implementing the features outlined in the project plan
- Ensure all code follows Go best practices
- Write comprehensive tests for all functionality
- Document all public APIs and complex algorithms
- Follow the performance requirements outlined in COMMON.md
+## 📋 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
+```bash
+# 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
+```

 ## System Architecture
 The MEV Bot follows a modular architecture with clearly defined components that communicate through well-defined interfaces.
@@ -113,3 +178,119 @@ As Claude, you're particularly skilled at:
   - Ensuring code follows established patterns and conventions

 When working on this project, please focus on these areas where your strengths will be most beneficial.
+
+## 🛠 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
+```bash
+# 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
+```bash
+# Arbitrum RPC Configuration
+export ARBITRUM_RPC_ENDPOINT="wss://arbitrum-mainnet.core.chainstack.com/73bc682fe9c5bd23b42ef40f752fa89a"
+export ARBITRUM_WS_ENDPOINT="wss://arbitrum-mainnet.core.chainstack.com/73bc682fe9c5bd23b42ef40f752fa89a"
+
+# 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
+```bash
+# 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
+```bash
+# 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 .
+```