auto-stock/CLAUDE.md

자동 주식 매매 시스템 — Claude 컨텍스트 가이드

핵심 지침 (Core Directive): 이 문서는 시스템의 전략, 규칙 및 아키텍처를 정의합니다. 모든 코드 수정 및 분석은 이 가이드라인을 엄격하게 준수해야 합니다.

---

1. 프로젝트 개요

1.1 기술 스택

• 백엔드: Python 3.11, FastAPI, SQLAlchemy 2.0 (Async), PostgreSQL 15, Redis 7, RabbitMQ 3
• 프론트엔드: React 18, TypeScript, Vite, Recharts, Lightweight Charts
• 인프라: Docker Compose, Nginx, Alembic (DB 마이그레이션)
• AI 계층: Claude 3.5 Sonnet / Gemini 2.0 Flash (.env의 AI_PROVIDER로 전환)
• ML: PyTorch, LightGBM, scikit-learn (앙상블 예측)
• 연동 (Integration): 한국투자증권(KIS) REST/WebSocket API, MCP Server (stdio)

1.2 주요 환경 변수 (.env)

• AI_PROVIDER: gemini 또는 claude
• KIS_MODE: virtual (모의투자) 또는 real (실전투자)
• TOKEN_SAVE_MODE: true (JSON을 압축하고, 차트 데이터를 30일치로 제한함)
• AUTO_TRADE_ENABLED: 자동 매매 활성화 여부
• US_TRADING_ENABLED: 미국 주식 매매 활성화 여부

---

2. 디렉토리 구조

2.1 백엔드 (backend/app/)

• API: api/endpoints/ — 20개 엔드포인트 모듈 (portfolio, market_data, trades, day_trading, backtest 등)
• 코어 (Core): core/config.py (전역 설정), core/database.py, core/security.py (API 키 인증), core/json_helpers.py, core/market_schedule.py
• 모델 (Models): models/models.py — SQLAlchemy ORM (Portfolio, TradeHistory, ActiveTrade, StockAnalysis, StockBan 등)
• 실시간 (Realtime): realtime/websocket_client.py, realtime/event_handler.py
• 전략 추상화 (Strategy): strategy/base_strategy.py, strategy/strategy_manager.py

2.2 서비스 (backend/app/services/)

• 전략 (Strategies):
  • mean_reversion_strategy.py — RSI+BB 평균 회귀 v2 (섹션 6)
  • short_term_strategy.py — 15분봉 단기 전략 (섹션 7.2)
  • day_trading_strategy.py — 5분봉 데이트레이딩 ORB/VWAP/RSI_BB (섹션 7.3)
  • kosdaq_scanner.py — 코스닥 스윙 스캐너 (섹션 7.1)
  • us_stock_strategy.py — 미국 주식 전략
• 데이트레이딩 모듈 (Modular): daytrading/entry_service.py, daytrading/exit_service.py, daytrading/position_manager.py, daytrading/scheduler.py
• 스윙 모듈 (Modular): swing/entry_service.py, swing/exit_service.py, swing/position_manager.py, swing/scheduler.py
• 매매 실행: trade_executor.py — 핵심 매매 엔진 (매수/매도/체결확인/슬리피지)
• 분석 (Analysis): feature_engineering.py, ml_ensemble.py, tensorflow_predictor.py, technical_indicators.py
• 리스크: mdd_manager.py (MDD 추적 + 자동 축소 실행), loss_tracker.py (연속 손실 ban), correlation_filter.py (상관관계 필터)
• 아키텍처: db_worker.py (비동기 DB 처리 워커, 재시도 3회)
• 데이터: korea_investment_api.py (KIS REST), kis_realtime_stream.py (KIS WebSocket), naver_finance.py
• 유틸: websocket_manager.py, order_dispatcher.py, signal_types.py, watchlist.py

2.3 MCP (mcp-server/)

• stdio_server.py, auto_trade_claude.py, claude_client.py, gemini_client.py, trade_monitor.py, risk_validator.py, mcp_tools.py

2.4 배치 스크립트 (backend/)

