13 KiB
13 KiB
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)
# 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분류)
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) 매수 조건
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) 매수 조건
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차 익절
first_exit = (
rsi14 >= 50
or close >= bb_mid
or profit_pct >= 2 * atr_pct
)
# BULL: 40% 익절 / BEAR: 60% 익절
2차 익절 (전량 청산)
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 손절 및 추가 진입 제한
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)
# 매일 장 마감 후 코스닥 전종목 스캔 → 조건 충족 종목 우선순위 큐에 저장
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회 → 전종목 스캔으로 월 510개 신호 확보
8.2 15분봉 단기 전략 (short_term_strategy.py)
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에게 요청 시 주의사항
- 기존 코드 시그니처 변경 금지 → 새 기능은
_v2,_v3파일로 분리 - 백테스트 없이 실전 코드 즉시 적용 금지 → 워크포워드 테스트 필수
json.dumps직접 사용 금지 → 반드시_dumps()헬퍼 사용- 리스크 규칙(포지션 크기, 손절, MDD, 가격 필터) 은 모든 전략에 기본 적용
- SIDEWAYS 구간 에서는 평균회귀 전략 신호 발생 시 무시
- 15분봉 단기 전략 은 전체 자본의 25% 초과 불가
- MDD -10% 돌파 시 단기 전략 즉시 중단, 일봉 전략만 유지
- 코스닥 스캐너 는 가격 5,000원 이상 + 거래대금 상위 20% 필터 반드시 적용
Last updated: 2026-02-22