# 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*