auto_trader CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

프로젝트 개요

AI 기반 자동 거래 분석 시스템으로, 다양한 금융 데이터를 수집하고 out-of-process MCP consumer(claude 세션 등)를 통해 투자 분석을 제공합니다.

주요 특징:

• 다중 시장 지원: 국내주식(KIS), 해외주식(KIS/Yahoo Finance), 암호화폐(Upbit)
• 다중 시간대 분석: 일봉 200개 + 분봉(60분/5분/1분)
• AI 분석: out-of-process MCP consumer(claude 세션 등)가 담당 (런타임은 in-process LLM provider 미탑재 — ROB-501 가드)

개발 환경 설정

필수 요구사항

• Python 3.13+
• UV (의존성 관리)
• PostgreSQL (데이터베이스)
• Redis (모델 제한 관리 및 캐싱)

초기 설정

# UV 설치 (미설치 시)
pip install uv

# 의존성 설치
uv sync                           # 프로덕션 의존성만
uv sync --all-groups              # 모든 의존성 (test, dev 포함)

# 환경 변수 설정
cp env.example .env
# .env 파일 편집하여 API 키 설정

# 데이터베이스 마이그레이션
uv run alembic upgrade head

# 개발 서버 실행
make dev                          # 또는 uv run uvicorn app.main:app --reload

Docker 환경

docker compose up -d              # PostgreSQL, Redis, Adminer 시작
docker compose ps                 # 서비스 상태 확인
docker compose down               # 서비스 중지

핵심 명령어

테스트

make test                         # 모든 테스트 실행
make test-unit                    # 단위 테스트만
make test-integration             # 통합 테스트만
make test-cov                     # 커버리지 리포트 포함
uv run pytest tests/test_*.py -v -k "test_name"  # 특정 테스트만

코드 품질

make lint                         # Ruff + ty 검사
make format                       # Ruff로 코드 포맷팅
make typecheck                    # ty 타입 체킹
make security                     # bandit, safety 보안 검사

데이터베이스

# 마이그레이션 생성 및 적용
uv run alembic revision --autogenerate -m "migration message"
uv run alembic upgrade head

# 마이그레이션 롤백
uv run alembic downgrade -1

# 현재 버전 확인
uv run alembic current

개발 도구

python manage_users.py list                 # 사용자 권한/상태 확인
python websocket_monitor.py --mode both     # 통합 WebSocket 모니터링
python kis_websocket_monitor.py             # KIS WebSocket 모니터링
python upbit_websocket_monitor.py           # Upbit WebSocket 모니터링