# 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 형식:
```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 규칙

```bash
# 파일 수정 후 반드시 실행
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 이전

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

---

## NAS 이전 방법

로컬 개발 완료 후:

```bash
# 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는 운영용으로 역할 분리.