• batch_daily_analysis.py — 일일 분석 배치
• batch_intraday_analysis.py — 장중 분석 배치
• train_ensemble.py — ML 모델 학습
• collect_krx_data.py — KRX 데이터 수집

---

3. 아키텍처 원칙 (필수 준수 사항)

3.1 관심사 분리 (Separation of Concerns)

• 실시간 계층 (Real-time Layer): API 콜백, 웹소켓 브로드캐스트 및 메모리 캐싱을 처리합니다. DB I/O(데이터베이스 입출력)는 절대 허용되지 않습니다.
• 영속성 계층 (Persistence Layer): 백그라운드 워커를 통해 DB INSERT/UPDATE 작업을 처리합니다.
• 예외: sync_portfolio()는 SELECT→UPDATE/DELETE→commit이 같은 트랜잭션에서 이뤄져야 하므로 API 엔드포인트 경로에서 직접 DB 접근을 허용합니다.

3.2 비동기 DB 워커 규칙

• 직접적인 DB 접근 금지: API 콜백이나 실시간 스케줄러 내부에서 AsyncSessionLocal() 또는 commit()을 절대 호출하지 마십시오.
• 큐(Queue) 사용: 모든 데이터 저장(매매 내역, 분석 결과 등)은 db_worker.py의 db_task_queue로 보내야 합니다.
• 워커 (Worker): 백그라운드 워커가 큐를 처리하고 안전한 DB 트랜잭션을 순차적으로 수행합니다.
• 재시도: 실패한 task는 최대 3회까지 지수 백오프(1→2→4초)로 재시도합니다.
• 지원 task 타입: insert_trade_history, update_trade_history, update_trade_history_by_order_id, upsert_stock_analysis, bulk_upsert_stock_analysis, upsert_stock_ban, upsert_portfolio, upsert_active_trade, close_active_trade, insert_trade_journal, log_mcp_deny

3.3 동시성 안전

• 종목별 세마포어: trade_executor.py의 _order_semaphores로 동일 종목 동시 주문 방지.
• Redis 분산 락: 여러 워커 프로세스간 동일 종목 동시 매도 방지.
• loss_tracker 락: asyncio.Lock으로 _tracker 딕셔너리 보호. 동시 접근 경로에서는 is_banned_safe(), record_trade_result_safe() 사용.
• MDD 매니저 락: asyncio.Lock으로 MDD 업데이트 및 축소 실행 보호.

---

4. 코딩 가이드라인

4.1 안정성

• 기존 코드 파괴 금지 (No Breaking Changes): 기존 함수나 클래스의 시그니처를 절대 변경하지 마십시오.
• 버전 관리: 새로운 전략 구현 시 _v2, _v3 등의 접미사를 사용하십시오.
• 안전 래퍼: 기존 동기 API를 비동기로 확장할 때 _safe 접미사의 새 메서드를 추가하십시오 (예: is_banned_safe()).

4.2 최적화

• JSON 처리: json.dumps 대신 항상 core.json_helpers._dumps()를 사용하십시오.
• 프롬프트 엔지니어링: 토큰 사용을 최소화하고 컴팩트한 포맷을 사용하십시오.

4.3 보안

• API 인증: 쓰기/삭제 엔드포인트에는 반드시 Depends(require_api_key)를 적용하십시오.
• SSL 검증: 외부 API 호출 시 verify=True 유지 (KIS API 포함).
• 비밀키: .env의 SECRET_KEY는 64자 이상 랜덤 문자열 사용.

---

5. 리스크 관리 규칙

5.1 포지션 사이징 (Position Sizing)

• 최대 비중: 종목당 총 자본의 6% (config.py: MAX_POSITION_SIZE = 0.06, 백테스트 검증 반영).
• 최대 보유 종목 수: 20개 (config.py: MAX_HOLDINGS_COUNT = 20).
• 레버리지: 인버스/레버리지 ETF의 경우 총 자본의 최대 **20%**로 제한 (config.py: LEVERAGE_ETF_MAX_RATIO = 0.20).

5.2 손절(SL) 및 익절(TP) — 일봉/스윙 기준

