# kis_bot 코드 수정 가이드 — AI 에이전트 필수 체크리스트

> **이 문서의 목적**: 코드 수정 시 사이드 이펙트를 빠짐없이 잡기 위한 절차 정의.
> 두 참조 문서와 함께 사용하세요.
> - 📦 [code_architecture.md](./code_architecture.md) — 파일 간 import 의존성 맵
> - 🗄️ [db_erd.md](./db_erd.md) — DB 테이블 스키마 & ERD

---

## ⚡ 핵심 원칙

```
코드를 수정하기 전에,
반드시 아래 섹션에 해당하는 grep을 먼저 실행하고
결과를 확인한 뒤 수정 범위를 확정한다.
```

**grep을 생략해도 되는 유일한 경우**: 주석/docstring 텍스트만 바꾸는 경우.

---

## 🔍 수정 유형별 필수 grep 목록

### 0. 조건검색 유니버스 (LS / 키움) — 시드·재시도

> LS 공백·ALIGN·job 이벤트 수정 시. 상세: [code_architecture.md 수동 노트](./code_architecture.md)

```bash
grep -rn "LS_T1859_EMPTY_RETRY\|t1859\|_refresh_empty\|STALE_RESYNC\|rows_prefer" /home/hoon/kis_bot/kis_trader/network --include="*.py"
grep -rn "condition_common\|condition_job_events\|LIVE_UNIVERSE_SLOT_ALIGN\|CAND_LIMIT" /home/hoon/kis_bot --include="*.py" -l
```

**체크리스트**:
- [ ] LS: AFR≠풀덤프 → RAM0 재시드(`LS_T1859_EMPTY_RETRY_SEC`, 기본 **1**·TR_GAP≥1.1). **0=OFF** (무한 REST 아님)
- [ ] 키움 CNSRREQ / LS t1859 시드 경로 **합치지 말 것** (공통은 `condition_common` JOB 플래그만)
- [ ] 빈 t1859 → history INSERT 금지
- [ ] `database.py` ENV 키 목록 + `env_config_ext` 저장 검증
- [ ] 웹 조건 이벤트/정합 탭 API (해당 시)

---

### 1. ENV 파라미터 추가/변경/삭제

> 예: `MOMENTUM_E_MIN_CHG_PCT`, `SCALP_STOP_LOSS_PCT` 등

```bash
# ① env 키 이름 직접 참조
grep -r "MOMENTUM_E_MIN_CHG_PCT" /home/hoon/kis_bot --include="*.py" -l

# ② params dict snake_case 키
grep -r "e_min_chg_pct" /home/hoon/kis_bot --include="*.py" -l

# ③ database.py CREATE TABLE 컬럼 정의
grep -n "MOMENTUM_E_MIN_CHG_PCT" /home/hoon/kis_bot/database.py

# ④ env_keys.py 등록 여부
grep -r "E_MIN_CHG_PCT" /home/hoon/kis_bot/kis_trader/engine/momentum_env_keys.py
```

**확인 후 수정해야 할 곳 체크리스트**:
- [ ] `database.py` — CREATE TABLE에 컬럼 추가
- [ ] `kis_trader/engine/momentum_env_keys.py` — `MOMENTUM_CONFIG_KEYS` 등록
- [ ] `kis_trader/engine/momentum_engine.py` — `get_momentum_defaults()` 로드 및 return dict
- [ ] `kis_trader/engine/momentum_hts_logic.py` — 실제 로직에서 사용
- [ ] `kis_trader/backtest/param_search_momentum.py` — 그리드/텀 탐색 범위
- [ ] `kis_trader/backtest/param_search_apply_snapshot.py` — 스냅샷 적용 매핑
- [ ] `kis_trader/backtest/optuna_search_space.py` — Optuna 탐색 공간 (해당 시)

---

### 2. DB 테이블 컬럼 추가/변경/삭제

```bash
# ① 해당 테이블 참조 파일 목록
grep -r "active_trades" /home/hoon/kis_bot --include="*.py" -l

# ② 컬럼명 직접 참조
grep -rn "avg_buy_price" /home/hoon/kis_bot --include="*.py"

# ③ INSERT/UPDATE 구문 (컬럼 순서에 민감)
grep -rn "INSERT INTO active_trades" /home/hoon/kis_bot --include="*.py"
grep -rn "UPDATE active_trades" /home/hoon/kis_bot --include="*.py"
```

**확인 후 수정해야 할 곳 체크리스트**:
- [ ] `database.py` — `CREATE TABLE`, `ALTER TABLE`
- [ ] `database.py` — INSERT/UPDATE 쿼리 전부
- [ ] 해당 테이블 참조 파일들 — SELECT 컬럼 파싱 로직

