Stock-trading-programming/CLAUDE.md

StockBot v3.0 — Claude Code 운영 가이드

최종 수정: 2026-05-15 (권한·evening 추가)
인프라: 로컬 개발 → Synology NAS Docker 이전 예정
현재 모드: 모의투자 (KIS_MOCK=true, DRY_RUN=true)

---

프로젝트 개요

항목	내용
목표	KIS API 기반 한국 주식 단타 자동매매
전략	변동성 돌파 (K=0.5)
언어	Python 3.11
DB	SQLite (data/stockbot.db)
알림	Discord Webhook
AI	Claude Code headless
코드 관리	Gitea (NAS) — 수정 후 자동 커밋/push

---

Claude Code 권한

이 프로젝트 폴더 내 모든 Bash/파일 작업은 사용자가 영구 승인한 상태입니다. 권한 확인 없이 자유롭게 실행하세요. (.claude/settings.json에 bypassPermissions 적용)

---

핵심 설계 원칙 (절대 불변)

1. 14:50 강제 청산 — 하드코딩, 예외 없음
2. 손절 우선 — AI 판단과 무관하게 손절 룰 항상 우선순위 1위
3. AI 역할 분리 — Claude Code는 장 전 분석 + 장 후 피드백만, 실시간 매매 개입 불가
4. 검증 순서 — 모의투자 3개월 → 조건 충족 → 실거래

---

하루 흐름

08:30  claude_morning → 뉴스/수급/지수 분석 → app/ai/daily_context.json 저장 → Discord 전송
08:50  유니버스 30종목 확정 + 전일 OHLCV 수집 + 목표가 계산
09:00  매매 루프 시작 (변동성 돌파 신호 + AI 필터)
14:50  강제 전량 청산 (절대 불변)
15:10  일일 결산 → Discord 전송
15:30  claude_evening → 결과 분석 + config.py 조정 + reports/ 저장 → Discord 전송

---

Claude Code 역할 상세

장 전 분석 (08:30) — claude_morning

1. 네이버/다음 금융 뉴스 크롤링 (data/news/ 저장)
2. KIS API 수급/지수 데이터 수집 (data/market/ 저장)
3. 시장 분위기 판단 (강세/중립/약세)
4. 감성 점수 산출 (0~100)
5. 주목 섹터 / 회피 섹터 선정
6. boosted_tickers / blacklist_tickers 결정
7. 포지션 사이즈 배율 결정 (0.5~1.5)
8. app/ai/daily_context.json 저장
9. Discord로 분석 요약 전송

daily_context.json 형식:

{
  "date": "2026-05-15",
  "generated_at": "08:30:00",
  "trade_allowed": true,
  "market_sentiment": "중립",
  "sentiment_score": 62,
  "risk_level": "보통",
  "hot_sectors": ["반도체", "2차전지"],
  "avoid_sectors": ["금융", "건설"],
  "boosted_tickers": ["005930", "000660"],
  "blacklist_tickers": [],
  "position_size_multiplier": 1.0,
  "reason": "분석 요약"
}

장 후 피드백 (15:30) — claude_evening

1. data/stockbot.db 오늘 매매 내역 조회
2. logs/trades.log 오늘 로그 확인
3. reports/daily/ 최근 30일 리포트 참조
4. 승률/손익/이상패턴 분석
5. app/config.py 파라미터 조정 (문제 명확할 때만)
6. reports/daily/날짜.md 저장
7. 실전 전환 조건 5가지 체크
8. Discord로 요약 전송

---

파일 구조

stockbot_v3/
├── CLAUDE.md                   ← 이 파일
├── .env                        ← API 키 (Git 절대 제외)
├── app/
│   ├── main.py                 ← 메인 매매 루프
│   ├── config.py               ← 전략 파라미터 (수정 가능)
│   ├── ai/
│   │   └── daily_context.json  ← 장 전 AI 분석 결과 (매일 갱신)
│   ├── strategy/
│   │   └── volatility_breakout.py  ← 전략 로직 (수정 가능)
│   ├── execution/
│   │   ├── kis_client.py       ← KIS API 래퍼
│   │   └── order_executor.py   ← 주문 실행
│   ├── risk/
│   │   └── manager.py          ← 리스크 관리 (수정 가능)
│   ├── monitor/
│   │   └── notifier.py         ← Discord Webhook
│   └── db/
│       ├── models.py           ← SQLite 스키마
│       └── repository.py       ← DB 접근
├── reports/
│   ├── daily/                  ← 매일 자동 생성
│   ├── weekly/                 ← 매주 자동 생성
│   └── live_ready/             ← 실전 전환 조건 충족 시 생성
├── data/
│   ├── stockbot.db
│   ├── news/                   ← claude_morning 뉴스 저장
│   └── market/                 ← claude_morning 수급/지수 저장
└── logs/
    ├── stockbot.log
    └── trades.log