• 기본 손절 (SL Base): -7% (안정적 종목), -10% (변동성 종목). (백테스트 검증: 기존 -6% → -7%)
• ATR 손절: 진입가 - (2.5 * ATR) (config.py: ATR_STOP_MULTIPLIER = 2.5). 기본 손절과 ATR 손절 중 타이트한(더 작은) 쪽 적용 — 코드에서 min(stop_loss, atr_stop_pct) 사용.
• 익절 (TP): +2R 수익(리스크 대비 2배 수익) 도달 시 50% 분할 매도.
• 트레일링 스탑 (Trailing Stop): 나머지 50% 물량에 대해 고점 - (1.5 * ATR) 적용.

5.3 MDD(최대 낙폭) 관리

• MDD -10%: 신규 진입을 중단합니다. 포지션 규모를 30% 축소합니다. 단기 매매 전략 및 데이트레이딩을 중단합니다. (mdd_manager.py: REDUCE_AND_PAUSE)
• MDD -20%: 모든 포지션을 강제로 50% 축소합니다. 레버리지/인버스 ETF부터 우선 청산합니다. (mdd_manager.py: FORCE_REDUCE)
• 자동 실행: mdd_manager.execute_reduction()이 portfolio.py와 swing/scheduler.py에서 자동 호출됩니다. 중복 실행 방지 플래그가 내장되어 있습니다.
• 복구: 잔고가 peak를 갱신하면 모든 MDD 플래그가 리셋됩니다.

5.4 필터 (Filters)

• 가격: 5,000원 초과 (국내), $4 초과 (미국). (예외: ETF, 리츠). (config.py: MIN_PRICE_KRW = 5000, MIN_PRICE_USD = 4.0)
• 상관관계 (Correlation): 섹터당 최대 3종목 (correlation_filter.py: max_per_sector = 3). 기존 포트폴리오와의 상관계수가 0.7을 초과하면 진입을 거부합니다.

5.5 연속 손실 관리

• 동일 종목에서 3회 연속 손실 시 42캘린더일(≈30거래일) 진입 금지 (loss_tracker.py).
• DB 영속화: save_to_db() → db_worker의 upsert_stock_ban 경유.
• 앱 재시작 시 load_from_db()로 ban 상태 복원.

---

6. 전략 A: RSI + 볼린저 밴드 평균 회귀 v2

구현 파일: mean_reversion_strategy.py, swing/ 모듈 자산 배분: 스윙 포트폴리오 (코스닥 스캐너 25% 외 나머지)

6.1 시장 국면 (일봉 기준)

• 상승장 (BULL): 코스피200 > 200일 이동평균선(MA200) AND MA200 기울기 > 0.
• 하락장 (BEAR): 코스피200 < MA200 AND MA200 기울기 < 0.
• 횡보장 (SIDEWAYS): ADX < 20 OR 기울기 ≈ 0. (이 국면에서는 모든 진입 신호를 무시합니다)
  • market_analyzer.py에서 position_multiplier=0.0, max_trades=0 반환.

6.2 진입 조건

• 상승장: RSI(14) < 40 (기본값, .env에서 MEAN_REVERSION_RSI_THRESHOLD로 조정 가능), 가격이 볼린저 밴드(BB) 하단 부근 (-3% ~ +1.5%), 거래량 > 20일 평균 거래량(20MA).
• 하락장: RSI(14) < 30, 가격 < 볼린저 밴드 하단, 거래량 > 1.5배 × 20MA, 반전 캔들(Reversal candle) 필수.
• 선제 진입 (Pre-emptive): 일봉 RSI < 40 AND 60분봉 RSI < 30 AND 5일 이동평균선(MA5) 상향 돌파.

6.3 청산 조건

• 부분 매도 (50%): RSI >= 50 OR 가격 > 볼린저 밴드 중앙선 OR 수익 > 2×ATR.
• 전량 매도: RSI >= 65 OR 가격 > 볼린저 밴드 상단 (99%) OR 트레일링 스탑 도달 (고점 - 1.5×ATR).

---

7. 전략 B: 공격적 성장 (Aggressive Growth)

7.1 코스닥 스캐너 (스윙 매매)