---

### 3. 함수/메서드 시그니처 변경

```bash
# ① 함수 정의 위치
grep -rn "def eval_momentum_hts_buy_at_index" /home/hoon/kis_bot --include="*.py"

# ② 함수 호출 위치 전부
grep -rn "eval_momentum_hts_buy_at_index" /home/hoon/kis_bot --include="*.py"

# ③ import 위치
grep -rn "from.*import.*eval_momentum_hts_buy_at_index" /home/hoon/kis_bot --include="*.py"
```

**확인 후 수정해야 할 곳 체크리스트**:
- [ ] 함수 정의 파일
- [ ] 함수를 import하는 모든 파일
- [ ] 함수를 호출하는 모든 파일

---

### 4. 전략 params dict 키 추가/변경

> 예: `mom_vol_mult`, `e_min_chg_pct` 같은 params 딕셔너리 키

```bash
# ① params에서 꺼내는 곳
grep -rn '"e_min_chg_pct"' /home/hoon/kis_bot --include="*.py"

# ② params에 넣는 곳 (파일 목록)
grep -rn "e_min_chg_pct" /home/hoon/kis_bot --include="*.py" -l
```

**확인 후 수정해야 할 곳 체크리스트**:
- [ ] 엔진 `get_*_defaults()` 함수 — params 생성
- [ ] 엔진 로직 파일 — `params.get("key", default)`
- [ ] 파라미터 서치 — 그리드 정의, 스냅샷 적용, `_to_env` 매핑
- [ ] Optuna 탐색 공간 — `_suggest_from_grid` 대상 그리드

---

### 5. 클래스/모듈 이름 변경 또는 파일 이동

```bash
# ① import 참조 전부
grep -rn "from kis_trader.engine.momentum_hts_logic import" /home/hoon/kis_bot --include="*.py"

# ② 문자열로 언급되는 곳 (동적 import, 로그 등)
grep -rn "momentum_hts_logic" /home/hoon/kis_bot --include="*.py"
```

---

### 6. 웜업(Warmup) 로직 변경

```bash
# ① 웜업 관련 함수 목록
grep -rn "candle_warmup" /home/hoon/kis_bot --include="*.py" -l
grep -rn "REST_WARMUP" /home/hoon/kis_bot --include="*.py" -l

# ② 웜업 bars env 키
grep -rn "BACKTEST_CANDLE_WARMUP_BARS" /home/hoon/kis_bot --include="*.py"
grep -rn "BACKTEST_REST_WARMUP_BARS" /home/hoon/kis_bot --include="*.py"
```

---

### 7. HTS 조건식 로직 변경

```bash
# ① skip_hts_scan_dupes 관련
grep -rn "skip_hts" /home/hoon/kis_bot --include="*.py" -l

# ② hts_trigger 설정
grep -rn "hts_trigger_defaults" /home/hoon/kis_bot --include="*.py"
grep -rn "trigger_e_confirm" /home/hoon/kis_bot --include="*.py"
```

---

## 📋 수정 전 표준 워크플로우

```
1. 수정 요청 파악
   └─ 어떤 유형의 변경인가? (ENV / DB / 함수 / 파라미터 / 파일이동 ...)

2. code_architecture.md 에서 연관 파일 1차 파악
   └─ 허브 파일 Top 20 체크
   └─ 전략별 파일 분류에서 관련 전략 파일 확인
   └─ DB 테이블 ↔ 코드 파일 연관 맵 확인

3. 위 섹션의 grep 명령어 실행 (반드시)
   └─ 발견된 파일 목록 확정

4. db_erd.md 에서 DB 스키마 확인 (DB 관련 변경 시)
   └─ 컬럼 타입, PK, 인덱스 확인

5. 수정 범위 확정 후 코드 수정

6. 문법 검사
   └─ python3 -m py_compile <수정한 파일>

7. (필수) docs/ 문서 갱신 — 아래 조건 중 하나라도 해당하면
   └─ 파일 추가/삭제/이동이 있었다면 → code_architecture.md 재생성
   └─ DB 테이블/컬럼이 변경됐으면 → db_erd.md 재생성
   └─ ENV 키/params 키가 추가됐으면 → MODIFICATION_GUIDE.md 체크리스트 갱신
```

---

## 🚨 이 프로젝트 특이 사항 (절대 무시 금지)

### SKIP_HTS_SCAN_DUPES 규칙
```
`*_SKIP_HTS_SCAN_DUPES` 는 사용자가 언급하기 전까지 false 유지.
임의로 true로 바꾸지 말 것.
```

