JUKUAN/CLAUDE.md

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

# Install dependencies
pip install -r requirements.txt
# or
uv sync

# Run basic strategy test
python quick_test.py

Strategy Development & Testing

# 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