-
Notifications
You must be signed in to change notification settings - Fork 0
Rulebook
JJong-03 edited this page Mar 5, 2026
·
4 revisions
이 페이지는 프로젝트의 비타협(Non-Negotiable) 규칙 10가지를 공개 요약한 것이다. 내부 규약(비공개)에서 발췌하였으며, 모든 설계·구현·운영 결정은 이 규칙을 따른다. 이 규칙들은 재현성(Reproducibility) 과 운영 안전성(Operational Safety) 을 보호하기 위해 존재한다.
| # | Name | What | Why | Learn more |
|---|---|---|---|---|
| 1 | Engine Immutability |
backtest/engine.py 및 핵심 엔진 로직은 절대 수정 금지. 새 기능은 Wrapper/Adapter 패턴으로만 추가한다. |
검증 완료된 레거시 엔진의 신뢰성과 재현성을 보존한다. | Design Principles, ADR-Design Decisions, Reproducibility |
| 2 | Additive-only API | Web↔Worker JSON Schema는 동결. 기존 필드 삭제·이름 변경 금지. 새 필드 추가 시 기본값 필수. | 독립 배포 환경에서 Web-Worker 통신이 깨지지 않도록 보장한다. | API-Endpoints & Schemas, Execution Lifecycle |
| 3 | Run from Repo Root | 모든 명령(Docker build, Python, 테스트)은 프로젝트 루트에서 실행. 하위 폴더 cd 금지. |
하위 폴더 실행 시 ModuleNotFoundError 등 import 오류가 발생한다. |
Runbook-Troubleshooting |
| 4 | Stateless Web | Flask 서버는 로컬 파일시스템 쓰기 금지. 차트는 메모리 → Base64. 로그는 stdout/stderr만. | Pod 수평 확장(HPA) 시 상태 공유 문제를 원천 차단한다. | Infra Architecture, Design Principles |
| 5 | Matplotlib Agg + plt.close |
matplotlib.use("Agg") 필수. 렌더링 후 plt.close(fig) 필수. |
서버 환경에서 GUI 의존 없이 렌더링하고, figure 누적에 의한 메모리 누수를 방지한다. | [[UI 화면 구성 |
| 6 | Error Type Separation |
user_error → HTTP 400 (Job 미생성). system_error → HTTP 500. 상세 스택트레이스는 서버 로그에만 기록. |
사용자 수정 가능 오류와 운영자 조치 필요 오류를 명확히 구분하여 triage를 가속한다. | Execution Lifecycle, Runbook-Troubleshooting |
| 7 | Config via Env Vars | 모든 설정은 환경변수로 주입. Secret은 Git 커밋 금지. K8s에서는 ConfigMap + Secret 사용. | 하드코딩된 시크릿 커밋을 방지하고, 환경별 설정 전환을 안전하게 한다. | Security Model, CI_CD_GitOps |
| 8 | run_id Logging | 모든 실행에 run_id(UUID4) 부여. 모든 로그 라인에 [run_id=<RUN_ID>] 포함. stdout/stderr로만 로깅. |
K8s 분산 환경에서 Web → Worker → DB 전 구간을 단일 요청 단위로 추적 가능하게 한다. | Execution Lifecycle, Runbook-Troubleshooting |
| 9 | DB Session Safety |
db.session.commit()은 항상 try/except 내에서 호출. 실패 시 rollback 필수. db.create_all()은 로컬 개발에서만 호출. |
트랜잭션 손상을 방지하고, Production 스키마 초기화는 운영자가 명시적으로 수행한다. | Runbook-Troubleshooting, Execution Lifecycle |
| 10 | Immutable Image Tags | Docker 이미지 태그는 Git SHA 또는 semver 사용. latest 금지. 동일 태그 덮어쓰기 금지. |
배포 이력 추적과 롤백을 보장한다. 어떤 코드가 실행 중인지 항상 식별 가능해야 한다. | CI_CD_GitOps, ADR-Design Decisions |
- 위키 내에서 특정 Rule 번호를 언급할 때는
[[Rulebook]]로 링크한다. - 예: "Matplotlib Agg 백엔드 사용은 Rule 5에 해당한다."
- 이 페이지가 프로젝트 규칙의 단일 공개 참조점(Single Public Reference) 이다.
- Design Principles — 10개 규칙을 8가지 아키텍처 원칙으로 재구성한 문서
- ADR-Design Decisions — 각 규칙의 대안 비교 및 의사결정 기록
- Glossary — 용어 정의