feat: 새로운 안전 규칙 및 최적화 적용을 통한 트레이딩 시스템 개선

변경 사항 (Changes):

구문 오류(Syntax error) 및 토큰 낭비를 방지하기 위해 에이전트 쉘(Agent shell)과 파이썬 코드 스니펫에 다수의 신규 안전 규칙(Safety rules)을 추가함.

스키마 검증 및 적절한 SQL 포맷팅을 보장하기 위해 임시(Ad-hoc) 데이터베이스 쿼리 작성 가이드라인을 도입함.

코드 수정 후 UI 기능이 정상 작동하는지 확인하기 위해, 백테스트 웹 서비스 재시작 및 브라우저 검증에 대한 새로운 규칙을 구현함.

시스템 전반의 무결성(Integrity)을 유지하기 위해 실전 매매(Live trading), 웹 백테스팅, 파라미터 탐색(Parameter searches) 간의 일관성 검사(Consistency checks) 체계를 확립함.

기대 효과 (Impact):

이러한 개선 사항들은 트레이딩 시스템의 견고성(Robustness)과 신뢰성을 향상시키며, 에러 발생을 최소화하고 다양한 시스템 컴포넌트 간의 원활한 상호작용을 보장함.
This commit is contained in:
Your Name
2026-07-17 01:09:09 +09:00
parent a4626e0351
commit fc27e726f9
151 changed files with 20718 additions and 6450 deletions

View File

