kis_bot/docs/like_mcp.md/MODIFICATION_GUIDE.md

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

이 문서의 목적: 코드 수정 시 사이드 이펙트를 빠짐없이 잡기 위한 절차 정의. 두 참조 문서와 함께 사용하세요.

• 📦 code_architecture.md — 파일 간 import 의존성 맵
• 🗄️ db_erd.md — DB 테이블 스키마 & ERD

---

⚡ 핵심 원칙

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

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

---

🔍 수정 유형별 필수 grep 목록

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

LS 공백·job 이벤트 수정 시. 상세: code_architecture.md 수동 노트

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\|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 등

# ① 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

호가 필터 나이: WS_ORDERBOOK_FILTER_MAX_AGE_SEC(기본 0=마지막 RAM) ≠ 저장 TTL WS_ORDERBOOK_TICK_MAX_AGE_SEC. 후처리 TPE 진입 격자: OPTUNA_OB_ENTRY_SPREAD_* / RATIO_* / ASK_MULT_* (optuna_common.ensure_optuna_gate_env_defaults). 꼬리 TPE 진입모드는 탐색 축이 아님(웹 체크 → 스터디 고정/순차 2회). *_SKIP_HTS_SCAN_DUPES true 금지.

확인 후 수정해야 할 곳 체크리스트:

• 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 테이블 컬럼 추가/변경/삭제

# ① 해당 테이블 참조 파일 목록
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. 함수/메서드 시그니처 변경

# ① 함수 정의 위치
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 딕셔너리 키

# ① 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. 클래스/모듈 이름 변경 또는 파일 이동

# ① 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) 로직 변경

# ① 웜업 관련 함수 목록
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 조건식 로직 변경

# ① 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 키 추가 시 두 경로 중 어디에 저장될지 확인 필요.
Optuna 후처리(실매 엔진 비영향): OPTUNA_POST_TOP_N / INCLUDE_MODE / INCLUDE_LIVE /
  OB·WHIPSAW trial 수 · OPTUNA_OB_AXIS_TRIALS · 진입/익절/STOP 탐색 범위 —
  ensure_optuna_gate_env_defaults → env_config_ext.
  모듈: kis_trader/backtest/optuna_postprocess_topn.py · optuna_orderbook_recommend.py
  · optuna_rerun_postprocess.py (구 JSON 「이 잡 후처리 재실행」)
  진입 격자(2026-08-15): OPTUNA_OB_ENTRY_SPREAD 0.1~8 / RATIO 0.05~1.5 / ASK_MULT 1~80 / LOOKBACK 30분.
  실매 필터 나이: WS_ORDERBOOK_FILTER_MAX_AGE_SEC(0) ≠ WS_ORDERBOOK_TICK_MAX_AGE_SEC(저장).
  사진 한 장도 없으면: WS_ORDERBOOK_FILTER_REJECT_IF_EMPTY(기본 true) → 필터 ON일 때 안 삼.

e_min_chg_pct 단위

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

---

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

# 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

갱신 방법

# 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로 전략을 분기하는 패턴은 없습니다. 코드 수정 불필요.