구현 파일: kosdaq_scanner.py

• 대상 (Scope): 코스닥 전 종목 (약 1,600개).
• 필터 (Filter): 가격 > 5,000원, 거래량 상위 20%.
• 점수 (Score): 0.5×RSI_score + 0.3×BB_score + 0.2×Vol_score. 최소 점수 0.15 이상인 종목 중 상위 20개 선정.
• 자산 배분 (Allocation): 전체 자본의 25%.

7.2 단기 전략 (15분봉)

구현 파일: short_term_strategy.py

• 타겟 (Target): 일봉 RSI < 40 인 종목.
• 진입 (Entry): 15분봉 RSI < 30, 가격이 볼린저 밴드 하단 부근, 종가 > MA5 (상향 돌파 확인), 거래량 > 1.3배 × 20MA (config.py: SHORT_TERM_VOLUME_MULTIPLIER = 1.3).
• 최소 변동성: ATR/close ≥ 0.8% (config.py: SHORT_TERM_MIN_ATR_RATIO = 0.008) — 거래비용 커버 보장.
• 청산 (Exit): 15분봉 RSI > 55 OR 수익 > 1.5 × ATR(15분봉).
• 손절 (SL): 진입가 - 1.0 × ATR(15분봉) 또는 -2% 하드 스탑 중 타이트한(더 높은 stop_price) 쪽 — 코드에서 min(atr_stop, hard_stop) 사용. (15분봉 단기전략 전용 — 섹션 5.2 ATR 2.5×는 일봉/스윙 기준)
• 자산 배분 (Allocation): 전체 자본의 최대 25%. MDD가 -10% 미만이면 비활성화합니다.

7.3 데이트레이딩 (5분봉, ORB/VWAP/RSI_BB)

구현 파일: day_trading_strategy.py, daytrading/ 모듈

전략 3종

전략	진입 조건	손절 기준
ORB	시초가 레인지 돌파 + 거래량 ≥ 1.5× 평균분당거래량 + 직전 5분봉 양봉	max(ORB 저점, 현재가×(1-ORB_SL%)) + ATR 하한, 상한 -2.5% 클램프
VWAP	VWAP 지지 반등 + RSI(14) < 40 + 거래량 ≥ 1.3× + 양봉	min(ATR×1.5 기반, 하드스탑 -2.5%) + 최소 1원 보장
RSI_BB	RSI(14) ≤ 30 + 종가 ≤ BB 하단 + 거래량 ≥ 1.3× + 양봉	min(ATR×1.5 기반, 하드스탑 -2.5%) + 최소 1원 보장

포지션 사이징

• 종목당 최대 4% (섹션 5.1 준수, config.py: DAY_TRADE_MAX_CAPITAL_RATIO = 0.04).
• 동시 최대 3종목 (config.py: DAY_TRADE_MAX_POSITIONS = 3).
• confidence 기반 동적 조정: 예산 × (signal.confidence / 0.7).

자산 배분

• 전체 자본의 최대 25% (config.py: DAY_TRADE_MAX_RATIO_DT = 0.25).

청산 규칙

• 분할 매도: 목표가(+2R) 달성 시 50% 분할 매도, 잔량은 트레일링 스탑(ATR × 1.0) 적용.
• 시간 손절: 진입 후 30분(6봉)간 +0.3% 미달 시 청산 (기회비용 관리).
• 과매수 청산: 5분봉 RSI ≥ 70 AND 수수료 이상 수익 시 청산.
• EOD 강제 청산: 15:20 이후 전량 청산 (config.py: DAY_TRADE_EOD_FLAT_HOUR/MIN).

필터 및 제한

• 시장 국면: SIDEWAYS 국면에서 진입 차단 (섹션 6.1 준수).
• 시간대 제한: 점심시간(11:30~13:00) VWAP/RSI_BB 진입 제한, 14:30 이후 신규 진입 마감.
• 일일 손실 한도: -3% 초과 시 당일 신규 진입 중단 (config.py: DAY_TRADE_DAILY_LOSS_LIMIT = -0.03).
• 쿨다운: 당일 3연패 시 신규 진입 차단 (daytrading/position_manager.py).
• loss_tracker 연동: 전량 매도 시 loss_tracker.record_trade_result() + save_to_db() 호출.
• MDD -10% 미만이면 비활성화합니다.

