docs(architecture): update AI assistant documentation and project structure

Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com>

CLAUDE.md

@@ -2,6 +2,11 @@
 
 This file contains comprehensive Claude Code configuration and context information for the MEV Bot project.
 
+**Note:** For Claude-specific CLI configuration, commands, and development guidelines, please refer to the [.claude/](.claude/) directory which contains:
+- [.claude/CLAUDE.md](.claude/CLAUDE.md) - Complete Claude Code CLI configuration
+- [.claude/commands/](.claude/commands/) - Slash commands for Claude Code
+- [.claude/scripts/](.claude/scripts/) - Scripts for Claude Code development workflow
+
 ## 🚀 Quick Start Commands
 
 ### Essential Build & Test Commands
@@ -66,6 +71,7 @@ This is an MEV (Maximal Extractable Value) bot written in Go 1.24+ that monitors
 - `@prompts/` - AI prompts for development assistance
 - `docs/` - Documentation
 - `scripts/` - Scripts for building, testing, and deployment
+- `.claude/` - Claude Code specific configuration and tools
 
 ## Key Integration Points
 - Refer to @prompts/COMMON.md for core requirements and integration points

GEMINI.md

@@ -2,6 +2,8 @@
 
 This file contains context information for Gemini about the MEV Bot project.
 
+**Note:** For a comprehensive understanding of the project structure, development guidelines, and AI assistant configuration, please refer to [CLAUDE.md](CLAUDE.md), which contains the complete project documentation.
+
 ## 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.
 
@@ -24,84 +26,6 @@ This is an MEV (Maximal Extractable Value) bot written in Go 1.24+ that monitors
 - `docs/` - Documentation
 - `scripts/` - Scripts for building, testing, and deployment
 
-## Key Integration Points
-- Refer to @prompts/COMMON.md for core requirements and integration points
-- Follow the modular architecture with independent components
-- 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
-
-## Mathematical Implementation Details
-
-### Uniswap V3 Pricing Functions
-The core of the MEV bot's functionality relies on precise Uniswap V3 pricing calculations:
-
-1. **sqrtPriceX96 to Price Conversion**
-   - Formula: `price = (sqrtPriceX96 / 2^96)^2`
-   - Implementation uses `math/big` for precision
-   - Critical for accurate price impact calculations
-
-2. **Price to sqrtPriceX96 Conversion**
-   - Formula: `sqrtPriceX96 = sqrt(price) * 2^96`
-   - Used when initializing or updating pool states
-   - Requires careful handling of floating-point precision
-
-3. **Tick Calculations**
-   - Formula: `tick = log_1.0001(sqrtPriceX96 / 2^96)^2`
-   - Ticks range from -887272 to 887272
-   - Used for discrete price levels in Uniswap V3
-
-4. **Price Impact Calculations**
-   - Based on liquidity and amount being swapped
-   - Formula: `priceImpact = amountIn / liquidity`
-   - Critical for determining arbitrage profitability
-
-### Precision Handling
-- Uses `github.com/holiman/uint256` for precise uint256 arithmetic
-- Implements proper rounding strategies
-- Handles overflow and underflow conditions
-- Maintains precision throughout calculations
-
-## Performance Optimization Areas
-
-### Concurrency Patterns
-1. **Worker Pools**
-   - Used in `pkg/scanner` for concurrent event processing
-   - Configurable number of workers based on system resources
-   - Channel-based job distribution
-
-2. **Pipeline Processing**
-   - Multi-stage processing in `pkg/market`
-   - Parallel processing of different transaction batches
-   - Backpressure handling through channel buffering
-
-3. **Caching Strategies**
-   - Singleflight pattern to prevent duplicate requests
-   - Time-based expiration for cached pool data
-   - Memory-efficient data structures
-
-### Low-Level Optimizations
-1. **Memory Allocation Reduction**
-   - Object pooling for frequently created objects
-   - Pre-allocation of slices and maps when size is known
-   - Reuse of buffers and temporary variables
-
-2. **Algorithmic Efficiency**
-   - O(1) lookups for cached pool data
-   - Efficient sorting and searching algorithms
-   - Minimal computational overhead in hot paths
-
-3. **System-Level Optimizations**
-   - Proper tuning of Go's garbage collector
-   - NUMA-aware memory allocation (if applicable)
-   - CPU cache-friendly data access patterns
-
 ## Gemini's Primary Focus Areas
 As Gemini, you're particularly skilled at:
 
@@ -109,30 +33,12 @@ As Gemini, you're particularly skilled at:
    - Implementing precise Uniswap V3 pricing functions
    - Optimizing mathematical calculations for performance
    - Ensuring numerical stability and precision
