shuim/auto-stock
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
739a8a2e5de81bbb84c30ee50e7be5beecc3c67a
auto-stock/CLAUDE.md
shuim 3eb38690fe fix: 자동매매 미작동 근본 원인 4개 수정 
## 버그 수정 요약

### 1. 거래량 필터 오작동 (market_analyzer.py)
- acml_vol(당일 누적량, 장초 2~10만주)을 100만주 기준으로 필터
  → 전 종목이 필터에 걸려 추천 종목 0개
- 수정: 20일 평균 거래량(avg_vol_20) 기준 10만주 미만 필터로 교체

### 2. min_volume_ratio 기본값 1.0 미설정 (recommendations.py)
- get_rule_based_recommendations_realtime()에서 min_volume_ratio 누락
  → 기본값 1.0 적용, 장중 acml_vol/avg_vol_20≈0.1 → 전 종목 None 반환
- 수정: min_volume_ratio=0 명시 설정

### 3. KRX 호가단위 오류 (korea_investment_api.py)
- 계산된 주문가격이 호가단위(50/100/500/1000원 등) 불일치
  → 모의투자 "호가단위 오류"로 모든 주문 실패
- 수정: _round_to_krx_tick() 헬퍼 추가, 주문 전 올림 처리

### 4. MCP 서버 AI_PROVIDER 미전달 (docker-compose.dev.yml, mcp-server/config.py)
- mcp-server 서비스에 AI_PROVIDER 환경변수 누락 → 항상 Gemini 사용
- Gemini 무료 쿼터 소진 → /analyze 500 에러 → fail-open
- 수정: AI_PROVIDER=${AI_PROVIDER:-claude} 추가
- 수정: load_dotenv(override=True)로 빈 env var 덮어쓰기 허용

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-03-10 13:24:11 +09:00

6.7 KiB
Raw Blame History

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

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

1. 프로젝트 개요

1.1 기술 스택

  • 백엔드: Python 3.11, FastAPI, SQLAlchemy (Async), PostgreSQL, Redis, Rabbitmq
  • 프론트엔드: 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) < 40, 가격이 볼린저 밴드(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)

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

8.2 응답 형식 (Response Format)

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

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

Reference in New Issue View Git Blame Copy Permalink