# 자동 주식 매매 시스템 — 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*