-   - Creating efficient algorithms for arbitrage detection
 
-2. **Optimizing Performance and Efficiency**
+2. **Performance Optimization**
    - Profiling and identifying bottlenecks in critical paths
    - Reducing memory allocations in hot code paths
    - Optimizing concurrency patterns for maximum throughput
-   - Tuning garbage collection for low-latency requirements
-
-3. **Understanding Complex Uniswap V3 Pricing Functions**
-   - Implementing accurate tick and sqrtPriceX96 conversions
-   - Calculating price impact with proper precision handling
-   - Working with liquidity and fee calculations
-   - Handling edge cases in pricing mathematics
-
-4. **Implementing Concurrent and Parallel Processing Patterns**
-   - Designing efficient worker pool implementations
-   - Creating robust pipeline processing systems
-   - Managing synchronization primitives correctly
-   - Preventing race conditions and deadlocks
-
-5. **Working with Low-Level System Operations**
-   - Optimizing memory usage and allocation patterns
-   - Tuning system-level parameters for performance
-   - Implementing efficient data structures for high-frequency access
-   - Working with CPU cache optimization techniques
 
 When working on this project, please focus on these areas where your strengths will be most beneficial.
+
+For complete development guidelines, system architecture details, and comprehensive configuration information, please refer to [CLAUDE.md](CLAUDE.md).

OPENCODE.md

@@ -2,6 +2,8 @@
 
 This file contains context information for OpenCode about the MEV Bot project.
 
+**Note:** For a comprehensive understanding of the project structure, development guidelines, and AI assistant configuration, please refer to [CLAUDE.md](CLAUDE.md), which contains the complete project documentation.
+
 ## 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.
 
@@ -24,124 +26,6 @@ This is an MEV (Maximal Extractable Value) bot written in Go 1.24+ that monitors
 - `docs/` - Documentation
 - `scripts/` - Scripts for building, testing, and deployment
 
-## Key Integration Points
-- Refer to @prompts/COMMON.md for core requirements and integration points
-- Follow the modular architecture with independent components
-- 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
-
-## Code Quality and Testing Standards
-
-### Go Best Practices
-1. **Error Handling**
-   - Use Go's error wrapping with context: `fmt.Errorf("failed to process transaction: %w", err)`
-   - Implement retry mechanisms with exponential backoff for transient failures
-   - Handle timeouts appropriately with context cancellation
-   - Log errors at appropriate levels (debug, info, warn, error)
-
-2. **Concurrency Safety**
-   - Use mutexes correctly to protect shared data
-   - Avoid race conditions with proper synchronization
-   - Use channels for communication between goroutines
-   - Implement graceful shutdown procedures
-
-3. **Code Structure**
-   - Follow idiomatic Go patterns and conventions
-   - Use clear, descriptive names for variables, functions, and types
-   - Organize code into logical packages with clear responsibilities
-   - Implement interfaces for loose coupling between components
-
-4. **Performance Considerations**
-   - Minimize memory allocations in hot paths
-   - Use appropriate data structures for the task
-   - Profile code regularly to identify bottlenecks
-   - Follow the performance requirements (latency < 10 microseconds for critical path)
-
-### Testing Standards
-1. **Unit Testing**
-   - Write tests for all functions and methods
-   - Use table-driven tests for multiple test cases
-   - Mock external dependencies for deterministic testing
-   - Test edge cases and boundary conditions
-
-2. **Integration Testing**
-   - Test component interactions and data flow
-   - Verify correct behavior with real (or realistic) data
-   - Test error conditions and recovery mechanisms
-   - Validate configuration loading and environment variable overrides
-
-3. **Property-Based Testing**
-   - Use property-based testing for mathematical functions
-   - Verify invariants and mathematical relationships
-   - Test with randomized inputs to find edge cases
-   - Ensure numerical stability and precision
-
-4. **Benchmarking**
-   - Create benchmarks for performance-critical code paths
-   - Measure latency and throughput for core functionality
-   - Compare performance before and after optimizations
-   - Identify bottlenecks in the processing pipeline
-
-### Documentation Standards
-1. **Code Comments**
-   - Comment all exported functions, types, and variables
-   - Explain complex algorithms and mathematical calculations
-   - Document any non-obvious implementation decisions
-   - Keep comments up-to-date with code changes
-
-2. **API Documentation**
-   - Provide clear usage examples for public APIs
-   - Document expected inputs and outputs
-   - Explain error conditions and return values
-   - Include performance characteristics where relevant
-
-3. **Architecture Documentation**
-   - Maintain up-to-date architectural diagrams
-   - Document data flow between components
-   - Explain design decisions and trade-offs
-   - Provide deployment and configuration guides
-
-## Debugging and Troubleshooting
-
-### Common Issues and Solutions
-1. **Rate Limiting Problems**
-   - Monitor RPC call rates and adjust configuration
-   - Implement proper fallback mechanisms for RPC endpoints
-   - Use caching to reduce duplicate requests
-
-2. **Concurrency Issues**
-   - Use race detection tools during testing
-   - Implement proper locking for shared data
-   - Avoid deadlocks with careful resource ordering
-
-3. **Precision Errors**
-   - Use appropriate data types for mathematical calculations
-   - Validate results against known test cases
-   - Handle overflow and underflow conditions properly
-
-### Debugging Tools and Techniques
-1. **Logging**
-   - Use structured logging with appropriate levels
-   - Include contextual information in log messages
-   - Implement log sampling for high-frequency events
-
-2. **Profiling**
-   - Use Go's built-in profiling tools (pprof)
-   - Monitor CPU, memory, and goroutine usage
-   - Identify hot paths and optimization opportunities
-
-3. **Testing Utilities**
-   - Use the test utilities in `pkg/test`
-   - Create realistic test data for validation
-   - Implement integration tests for end-to-end validation
-
 ## OpenCode's Primary Focus Areas
 As OpenCode, you're particularly skilled at:
 