### HTS 조건식과 코드 분리
```
HTS는 후보 유니버스 참고용.
그리드를 HTS 밴드에 맞추라고 강제하지 말 것.
```

### 백테스트 웜업 전략별 분리
```
모멘텀 웜업 변경이 스캘핑/꼬리잡기 웜업에 영향을 주지 않는다.
각 전략 웜업 함수는 독립적이다:
  - momentum_backtest_candle_warmup_bars()  ← momentum_backtest_common.py
  - scalp_backtest_candle_warmup_bars()    ← scalping_backtest_common.py
  - tail_backtest_candle_warmup_bars()     ← tail_backtest_common.py
```

### env 키 저장 경로
```
database.py의 CREATE TABLE 컬럼에 있는 키 → 해당 config_* 테이블 컬럼
database.py의 CREATE TABLE에 없는 키      → env_config_ext (key-value 테이블)
새 env 키 추가 시 두 경로 중 어디에 저장될지 확인 필요.
```

### e_min_chg_pct 단위
```
e_min_chg_pct 는 퍼센트 단위 (0.5 = 0.5%).
코드 내부에서 / 100.0 변환 후 사용.
```

---

## 🛠️ 자주 쓰는 grep 원라이너 모음

```bash
# ENV 키 전체 참조 추적
grep -rn "ENV_KEY_NAME" /home/hoon/kis_bot --include="*.py"

# DB 테이블 참조 파일 목록
grep -rl "table_name" /home/hoon/kis_bot --include="*.py"

# params dict 특정 키 추적
grep -rn '"param_key"' /home/hoon/kis_bot --include="*.py"

# 함수 호출 추적
grep -rn "function_name(" /home/hoon/kis_bot --include="*.py"

# import 경로 추적
grep -rn "from module.path import" /home/hoon/kis_bot --include="*.py"

# 특정 전략 파일만 검색
grep -rn "keyword" /home/hoon/kis_bot/kis_trader/engine --include="*momentum*"

# SQL 쿼리 내 테이블 참조
grep -rn "FROM table_name\|INTO table_name\|UPDATE table_name" /home/hoon/kis_bot --include="*.py"
```

---

## ✅ 이 가이드 + 두 MD 파일이면 충분한가?

| 상황 | 충분 여부 |
|------|----------|
| ENV 파라미터 추가/변경 | ✅ 충분 (위 체크리스트 따르면) |
| DB 컬럼 추가/변경 | ✅ 충분 (grep 필수 실행 시) |
| 함수 시그니처 변경 | ✅ 충분 |
| 전략 간 공유 유틸 변경 | ✅ `code_architecture.md` 허브 파일 + grep |
| 동적 import 패턴 변경 | ⚠️ grep으로만 확인 가능 (MD로 탐지 불가) |
| 런타임에만 나타나는 의존 | ❌ 실제 실행해봐야 함 |

> **결론**: grep을 반드시 실행한다는 전제 하에,
> 이 세 파일(MODIFICATION_GUIDE.md + code_architecture.md + db_erd.md)이면
> 런타임 의존성을 제외한 대부분의 케이스에서 누락 없이 수정 가능합니다.

---

## 🔄 docs/ 문서 갱신 규칙 (필수)

### 갱신 트리거 조건

| 변경 유형 | 갱신할 문서 |
|-----------|------------|
| .py 파일 추가/삭제/이동 | `code_architecture.md` |
| import 구조 변경 | `code_architecture.md` |
| DB 테이블/컬럼 변경 | `db_erd.md` |
| ENV 키/params dict 키 추가 | `MODIFICATION_GUIDE.md` 체크리스트 |
| 전략 추가/삭제 | `code_architecture.md` + `MODIFICATION_GUIDE.md` |

### 갱신 방법

```bash
# code_architecture.md 재생성 (AST 분석 스크립트)
cd /home/hoon/kis_bot && python3 /tmp/gen_arch_md.py

# db_erd.md 재생성 (DB DDL 추출 → MD 변환)
cd /home/hoon/kis_bot && python3 /tmp/gen_erd_md.py
```

### 동적 import 안전성 (2026-08-01 감사 결과)

이 프로젝트의 동적 import는 **총 7건**이며, 전부 무해한 패턴입니다:
- 표준 라이브러리 인라인 호출: `__import__("json")`, `__import__("time")` — 3건
- 테스트 모듈 로딩: `importlib.import_module("_test_...")` — 2건
- 레거시 (remove/ 폴더, 비활성) — 2건

**핵심 매매/엔진/백테 코드에서 동적 import로 전략을 분기하는 패턴은 없습니다.**
코드 수정 불필요.