---

수정 범위

자유롭게 수정 가능

• app/config.py — 전략 파라미터 (TP1_PCT, TP2_PCT, SL_PCT, STRATEGY_K 등)
• app/strategy/volatility_breakout.py — 전략 로직, 진입/청산 조건
• app/risk/manager.py — 리스크 기준값 (L1~L5 임계값)
• app/ai/daily_context.json — 매일 장 전 생성
• reports/ — 리포트 생성/저장

승인 필요 (사용자 확인 후 수정)

• app/main.py — 구조 변경, 스케줄 변경
• app/execution/ — 주문 로직 변경
• app/db/ — 스키마 변경

절대 금지

• FORCE_EXIT = "14:50" 변경
• 손절을 익절보다 후순위로 변경
• .env 파일 직접 수정 (KIS_MOCK, DRY_RUN 포함)
• .env Git 커밋

---

Git 규칙

# 파일 수정 후 반드시 실행
git add -A
git commit -m "[2026-05-15] 수정내용 요약"
git push origin main

• push 대상: origin main (Gitea NAS)
• .env는 절대 커밋 금지 (.gitignore 등록 확인)
• 커밋 메시지: [날짜] 변경내용

---

리스크 관리 (L1~L5)

레벨	조건	동작	Discord
L1	1회 -1.5%	즉시 손절	[손절]
L2	일일 -3%	당일 신규 진입 중단	[경고]
L3	3연속 손절	당일 매매 중단	[경고]
L4	주간 -7%	주말까지 중단	[경고]
L5	월간 -15%	전략 폐기 + 재검토	[긴급]

---

실전 전환 조건 (claude_evening 자동 체크)

조건	기준
누적 운영	30거래일 이상
승률	최근 30일 > 48%
MDD	최근 30일 < -10%
샤프지수	최근 30일 > 1.0
L3 발동	월 2회 이하

전부 충족 시 → reports/live_ready/날짜_READY.md 생성 + Discord 🚀 알림

전환 방법: .env에서 KIS_MOCK=false, DRY_RUN=false 로 변경

---

운영 모드

KIS_MOCK	DRY_RUN	동작
true	true	신호 확인만 ← 현재
true	false	모의투자 실주문
false	false	실거래

---

현재 알려진 이슈 및 할 일

다음 단계

• WebSocket 전환 — REST 폴링 → KIS WebSocket 실시간 시세
• NAS Docker 이전

완료

• claude_morning 구현 — 뉴스 크롤링 + KIS 수집 + /morning 슬래시 커맨드
• claude_evening 구현 — 결과 분석 + 실전 전환 체크 + /evening 슬래시 커맨드
• 작업 스케줄러 자동화 — StockBot_Morning(08:15), StockBot_Bot(07:55), StockBot_Evening(15:30)
• Discord Stop 훅 — 세션 종료 시 이번 세션 커밋만 전송
• SQLite UPDATE ORDER BY → 서브쿼리 수정 (order_executor.py)
• 전일 데이터 캐시 skip 로직 (has_prev_data)
• 전일 날짜 계산 수정 (월요일 → 금요일)
• has_prev_data() 메서드 추가 (volatility_breakout.py)
• check_entries() / check_exits() sleep → 1.1초 (KIS rate limit)

---

NAS 이전 방법

로컬 개발 완료 후:

# 1. Gitea push (로컬)
git push origin main

# 2. NAS에서 pull
ssh nas
cd /volume1/docker/stockbot
git pull origin main

# 3. .env NAS에 별도 복사 (Git 경유 금지)
scp .env nas:/volume1/docker/stockbot/.env

# 4. Docker Compose 실행
docker-compose up -d

로컬 Claude Code는 개발/디버깅용, NAS는 운영용으로 역할 분리.