@@ -149,30 +33,12 @@ As OpenCode, you're particularly skilled at:
    - Implementing clean, idiomatic Go code
    - Following established patterns and conventions
    - Debugging complex concurrency issues
-   - Optimizing code for performance and readability
 
 2. **Implementing Test Cases and Ensuring Code Quality**
    - Writing comprehensive unit and integration tests
    - Implementing property-based tests for mathematical functions
    - Creating performance benchmarks for critical paths
-   - Ensuring proper error handling and recovery
-
-3. **Following Established Coding Patterns and Conventions**
-   - Using appropriate design patterns (worker pools, pipelines, etc.)
-   - Following Go's idiomatic patterns and best practices
-   - Implementing consistent error handling and logging
-   - Maintaining code organization and package structure
-
-4. **Identifying and Fixing Bugs**
-   - Debugging race conditions and concurrency issues
-   - Identifying performance bottlenecks
-   - Fixing precision errors in mathematical calculations
-   - Resolving configuration and deployment issues
-
-5. **Ensuring Code is Well-Structured and Readable**
-   - Organizing code into logical packages with clear responsibilities
-   - Using clear, descriptive naming conventions
-   - Implementing proper abstraction and encapsulation
-   - Maintaining consistency across the codebase
 
 When working on this project, please focus on these areas where your strengths will be most beneficial.
+
+For complete development guidelines, system architecture details, and comprehensive configuration information, please refer to [CLAUDE.md](CLAUDE.md).

QWEN.md

@@ -2,6 +2,15 @@
 
 This file contains context information for Qwen Code about the MEV Bot project.
 
+**Note:** For a comprehensive understanding of the project structure, development guidelines, and AI assistant configuration, please refer to [CLAUDE.md](CLAUDE.md), which contains the complete project documentation.
+
+For Qwen Code-specific configuration, commands, and development guidelines, please refer to the [.qwen/](.qwen/) directory which contains:
+- [.qwen/QWEN.md](.qwen/QWEN.md) - Complete Qwen Code configuration and context
+- [.qwen/commands/](.qwen/commands/) - Slash commands for Qwen Code
+- [.qwen/config/](.qwen/config/) - Configuration files for Qwen Code
+- [.qwen/prompts/](.qwen/prompts/) - Qwen Code specific prompts
+- [.qwen/scripts/](.qwen/scripts/) - Scripts for Qwen Code development workflow
+
 ## 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.
 
@@ -24,111 +33,21 @@ This is an MEV (Maximal Extractable Value) bot written in Go 1.24+ that monitors
 - `@prompts/` - AI prompts for development assistance
 - `docs/` - Documentation
 - `scripts/` - Scripts for building, testing, and deployment
+- `.qwen/` - Qwen Code specific configuration and tools
 
