shuim/auto-stock

Files

shuim 3e19862c02 DB삭제 되는부분 처리

2026-02-24 15:58:43 +09:00

6.7 KiB

Raw Blame History

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

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

1. 프로젝트 개요

1.1 기술 스택

백엔드: Python 3.11, FastAPI, SQLAlchemy (Async), PostgreSQL, Redis
프론트엔드: React, TypeScript, Vite, Recharts
인프라: Docker Compose, Nginx
AI 계층: Claude 3.5 Sonnet / Gemini 2.0 Flash (.env에서 전환)
연동 (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일치로 제한함)

2. 디렉토리 구조

2.1 백엔드 (`backend/app/`)

API: api/endpoints/ (시장 데이터, 포트폴리오, 매매)
코어 (Core): market_data.py, portfolio.py, trades.py

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

전략 (Strategies): mean_reversion_strategy.py (v2), short_term_strategy.py, kosdaq_scanner.py
분석 (Analysis): feature_engineering.py, ml_ensemble.py, tensorflow_predictor.py
리스크 및 유틸 (Risk & Utils): risk_management.py, loss_tracker.py, mdd_manager.py
아키텍처 (Architecture): db_worker.py (비동기 DB 처리 워커)

2.3 MCP (`mcp-server/`)

stdio_server.py, auto_trade_claude.py, trade_monitor.py

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

3.1 관심사 분리 (Separation of Concerns)

실시간 계층 (Real-time Layer): API 콜백, 웹소켓 브로드캐스트 및 메모리 캐싱을 처리합니다. DB I/O(데이터베이스 입출력)는 절대 허용되지 않습니다.
영속성 계층 (Persistence Layer): 백그라운드 워커를 통해 DB INSERT/UPDATE 작업을 처리합니다.

3.2 비동기 DB 워커 규칙

직접적인 DB 접근 금지: API 콜백이나 실시간 스케줄러 내부에서 AsyncSessionLocal() 또는 commit()을 절대 호출하지 마십시오.
큐(Queue) 사용: 모든 데이터 저장(매매 내역, 분석 결과 등)은 db_worker.py의 db_task_queue로 보내야 합니다.
워커 (Worker): 백그라운드 워커가 큐를 처리하고 안전한 DB 트랜잭션을 순차적으로 수행합니다.

4. 코딩 가이드라인

4.1 안정성

기존 코드 파괴 금지 (No Breaking Changes): 기존 함수나 클래스의 시그니처를 절대 변경하지 마십시오.
버전 관리: 새로운 전략 구현 시 _v2, _v3 등의 접미사를 사용하십시오.

4.2 최적화

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

5. 리스크 관리 규칙

5.1 포지션 사이징 (Position Sizing)

최대 비중: 종목당 총 자본의 3~4%.
최대 보유 종목 수: 20~25개 종목.
레버리지: 인버스/레버리지 ETF의 경우 총 자본의 최대 20%로 제한.

5.2 손절(SL) 및 익절(TP)

기본 손절 (SL Base): -6% (안정적 종목), -10% (변동성 종목).
ATR 손절: 진입가 - (2.5 * ATR). (기본 손절보다 우선 적용)
익절 (TP): +2R 수익(리스크 대비 2배 수익) 도달 시 50% 분할 매도.
트레일링 스탑 (Trailing Stop): 나머지 50% 물량에 대해 고점 - (1.5 * ATR) 적용.

5.3 MDD(최대 낙폭) 관리

MDD -10%: 신규 진입을 중단합니다. 포지션 규모를 30% 축소합니다. 단기 매매 전략(Short-term Strategy)을 중단합니다.
MDD -20%: 모든 포지션을 강제로 50% 축소합니다. 레버리지 자산부터 우선 청산합니다.

5.4 필터 (Filters)

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

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

6.1 시장 국면 (일봉 기준)

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

6.2 진입 조건

상승장: RSI(14) < 25, 가격이 볼린저 밴드(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 청산 조건

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

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

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

대상 (Scope): 코스닥 전 종목 (약 1,600개).
필터 (Filter): 가격 > 5,000원, 거래량 상위 20%.
점수 (Score): 0.5*RSI + 0.3*BB + 0.2*Vol. 상위 20개 종목 선정.
자산 배분 (Allocation): 전체 자본의 25%.

7.2 단기 전략 (15분봉)

타겟 (Target): 일봉 RSI < 40 인 종목.
진입 (Entry): 15분봉 RSI < 30, 가격이 볼린저 밴드 하단 부근, 5MA 상향 돌파, 거래량 > 1.3배 증가.
청산 (Exit): 15분봉 RSI > 55 OR 수익 > 1.5 * ATR(15분봉).
자산 배분 (Allocation): 전체 자본의 최대 25%. MDD가 -10% 미만이면 비활성화합니다.

8. Claude에 대한 지침

8.1 주요 점검 사항 (Critical Checkpoints)

아키텍처: 모든 DB 쓰기 작업이 db_worker.py를 사용하는지 확인하십시오.
안전성 (Safety): 모든 매매에 리스크 규칙(섹션 5)을 항상 적용하십시오.
시장 국면 (Regime): 횡보장(SIDEWAYS) 국면에서는 진입을 제안하지 마십시오.
테스트: 백테스트 및 전진 분석(Walk-forward validation) 없이는 실전 투자를 하지 마십시오.

8.2 응답 형식 (Response Format)

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

마지막 업데이트: 2026-02-24