---

8. Claude에 대한 지침

8.1 주요 점검 사항 (Critical Checkpoints)

1. 아키텍처: 모든 DB 쓰기 작업이 db_worker.py를 사용하는지 확인하십시오. 예외: sync_portfolio().
2. 안전성 (Safety): 모든 매매에 리스크 규칙(섹션 5)을 항상 적용하십시오.
3. 시장 국면 (Regime): 횡보장(SIDEWAYS) 국면에서는 진입을 제안하지 마십시오.
4. 테스트: 백테스트 및 전진 분석(Walk-forward validation) 없이는 실전 투자를 하지 마십시오.
5. 손절 방향: 손절가 선택 시 항상 min() (타이트한 쪽)을 사용하십시오. max()는 절대 사용하지 마십시오.
6. loss_tracker 영속화: record_trade_result() 호출 후 반드시 save_to_db() 호출을 확인하십시오.
7. 인증: 쓰기/삭제 API에는 반드시 require_api_key 의존성을 적용하십시오.

8.2 응답 형식 (Response Format)

• JSON 출력 시 _dumps()를 사용하십시오.
• 새로운 기능 개발 시 새 파일을 생성하십시오.
• 기존 시그니처를 수정하지 마십시오.

8.3 주요 설정값 참조 (config.py) — 백테스트 검증 완료

설정	값	설명	백테스트 변경
MAX_POSITION_SIZE	0.06	종목당 최대 6%	기존 0.04 → 0.06
MAX_HOLDINGS_COUNT	20	동시 보유 최대	유지
LEVERAGE_ETF_MAX_RATIO	0.20	레버리지 ETF 최대	유지
ATR_STOP_MULTIPLIER	2.5	스윙 ATR 손절 배수	유지
STOP_LOSS_PERCENT	7.0	기본 손절 7%	기존 6.0 → 7.0
MEAN_REVERSION_RSI_THRESHOLD	46.0	평균회귀 RSI 임계값	기존 40.0 → 46.0
MEAN_REVERSION_BEAR_RSI_THRESHOLD	35.0	BEAR RSI 임계값	기존 30.0 → 35.0
MEAN_REVERSION_RSI_EXIT_THRESHOLD	55.0	1차 익절 RSI	기존 50.0 → 55.0
MEAN_REVERSION_RSI_FULL_EXIT	70.0	전량 청산 RSI	기존 65.0 → 70.0
DAY_TRADE_MAX_POSITIONS	3	데이트레이딩 동시 최대	유지
DAY_TRADE_ENTRY_CUTOFF	14:30	데이트레이딩 마감	기존 15:00 → 14:30
CONSECUTIVE_LOSS_BAN_COUNT	3	연속 손실 ban 횟수	유지

8.4 듀얼 전략 (백테스트 검증: 2023-03 ~ 2026-03)

스윙 전략은 3가지 진입 전략을 병행합니다:

전략	조건	청산 방식	기여도
평균회귀	RSI 과매도 + BB 하단	RSI 55 부분익절 → RSI 70 전량	베이스 수익
모멘텀 돌파	20일 신고가 + 거래량 2x + RSI 50~70	+10% 30%매도 → +20% 30%매도 → 트레일링	큰 이익
눌림목 매수	MA20>MA60 + MA20 근처 조정 + RSI 반등	평균회귀와 동일	안정 수익

8.5 적응형 모드 (4단계)

시장 상황에 따라 파라미터가 자동 전환됩니다 (adaptive_strategy.py):

모드	RSI 진입	포지션	손절	트리거
Aggressive	50	7%	-9%	ATR백분위<30 + ADX>25 + 5일수익>+2%
Normal	46	6%	-7%	기본
Defensive	38	4%	-6%	ATR백분위>70 또는 5일수익<-3%
Crisis	25	1.5%	-3%	ATR백분위>90 또는 5일수익<-5%

마지막 업데이트: 2026-03-25 (백테스트 검증 반영)