-## Technologies
+## Qwen Code's Primary Focus Areas
-- Go 1.24+
+As Qwen Code, you're particularly skilled at:
-- Arbitrum sequencer monitoring via Ethereum JSON-RPC
-- Uniswap V3 pricing functions (price to tick, sqrtPriceX96 to tick, etc.)
-- Multiple transport mechanisms (shared memory, Unix sockets, TCP, WebSockets, gRPC)
-- Concurrency patterns (worker pools, pipelines, fan-in/fan-out)
-- Ethereum client library (github.com/ethereum/go-ethereum)
-- Uint256 arithmetic (github.com/holiman/uint256)
-- Rate limiting (golang.org/x/time/rate)
-- Extended concurrency primitives (golang.org/x/sync)
-- CLI framework (github.com/urfave/cli/v2)
-- YAML parsing (gopkg.in/yaml.v3)
 
-## Core Components
+1. **Mathematical Computations**
+   - Implementing precise Uniswap V3 pricing functions
+   - Ensuring numerical stability and precision
+   - Working with liquidity and fee calculations
 
-### 1. Configuration Management (`internal/config`)
+2. **Algorithmic Implementation**
-Handles loading configuration from YAML files with environment variable overrides. Supports multiple environments and rate limiting configurations for RPC endpoints.
+   - Creating efficient algorithms for arbitrage detection
+   - Implementing accurate tick and sqrtPriceX96 conversions
+   - Calculating price impact with proper precision handling
 
-### 2. Event Processing (`pkg/events`)
+When working on this project, please focus on these areas where your strengths will be most beneficial.
-Parses Ethereum transactions to identify DEX interactions and extracts relevant event data including swap amounts, pool addresses, and pricing information.
 
-### 3. Market Pipeline (`pkg/market`)
+For complete development guidelines, system architecture details, and comprehensive configuration information, please refer to [CLAUDE.md](CLAUDE.md).
-Implements a multi-stage processing pipeline for transactions:
-- Transaction decoding and event parsing
-- Market analysis using Uniswap V3 math
-- Arbitrage opportunity detection
-
-### 4. Arbitrum Monitor (`pkg/monitor`)
-Monitors the Arbitrum sequencer for new blocks and transactions, with rate limiting and concurrent processing support.
-
-### 5. Market Scanner (`pkg/scanner`)
-Uses a worker pool pattern to analyze market events for potential arbitrage opportunities with caching and concurrency support.
-
-### 6. Uniswap Pricing (`pkg/uniswap`)
-Implements Uniswap V3 pricing functions for converting between sqrtPriceX96, ticks, and actual prices.
-
-## System Architecture
-
-### Data Flow
-1. Arbitrum Monitor detects new blocks and transactions
-2. Events are parsed from transactions by the Event Parser
-3. Transactions flow through the Market Pipeline for processing
-4. Market Scanner analyzes events for arbitrage opportunities
-5. Profitable opportunities are identified and potentially executed
-
-### Concurrency Model
-The system uses several concurrency patterns to achieve high throughput:
-- Worker pools for parallel transaction processing
-- Pipelines for multi-stage processing
-- Fan-in/fan-out patterns for distributing work
-- Rate limiting to prevent overwhelming RPC endpoints
-- Caching with singleflight to prevent duplicate requests
-
-### Communication Patterns
-- Pipeline pattern for multi-stage transaction processing
-- Worker pool pattern for concurrent event analysis
-- Message passing through Go channels
-- Shared memory access with proper synchronization
-
-## Mathematical Implementation
-
-### Uniswap V3 Pricing
-The system implements precise Uniswap V3 pricing calculations:
-- sqrtPriceX96 to price conversion: `price = (sqrtPriceX96 / 2^96)^2`
-- Price to sqrtPriceX96 conversion: `sqrtPriceX96 = sqrt(price) * 2^96`
-- Tick calculations: `tick = log_1.0001(sqrtPriceX96 / 2^96)^2`
-- Price impact calculations using liquidity values
-
-### Precision Handling
-- Uses `github.com/holiman/uint256` for precise uint256 arithmetic
-- Uses `math/big` for floating-point calculations when needed
-- Implements proper rounding and precision handling
-
-## Development Notes
-- Focus on off-chain price movement calculations using precise Uniswap V3 mathematics
-- Refer to official Uniswap V3 documentation for pricing functions and pool mechanics
-- Implement market scanning functionality for potential arbitrage opportunities
-- Follow the modular architecture with independent components
-- Use the universal message bus for inter-module communication
-- Adhere to the standards defined in @prompts/COMMON.md
-- Pay attention to performance requirements (latency < 10 microseconds for critical path)
-- Implement proper error handling with context wrapping and retry mechanisms
-- Ensure comprehensive test coverage including unit tests, integration tests, and benchmarks
-
-## Integration Points
-- Configuration management via `internal/config`
-- Event processing through `pkg/events` and `pkg/market`
-- Communication layer via the pipeline pattern in `pkg/market`
-- Data persistence through the market manager in `pkg/market`
-- Monitoring and metrics collection via the logger in `internal/logger`
-- Rate limiting via `internal/ratelimit`
-
-## Performance Considerations
-- Use worker pools for concurrent transaction processing
-- Implement caching for pool data to reduce RPC calls
-- Apply rate limiting to prevent exceeding RPC provider limits
-- Use uint256 arithmetic for precise calculations
-- Minimize memory allocations in hot paths
-- Profile code regularly to identify bottlenecks
-- Optimize critical path for sub-10 microsecond latency
-
-## Testing Approach
-- Unit tests for all mathematical functions and core logic
-- Integration tests for component interactions
-- Performance benchmarks for critical paths
-- Property-based testing for mathematical correctness
-- Mock external dependencies for deterministic testing

