404 lines
13 KiB
Markdown
404 lines
13 KiB
Markdown
# Auto Stock Trading System - 전략 가이드 (Claude.md)
|
||
|
||
> 이 파일은 Claude AI가 자동매매 시스템의 전략과 규칙을 이해하기 위한 컨텍스트 문서입니다.
|
||
> 코드 수정, 전략 분석, 백테스트 요청 시 이 파일을 기준으로 판단하세요.
|
||
|
||
---
|
||
|
||
## 1. 프로젝트 개요
|
||
|
||
한국/미국 주식 자동매매 시스템 (풀스택)
|
||
- 한국투자증권 API 연동 (모의/실전 전환 가능)
|
||
- AI(Claude/Gemini) 기반 시장 분석 및 매매 판단
|
||
- MCP(Model Context Protocol) 서버로 Claude CLI 연동
|
||
- 실시간 WebSocket 시세 + React 대시보드
|
||
|
||
---
|
||
|
||
## 2. 기술 스택
|
||
|
||
| 계층 | 기술 |
|
||
|------|------|
|
||
| Backend | Python 3.11, FastAPI, SQLAlchemy (async), PostgreSQL, Redis |
|
||
| Frontend | React + TypeScript, Vite, Recharts |
|
||
| MCP Server | Python, Anthropic SDK, MCP Protocol (stdio) |
|
||
| AI | Claude 3.5 Sonnet / Gemini 2.0 Flash (`.env`에서 전환) |
|
||
| Infra | Docker Compose, Nginx |
|
||
|
||
---
|
||
|
||
## 3. 디렉터리 구조
|
||
|
||
```
|
||
auto-stock/
|
||
├── backend/
|
||
│ ├── app/
|
||
│ │ ├── api/endpoints/
|
||
│ │ │ ├── market_data.py # 시세 조회
|
||
│ │ │ ├── portfolio.py # 포트폴리오 + ATR 기반 청산
|
||
│ │ │ ├── trades.py # 주문/체결
|
||
│ │ │ ├── recommendations.py # 규칙 기반 추천 + 자동매매
|
||
│ │ │ ├── trading_rules.py # 매매 규칙 CRUD
|
||
│ │ │ ├── risk_management.py # 리스크 관리
|
||
│ │ │ ├── ml_ensemble.py # ML 앙상블 엔드포인트
|
||
│ │ │ ├── tensorflow_predictions.py
|
||
│ │ │ ├── debug.py
|
||
│ │ │ └── monitoring.py
|
||
│ │ ├── core/
|
||
│ │ │ ├── config.py # 백엔드 설정 (매매 규칙 파라미터)
|
||
│ │ │ ├── database.py
|
||
│ │ │ ├── json_helpers.py # _dumps() 공용 헬퍼
|
||
│ │ │ └── market_schedule.py # 장 운영시간
|
||
│ │ ├── services/
|
||
│ │ │ ├── korea_investment_api.py
|
||
│ │ │ ├── websocket_manager.py
|
||
│ │ │ ├── mean_reversion_strategy.py # RSI+볼린저 평균회귀 (v2)
|
||
│ │ │ ├── kosdaq_scanner.py # 코스닥 전종목 스캐너 (신규)
|
||
│ │ │ ├── short_term_strategy.py # 15분/60분봉 단기 전략 (신규)
|
||
│ │ │ ├── mdd_manager.py
|
||
│ │ │ ├── loss_tracker.py
|
||
│ │ │ ├── feature_engineering.py
|
||
│ │ │ ├── ml_ensemble.py
|
||
│ │ │ └── tensorflow_predictor.py
|
||
│ │ ├── models/models.py
|
||
│ │ └── main.py
|
||
│ ├── batch_daily_analysis.py
|
||
│ ├── trading_rules_config.json
|
||
│ └── migrations/
|
||
├── frontend/
|
||
│ └── src/
|
||
│ ├── pages/
|
||
│ ├── components/
|
||
│ ├── hooks/
|
||
│ ├── lib/
|
||
│ └── utils/
|
||
├── mcp-server/
|
||
│ ├── config.py
|
||
│ ├── claude_client.py
|
||
│ ├── mcp_tools.py
|
||
│ ├── stdio_server.py
|
||
│ ├── main.py
|
||
│ ├── utils.py
|
||
│ ├── auto_trade_claude.py
|
||
│ └── trade_monitor.py
|
||
├── docker/
|
||
│ └── init-db.sql
|
||
├── docs/
|
||
├── tests/
|
||
├── scripts/
|
||
├── docker-compose.yml
|
||
├── docker-compose.dev.yml
|
||
└── .env
|
||
```
|
||
|
||
---
|
||
|
||
## 4. 환경 설정 (.env)
|
||
|
||
```env
|
||
# AI Provider 전환
|
||
AI_PROVIDER=gemini # gemini | claude
|
||
|
||
# 토큰 절약 설정
|
||
TOKEN_SAVE_MODE=true
|
||
NEWS_LIMIT=3
|
||
CHART_DAYS=30
|
||
JSON_COMPACT=true
|
||
CLAUDE_MAX_TOKENS=1024
|
||
CLAUDE_TEMPERATURE=0.3
|
||
|
||
# 증권 API 모드
|
||
KIS_MODE=virtual # virtual | real
|
||
|
||
# 스캐너 설정 (신규)
|
||
SCANNER_MARKET=KOSDAQ # KOSDAQ | KOSPI | ALL
|
||
SCANNER_INTERVAL=15 # 스캔 주기 (분)
|
||
SHORT_TERM_CAPITAL_RATIO=0.25 # 단기전략 자본 비율 (최대 25%)
|
||
```
|
||
|
||
---
|
||
|
||
## 5. 코딩 규칙
|
||
|
||
- 기존 함수/클래스 시그니처 유지, 작은 단위 변경 우선
|
||
- 새 전략은 별도 파일/클래스로 추가 (`_v2`, `_v3`)
|
||
- AI 프롬프트는 간결하게 (필수 필드만 명시, JSON 예시 최소화)
|
||
- `json.dumps`는 `_dumps()` 헬퍼 사용 (토큰 절약 모드 자동 적용)
|
||
- `.env` 파일은 커밋하지 않음 (API 키 포함)
|
||
|
||
---
|
||
|
||
## 6. 포지션 및 리스크 규칙
|
||
|
||
### 6.1 포지션 규칙
|
||
- 1종목당 최대 **3~4%** 자본 사용
|
||
- 동시 보유 종목 수: 기본 최대 **20종목**, 전략에 따라 최대 25종목
|
||
- 레버리지/인버스 ETF: 전체 자본의 **20% 이내**
|
||
|
||
### 6.2 손절 및 청산 규칙
|
||
- 기본 손절:
|
||
- 저변동 종목/ETF(대형주): **-6%**
|
||
- 고변동 종목(테마·코스닥): **-10%**
|
||
- ATR 기반 손절 (우선 적용):
|
||
- 손절가 = 진입가 - **2.5 × ATR**
|
||
- 변동성 크면 손절폭 자동 확대, 줄면 축소
|
||
- 익절/트레일링:
|
||
- 2R 이상 수익 시 절반 익절 + 나머지 트레일링 스탑 (**1.5 × ATR**)
|
||
|
||
### 6.3 포트폴리오 MDD 관리
|
||
- MDD **-10%** 돌파 시:
|
||
- 신규 진입 일시 중단
|
||
- 기존 포지션 크기 **30% 축소**
|
||
- MDD **-20%** 돌파 시:
|
||
- 전체 포지션 **50% 강제 축소**
|
||
- 레버리지/인버스 포지션 우선 청산
|
||
|
||
### 6.4 가격 필터 (저가주 제한)
|
||
- 국내: **5,000원 이하** 매수 금지
|
||
- 단, ETF·리츠·우량 대형 공모주는 화이트리스트로 허용
|
||
- 미국: **4달러 이하** 매수 금지
|
||
- ETF·리츠 화이트리스트 예외 가능
|
||
|
||
### 6.5 시간 프레임 운용
|
||
- 기본: **일봉(Daily) + 60분봉(H1)**
|
||
- 단기(인트라데이): **15분/60분봉** → 전체 자본의 **최대 20~25%** 이내
|
||
- 슬리피지·수수료 포함 백테스트 필수
|
||
|
||
### 6.6 섹터 상관관계 필터
|
||
- 동일 섹터 최대 **3종목** 제한
|
||
- 기존 보유 종목과 상관계수 **0.7 이상** 시 진입 제한
|
||
- correlation_matrix: 주간 업데이트 → Redis 캐싱
|
||
|
||
---
|
||
|
||
## 7. RSI + 볼린저 평균회귀 전략 v2 (개선형)
|
||
|
||
### 7.1 시장 Regime 판단 (3분류)
|
||
|
||
```python
|
||
slope_200 = (ma200_today - ma200_20days_ago) / 20 # 기울기
|
||
adx = talib.ADX(high, low, close, 14)[-1]
|
||
|
||
if close > ma200 and slope_200 > 0 and adx > 20:
|
||
regime = MarketRegime.BULL # 추세 상승장
|
||
elif close < ma200 and slope_200 < 0 and adx > 20:
|
||
regime = MarketRegime.BEAR # 추세 하락장
|
||
else:
|
||
regime = MarketRegime.SIDEWAYS # 박스권 (신규 진입 금지)
|
||
```
|
||
|
||
> **판별 기준**: 코스피200 지수 기준 / 매일 장 마감 후 업데이트
|
||
> **SIDEWAYS**: ADX < 20 또는 200MA 횡보(기울기 ≈ 0) → 진입 금지
|
||
|
||
---
|
||
|
||
### 7.2 매수 조건
|
||
|
||
#### 공통 전제조건
|
||
- 가격: 국내 5,000원 이상 / 미국 4달러 이상
|
||
- 유동성: 최근 20일 평균 거래대금 상위 20% 이내
|
||
|
||
---
|
||
|
||
#### 상승장(BULL) 매수 조건
|
||
|
||
```python
|
||
rsi_ok = rsi14 <= 25
|
||
pct = (close - bb_lower) / bb_lower * 100
|
||
bb_ok = -3.0 <= pct <= 1.5
|
||
volume_ok = volume > volume_ma20 * 0.8
|
||
candle_ok = close > open or close > prev_low * 1.005
|
||
|
||
bull_signal = rsi_ok and bb_ok and volume_ok and candle_ok
|
||
# → 2회 분할 매수 (50% + 50%)
|
||
```
|
||
|
||
---
|
||
|
||
#### 하락장(BEAR) 매수 조건
|
||
|
||
```python
|
||
rsi_ok = rsi14 <= 30
|
||
bb_ok = close <= bb_lower * 1.01
|
||
volume_surge = volume > volume_ma20 * 1.5
|
||
rebound_ok = close > prev_close or close > h1_prev_high
|
||
|
||
bear_signal = rsi_ok and bb_ok and volume_surge and rebound_ok
|
||
# → 3회 분할 매수 (단, 2일 연속 과매도면 2회로 축소)
|
||
```
|
||
|
||
---
|
||
|
||
#### 복합 타임프레임 선취매 (선택)
|
||
- 일봉 RSI ≤ 40 관심 종목 중, 60분봉 RSI ≤ 30 신호 발생 시 선취매
|
||
- 60분봉 필터: 5일 이동평균선 상향 돌파 동시 확인 (Fake-out 방지)
|
||
- 비중: 전체 자본의 **10% 이내**
|
||
|
||
---
|
||
|
||
### 7.3 청산 조건
|
||
|
||
#### 1차 익절
|
||
```python
|
||
first_exit = (
|
||
rsi14 >= 50
|
||
or close >= bb_mid
|
||
or profit_pct >= 2 * atr_pct
|
||
)
|
||
# BULL: 40% 익절 / BEAR: 60% 익절
|
||
```
|
||
|
||
#### 2차 익절 (전량 청산)
|
||
```python
|
||
trailing_stop = max_close_after_entry - 1.5 * atr
|
||
|
||
second_exit = (
|
||
close <= trailing_stop # ATR 트레일링 (최우선)
|
||
or rsi14 >= 65
|
||
or close >= bb_upper * 0.99
|
||
)
|
||
```
|
||
|
||
---
|
||
|
||
### 7.4 손절 및 추가 진입 제한
|
||
|
||
```python
|
||
stop_loss_atr = entry_price - 2.5 * atr
|
||
stop_loss_pct = entry_price * 0.92 # -8%
|
||
stop_triggered = close <= min(stop_loss_atr, stop_loss_pct)
|
||
|
||
# 연속 손실 제한
|
||
if consecutive_losses >= 3:
|
||
block_entry_days = 30
|
||
```
|
||
|
||
---
|
||
|
||
### 7.5 시장 상태별 자본 배분
|
||
|
||
| Regime | 전략 운용 비중 | 특징 |
|
||
|-----------|----------------|----------------------|
|
||
| BULL | **최대 70%** | 공격적, 모멘텀 최대 활용 |
|
||
| SIDEWAYS | **진입 금지** | 가짜 신호 차단 |
|
||
| BEAR | **최대 30%** | 보수적, 자본 보호 우선 |
|
||
|
||
---
|
||
|
||
## 8. 공격적 전략 (월 5% 목표)
|
||
|
||
> **목표**: 1천만원 → 1억원 (4년 순수 복리 / 현실 7~8년)
|
||
> **핵심**: 단일 종목 대기 → 코스닥 전종목 스캔 + 단기봉 병행으로 신호 빈도 ↑
|
||
|
||
### 8.1 코스닥 전종목 스캐너 (`kosdaq_scanner.py`)
|
||
|
||
```python
|
||
# 매일 장 마감 후 코스닥 전종목 스캔 → 조건 충족 종목 우선순위 큐에 저장
|
||
class KosdaqScanner:
|
||
def scan_all(self) -> list[ScanResult]:
|
||
candidates = []
|
||
for ticker in kosdaq_all_tickers: # ~1,600종목
|
||
if not self._price_filter(ticker): # 5,000원 이상
|
||
continue
|
||
if not self._liquidity_filter(ticker): # 거래대금 상위 20%
|
||
continue
|
||
score = self._score(ticker) # RSI + BB + 거래량 복합 점수
|
||
candidates.append(ScanResult(ticker, score))
|
||
return sorted(candidates, key=lambda x: x.score, reverse=True)[:20]
|
||
|
||
def _score(self, ticker) -> float:
|
||
rsi_score = max(0, (25 - rsi14) / 25) # RSI 낮을수록 ↑
|
||
bb_score = max(0, (0 - pct_vs_lower) / 3) # BB 하단 근접 ↑
|
||
volume_score = min(volume / volume_ma20, 2.0) # 거래량 급증 ↑
|
||
return rsi_score * 0.5 + bb_score * 0.3 + volume_score * 0.2
|
||
```
|
||
|
||
> **기대 효과**: 단일 종목 대기 연 2~4회 → 전종목 스캔으로 월 5~10개 신호 확보
|
||
|
||
---
|
||
|
||
### 8.2 15분봉 단기 전략 (`short_term_strategy.py`)
|
||
|
||
```python
|
||
class ShortTermStrategy:
|
||
MAX_CAPITAL_RATIO = 0.25 # 전체 자본의 최대 25%
|
||
TIMEFRAME = "15m"
|
||
|
||
def entry_signal(self, ticker) -> bool:
|
||
# 일봉 RSI ≤ 40 관심 종목 중에서만 적용
|
||
if daily_rsi > 40:
|
||
return False
|
||
# 15분봉 조건
|
||
rsi_15m = self._rsi(ticker, "15m", 14)
|
||
bb_lower = self._bb_lower(ticker, "15m", 20)
|
||
ma5 = self._ma(ticker, "15m", 5)
|
||
return (
|
||
rsi_15m <= 30
|
||
and close <= bb_lower * 1.01
|
||
and close > ma5 # 5분봉 MA5 상향 돌파 (Fake-out 방지)
|
||
and volume > volume_ma * 1.3
|
||
)
|
||
|
||
def exit_signal(self, position) -> bool:
|
||
rsi_15m = self._rsi(position.ticker, "15m", 14)
|
||
return rsi_15m >= 55 or profit_pct >= 1.5 * atr_15m_pct
|
||
```
|
||
|
||
> **슬리피지 주의**: 15분봉 전략은 반드시 수수료 0.3% + 슬리피지 0.2% 포함 백테스트 필수
|
||
|
||
---
|
||
|
||
### 8.3 멀티 전략 자본 배분
|
||
|
||
| 전략 | 자본 비율 | 기대 월 수익 | 신호 빈도 |
|
||
|------|-----------|-------------|-----------|
|
||
| RSI+볼린저 일봉 (v2) | 50% | +2~3% | 월 3~5회 |
|
||
| 코스닥 스캐너 | 25% | +1~2% | 월 5~10회 |
|
||
| 15분봉 단기 전략 | 25% | +1~2% | 월 10~20회 |
|
||
| **합계 기대치** | **100%** | **+4~7%** | - |
|
||
|
||
> 세 전략 동시 운용 시 월 5% 달성 현실 가능
|
||
> MDD -10% 돌파 시 단기 전략 즉시 중단, 일봉 전략만 유지
|
||
|
||
---
|
||
|
||
### 8.4 수익 목표 시뮬레이션 (복리)
|
||
|
||
| 이정표 | 순수 복리 (월 5%) | 현실 예상 (MDD 포함) |
|
||
|--------|------------------|---------------------|
|
||
| 2,000만 | 15개월 (1.2년) | 20~24개월 |
|
||
| 3,000만 | 23개월 (1.9년) | 30~36개월 |
|
||
| 5,000만 | 33개월 (2.8년) | 45~54개월 |
|
||
| **1억** | **48개월 (4.0년)** | **7~8년** |
|
||
|
||
> 10년 내 1억 달성 확률 (몬테카를로 1,000회): **82.5%**
|
||
|
||
---
|
||
|
||
## 9. 주요 포트 (개발 환경)
|
||
|
||
| 서비스 | 포트 |
|
||
|--------|------|
|
||
| Backend (FastAPI) | 8000 |
|
||
| MCP Server | 8001 |
|
||
| Frontend (Vite) | 5173 |
|
||
| PostgreSQL | 5432 (Docker: 55432) |
|
||
| Redis | 6379 |
|
||
|
||
---
|
||
|
||
## 10. Claude에게 요청 시 주의사항
|
||
|
||
1. **기존 코드 시그니처 변경 금지** → 새 기능은 `_v2`, `_v3` 파일로 분리
|
||
2. **백테스트 없이 실전 코드 즉시 적용 금지** → 워크포워드 테스트 필수
|
||
3. **`json.dumps` 직접 사용 금지** → 반드시 `_dumps()` 헬퍼 사용
|
||
4. **리스크 규칙(포지션 크기, 손절, MDD, 가격 필터)** 은 모든 전략에 기본 적용
|
||
5. **SIDEWAYS 구간** 에서는 평균회귀 전략 신호 발생 시 무시
|
||
6. **15분봉 단기 전략** 은 전체 자본의 25% 초과 불가
|
||
7. **MDD -10%** 돌파 시 단기 전략 즉시 중단, 일봉 전략만 유지
|
||
8. **코스닥 스캐너** 는 가격 5,000원 이상 + 거래대금 상위 20% 필터 반드시 적용
|
||
|
||
---
|
||
|
||
*Last updated: 2026-02-22*
|