---
description: 실매↔웹백테↔파람 정합 — 파람서치는 Optuna 기본, 수정 후 교차검증 체크리스트
alwaysApply: true
---

# 실매 · 웹백테 · 파람서치 정합 (Optuna 기본)

`.cursorrules` 5·7번을 **실행 절차**로 구체화한다.  
전략 로직/파라미터/공통 엔진을 고치면 “코드만 맞춤”으로 끝내지 말고 **실매 기준 → 웹백테 → Optuna** 순으로 검증한다.

## 0. 파람서치 기본 = Optuna

- 사용자가 Grid CLI를 **명시**하지 않으면 파람서치는 **`param_search_optuna.py`** 를 쓴다.
  - 이유: trial 진행률·study 재개·TPE 탐색이 Grid보다 섬세하고 운영에 맞음.
- Grid (`tail_param_search.py` 등)는 Optuna가 없는 전략·사용자가 Grid를 지정한 경우·그리드 공간 점검용만.
- Optuna 대상: `tail` | `momentum` | `breakout` | `scalp` (`--strategy`).

## 1. 수정 시 맞출 대상 (한 축이라도 빠지면 미완료)

| 축 | 무엇 |
|----|------|
| 실매 | `*_engine` / Strategy + DB env (`get_*_defaults_from_db`) |
| 웹백테 | `backtest_web.py` API + 해당 탭 인풋 = 실매 키·기본값 |
| 파람 | Optuna 그리드 ⊃ **실매 TRIGGER/청산 핵심값** (HTS SCAN 밴드 재현 목적 아님 — `hts-condition-grids.mdc`) |
| 공통 | 가능하면 엔진/헬퍼 1경로 공유 (백테·Optuna가 실매와 다른 분기 금지) |

## 2. 검증 체크리스트 (보고 전)

1. **거래일**: start/end = 최근 장운영일 (`kr_trading_day`). 주말·휴장 날짜로 돌리지 말 것.
2. **실매 DB 스냅샷**: 해당 전략 핵심 파라미터 확인.
3. **그리드 ⊃ 실매값**: Optuna mode 축에 실매값이 없으면 그리드 먼저 고침 (또는 사용자 보고 후 중단).
4. **웹백테 1회**: 동일 start/end·동일 파라미터로 탭 실행 → 거래수·PnL·승률 기록. (웹 수정 시 항목 14 브라우저 검증 포함)
5. **Optuna (기본)**:  
   ```bash
   python3 -u kis_trader/backtest/param_search_optuna.py \
     --strategy <tail|momentum|breakout|scalp> --mode <fast|coarse|fine|…> \
     --start YYYY-MM-DD --end YYYY-MM-DD \
     --trials N --min_trades 1 --orderbook-filter off --no-progress \
     --study-name <전략>_<mode>_<TS>
   # --apply-best 없음 (기본)
   ```
   - nohup + 로그 경로 안내. `for+sleep` 폴링 금지.
   - categorical 그리드 변경 시 **새 study-name** 필수.
6. **교차 비교**: 동일 기간 **현재 DB 백테 PnL** vs **Optuna best 백테 PnL** (헬퍼 재사용: `scripts/append_tail_optuna_compare.py` 등).  
   - 수치·건수가 어긋나면 “정합 OK” 금지 → 원인 분류(엔진/유니버스/틱재생/포트폴리오).
7. **DB 적용**: 사용자 `--apply-best`/적용 지시 **없으면** 저장 금지. 1일 best는 과적합 경고.

## 3. 완료 보고 최소 산출물

- 전략·기간(거래일)·mode·study-name·로그/JSON 경로
- 현재 DB 백테 요약 (trades / WR / PnL)
- Optuna best 요약 + Δ(현재 대비)
- 웹백테를 돌렸으면 그 수치 (또는 “웹 미해당”)
- 적용 여부: **미적용** / 사용자 지시로 적용

## 4. 하지 말 것

- Grid를 기본 경로로 돌리기 (사용자 미지정 시)
- 실매만 고치고 웹·Optuna 그리드/기본값 방치
- Optuna best를 검증 없이 DB 반영
- 주말 날짜·구 study·실매값 빠진 그리드로 trial 낭비