README.md

@@ -49,11 +49,37 @@ Configuration files can be found in the `config/` directory.
 ├── go.mod               # Go module definition
 ├── go.sum               # Go module checksums
 ├── README.md            # This file
-└── QWEN.md              # Qwen Code context file
+├── .claude/             # Claude Code specific configuration and tools
+├── .gemini/             # Gemini specific configuration and tools
+├── .opencode/           # OpenCode specific configuration and tools
+├── .qwen/               # Qwen Code specific configuration and tools
+├── CLAUDE.md            # Complete project documentation and Claude context (comprehensive example)
+├── GEMINI.md            # Gemini context (simplified, references CLAUDE.md)
+├── OPENCODE.md          # OpenCode context (simplified, references CLAUDE.md)
+└── QWEN.md              # Qwen Code context (simplified, references CLAUDE.md)
 ```
 
 ## Development
 
+### AI Assistant CLI Configurations
+
+This project is configured to work with multiple AI coding assistants, each with specialized expertise:
+
+- **Claude** (`.claude/`) - System architecture, design patterns, and integration
+- **OpenCode** (`.opencode/`) - Multi-language development and testing
+- **Qwen Code** (`.qwen/`) - Mathematical computations and precision handling
+- **Gemini** (`.gemini/`) - Performance optimization and concurrency
+
+### Git Workflow
+
+This project follows a comprehensive Git workflow with specific branch strategies, commit conventions, and automated checks. See [docs/GIT_WORKFLOW.md](docs/GIT_WORKFLOW.md) and [docs/BRANCH_STRATEGY.md](docs/BRANCH_STRATEGY.md) for detailed information.
+
+Key aspects:
+- **Branch Strategy**: `main`, `develop`, `feature/*`, `fix/*`, `release/*`, `hotfix/*`
+- **Commit Messages**: Conventional commits format
+- **Git Hooks**: Pre-commit and pre-push checks
+- **Pull Requests**: Required for all merges to `main` and `develop`
+
 ### Prompts Directory
 
 The `@prompts/` directory contains prompts that can be used with AI coding assistants for various development tasks.
@@ -61,10 +87,10 @@ The `@prompts/` directory contains prompts that can be used with AI coding assis
 ### Contributing
 
 1. Fork the repository
-2. Create a feature branch
+2. Create a feature branch following the branch naming conventions
-3. Commit your changes
+3. Commit your changes with conventional commit messages
 4. Push to the branch
-5. Create a Pull Request
+5. Create a Pull Request with detailed description
 
 ## License
 

docs/project-summary.md

@@ -49,7 +49,10 @@ This document provides a summary of the MEV bot project structure and components
 │   │   └── scanner.go
 │   └── uniswap/
 │       └── pricing.go
-├── QWEN.md                   # Qwen Code context file
+├── CLAUDE.md                 # Complete project documentation and Claude context (comprehensive example)
+├── GEMINI.md                 # Gemini context (simplified, references CLAUDE.md)
+├── OPENCODE.md               # OpenCode context (simplified, references CLAUDE.md)
+├── QWEN.md                   # Qwen Code context (simplified, references CLAUDE.md)
 ├── README.md                 # Project overview
 └── scripts/                  # Scripts for building, testing, and deployment
     ├── build.sh
@@ -100,4 +103,4 @@ This document provides a summary of the MEV bot project structure and components
 
 ## Development
 
-Use the prompts in the `@prompts/` directory with your AI coding assistant for help with specific aspects of the project.
+Use the prompts in the `@prompts/` directory with your AI coding assistant for help with specific aspects of the project. For complete documentation, refer to CLAUDE.md which contains the comprehensive project documentation.