@@ -31,6 +31,56 @@
- 8. 공통으로 사용할 수 있는 코드는 공통으로 코드를 작성하고 함수로 만들어서 사용하세요.
- 9. 코드 수정 시 개발의 기본 none null 로 인한 오류가 나지 않는지 확인하세요.
- 10. 테스트 코드를 돌리거나 할 때 백그라운드로 돌리고 tail -f 로 볼 수 있는 log파일 경로를 알려주세요.
- 11. **인프라·공유경로·재시작 안정성 검증 (전 전략 공통, 필수)**
갭보정·WS/REST·워커·봉 롤업·구독·유니버스·env 기본값·공유 헬퍼 등 **실매에 영향 있는 인프라/공통 코드**를 수정한 뒤에는,
“유닛이 돌아간다”만으로 끝내지 말고 **재시작·다전략 공존** 관점에서 검증한 뒤 보고하라.
하나라도 미확인이면 “안전/문제없다”고 단정하지 말고, 고치거나 잔여 위험을 명시하라.
(꼬리·모멘텀·돌파·스캘핑·레인지 등 **어느 전략을 고쳐도** 동일. 특정 수치·특정 사건 전용 체크가 아님.)
- **교차 부작용**: A전략용 한도·가드·ok마킹·재시도가 B전략 웜업/매수를 깨지 않는가? 공유 큐·공유 캐시·owner(후보) 분기를 확인했는가?
- **웜업/매매 0건**: 봉·틱·롤업·min 봉수 조건이 스킵·조기완료·영구 미충족으로 트리거가 막히지 않는가?
- **API 폭주**: 재시도·재큐·bulk refill·폴백(키움/한투)이 무한·과도 반복하지 않는가? 실패 상한 후 재큐가 멈추는가? sleep·워커·초당 한도를 넘지 않는가?
- **장외/장중·폴백 기본값**: 장외 no-op/안전 동작, 위험 폴백 기본 OFF 여부.
- **락/예외**: 공유 lock 재진입·데드락, 예외 삼킴으로 인한 조용한 실패가 없는가?
- **최소 산출물**: 관련 스모크(가능하면 전략 2개 이상 경로) + 재시작 후 정상/이상 로그 시그니처 + log 경로.
- 12. **DB 임시 조회(adhoc) — 스키마·PyMySQL 안전 (토큰 낭비 금지)**
- TradeDB로 SQL 날리기 전 **반드시** `SHOW COLUMNS FROM <table>`로 실제 컬럼 확인. 추측 SELECT 금지.
- `target_candidates`에는 **`strategy_id` 없음** (code/name/score/price/scan_time/updated_at ± market/sector/theme).
- pymysql: SQL 문자열의 `%`는 포맷으로 해석됨. `LIKE '20260712%'` 금지 → `LIKE %s` + `('20260712%',)` 또는 `%%`.
- `not enough arguments for format string` = `%` 충돌이지 스키마 오류가 아님.
- 실패 시 원인 고친 뒤 **1회만** 재실행. 같은 가정으로 날짜/strategy만 바꿔 반복 금지. 상세: `.cursor/rules/db-adhoc-query-safety.mdc`
- 13. **파람서치·백테 토큰/재실행 절약** (상세: `.cursor/rules/optuna-backtest-token-savings.mdc`)
- 주말/공휴일이면 **최근 거래일**로만 실행 (오늘=일요일이라 재실행한 낭비 금지).
- 그리드(categorical) 변경 후 **반드시 새 `--study-name`**. 동일 study 재사용 → dynamic value space 에러 → 통째 재실행 낭비.
- Optuna 전: **실매 DB 핵심값이 해당 mode 그리드에 포함**되는지 확인. 없으면 trial 금지(실매 근방 미탐색).
- `--apply-best` 미명시 시 DB 미적용. 긴 잡은 nohup+로그 경로만, `for+sleep` 폴링 금지. 비교 헬퍼 재사용.
- 14. **백테 웹 재시작 + 브라우저 검증** (상세: `.cursor/rules/backtest-web-restart.mdc`)
- 웹 UI/API 수정 후 `sudo systemctl restart kis_backtest_web.service` 실행 → `active` + curl 확인.
- **그걸로 끝내지 말 것.** 브라우저로 페이지를 띄워 수정한 탭·버튼을 눌러보고, 콘솔 `Uncaught`/`ReferenceError` 없음을 확인한 뒤에야 완료 보고.
- `curl 200`만 = 검증 미완료. 실매 봇은 웹과 무관하면 재시작하지 말 것.
- 15. **실매↔웹백테↔파람 정합 — 파람은 Optuna 기본** (상세: `.cursor/rules/live-backtest-optuna-parity.mdc`)
- 전략/파라미터 수정 시 실매 엔진·DB → 웹백테 인풋/API → Optuna 그리드(실매값 포함)를 **한 세트로** 맞춘다.
- 파람서치 기본 = `param_search_optuna.py` (진행률·TPE). Grid는 사용자 명시·미지원 전략·그리드 점검용만.
- 검증: 거래일 보정 → 웹백테 1회 → Optuna(no `--apply-best`, 새 study-name) → 현재 DB vs best 비교표. 어긋나면 정합 OK 금지.
- 완료 보고: 기간·로그/JSON·현재/best PnL·Δ·적용여부(기본 미적용).
- 16. **HTS = SCAN 참고 — TRIGGER/그리드 HTS 숫자 강제 맞춤 금지** (상세: `.cursor/rules/hts-condition-grids.mdc`)
- HTS는 후보 유니버스 참고. 그리드를 HTS 밴드에 맞추라고 강제하지 말 것.
- `*_SKIP_HTS_SCAN_DUPES` 는 **사용자가 언급하기 전까지 false 유지**. 임의로 true로 바꾸지 말 것.
- Optuna는 타점/청산/리스크 축. 실매↔웹↔Optuna 엔진 정합(15)은 별개.
- 17. **에이전트 셸·Python 스니펫 — 문법 오류 코드 실행 금지** (상세: `.cursor/rules/agent-shell-python-safety.mdc`)
- `from X import Y if cond else None` 등 **가짜 문법** heredoc 금지. SyntaxError로 턴·토큰 낭비.
- 실행 전 문법 확인(또는 `py_compile` 1회). 실패 시 고치고 **1회만** 재실행.
- 심볼명은 Grep/`hasattr`로 확인 후 import. 시그니처 모르면 `inspect.signature` 먼저.
- 18. ** 백테 파람서치 정합성 검증**
- 백테 파람서치 정합성 검증 시 백테 파라미터서치의 결과 값이 동일해야 하고 검증을 꼭 거쳐야 한다.
- optuna 파라미터서치 결과 값이 각 백테 탭 결과와 동일해야 하고 검증을 꼭 거쳐야 한다.
- 백테 웹페이지 탭을 직접 들어가 결과를 확인하고 검증을 꼭 거쳐야 한다.
- optuna `SKIP_HTS_SCAN_DUPES` 는 false 유지하고 수정하지 말 것.
- optuna 각 전략의 hts_skip은 false 유지하고 수정하지 말 것.
- 19. **땜빵용 코딩은 지양한다**
- 근본원인을 고쳐야돼 항상 근본원인을 먼저찾고 초등학생도 이해하기 쉽게 설명 후 설계를 하고 보고한다.
- 20. 수정 사항이 실매에 영향이 가는지 백테 파라미터에만만 영향이 가는지 명확히 분류 후 보고하고 수정한다.
- 21. 백테 웹페이지 탭 ui 수정시 다른 전략 탭도 모두 수정되어야 한다.
- 가상거래내역, 실거래내역 ui 는 모두 동일해야한다.
# [CRITICAL SYSTEM DIRECTIVES: 절대 엄수 사항 - 위반 시 작동 중지]
## 1. 🚨 하드코딩 절대 금지 (NO HARDCODING)