# CLAUDE.md

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

## Project Overview

This is a quantitative trading strategies repository focused on JoinQuant platform implementations. The codebase contains trading strategies across multiple asset classes including options, futures, ETFs, and stocks, primarily for the Chinese A-share market.

## Architecture & Structure

### High-Level Organization
- **API/**: Documentation and resources for JoinQuant API usage
- **Lib/**: Core strategy implementations organized by asset class
  - **Options/**: Options trading strategies (bull spreads, covered calls, straddles, collars)
  - **Fund/**: ETF/LOF fund premium/discount strategies
  - **Future/**: Futures trading strategies (trend-following, breakout, mean-reversion)
  - **Stock/**: Equity strategies and stock selection algorithms
  - **Research/**: Data analysis and research notebooks
  - **Utils/**: Utility functions and data processing tools
- **Data/**: Sample data files and datasets
- **Log/**: Strategy execution logs
- **Resources/**: API documentation and external resources

### Key Dependencies
- Python 3.11+
- pandas (data manipulation)
- matplotlib (visualization)
- jqdata (JoinQuant data access)

## Common Development Commands

### Setup & Installation
```bash
# Install dependencies
pip install -r requirements.txt
# or
uv sync

# Run basic strategy test
python quick_test.py
```

### Strategy Development & Testing
```bash
# Run a specific strategy
python Lib/Options/deep_itm_bull_spread_strategy.py

# Analyze strategy performance
python Lib/utils/read_log.py

# Generate research reports
jupyter notebook Lib/research/
```

### Common Operations
- **Strategy Testing**: Use JoinQuant's backtesting framework
- **Data Analysis**: Leverage pandas for financial data processing
- **Visualization**: matplotlib for strategy performance charts
- **Logging**: Built-in logging to /log/ directory

## Strategy Categories

### Options Strategies
- **Bull Spreads**: Deep ITM call spreads with systematic roll-over
- **Covered Calls**: ETF-based covered call strategies with dynamic adjustment
- **Straddles/Strangles**: Volatility-based strategies for range-bound markets
- **Collar Strategies**: Downside protection with upside cap
- **Calendar Spreads**: Time decay arbitrage strategies

### Fund Strategies
- **Premium/Discount Arbitrage**: ETF/LOF fund discount strategies with dynamic position sizing
- **Momentum Rotation**: ETF momentum-based sector rotation
- **Grid Trading**: Systematic grid-based trading on fund premiums

### Futures Strategies
- **Trend Breakout**: Multi-MA crossover and breakout systems
- **Spider Web**: Futures positioning-based sentiment analysis
- **K-line Pattern**: Candlestick pattern recognition with trend filtering
- **Mean Reversion**: Counter-trend strategies with strict risk controls

### Risk Management Framework
- **Dynamic Position Sizing**: Position sizing based on volatility and market conditions
- **Multi-level Stop Loss**: Individual position and portfolio-level stops
- **Holiday Risk Management**: Automatic position reduction before holidays
- **Market State Filtering**: Adaptive strategies based on market regime detection

## Key Code Patterns

### Strategy Structure
Most strategies follow this pattern:
1. **Initialize**: Set up parameters, universe, and global variables
2. **Signal Generation**: Technical analysis or fundamental filtering
3. **Position Management**: Dynamic sizing and risk controls
4. **Execution**: Order management with slippage and cost considerations
5. **Monitoring**: Real-time P&L tracking and risk alerts

### Common Parameters
- `g.max_position`: Maximum number of positions
- `g.loss_limit`: Stop loss threshold (typically 10%)
- `g.proportion_cash`: Cash reserve for drawdowns
- `g.holiday`: Holiday calendar for risk management

### Data Sources
- **JoinQuant API**: Real-time and historical market data
- **Fundamental Data**: Financial statements and company metrics
- **Options Data**: Greeks, implied volatility, and option chains
- **Futures Data**: Positioning data, volume, and open interest

## File Naming Conventions
- Strategy files use descriptive names: `asset_class_strategy_type.py`
- Research notebooks: `analysis_*.ipynb`
- Test files: `test_*.py` or `*_test.py`
- Log files: `strategy_name_YYYYMMDD.log`

## Development Guidelines

### Strategy Implementation
1. Use JoinQuant's API functions (`get_price`, `order_target_value`, etc.)
2. Implement proper error handling for API failures
3. Include detailed logging for strategy execution
4. Follow the existing parameter naming conventions

### Testing Approach
- Backtest using JoinQuant's framework
- Validate with out-of-sample data
- Check edge cases (holidays, limit moves, etc.)
- Monitor transaction costs and slippage impact

### Code Organization
- Group related strategies in appropriate directories
- Use consistent parameter naming across strategies
- Implement shared utilities in `/Lib/utils/`
- Document strategies in corresponding README.md files

## Quick Start for New Strategies

1. **Choose Strategy Type**: Options/Futures/Fund/Stock
2. **Create File**: Follow naming convention in appropriate directory
3. **Implement Framework**: Use existing strategy templates
4. **Test Locally**: Use `quick_test.py` for basic validation
5. **Backtest**: Upload to JoinQuant for full backtesting
6. **Document**: Add description to relevant README.md

## Important Notes
- All strategies assume JoinQuant platform API availability
- Some strategies may have hardcoded parameters for Chinese markets
- Transaction costs and slippage assumptions vary by strategy
- Holiday schedules follow Chinese market calendar