bioreport

Research System Refactor — Thread-based + Universe Tracking

11 min read

상태 (2026-04-22): Phase 0~3 완료 (기초 + 도구 + dogfood). Phase 4 (backport) / Phase 5 (site 추가 정리) 는 skip. Phase 6 (상시 운영) 진입 — 이후 리서치는 전부 research/threads/ 로 누적.

Research System Refactor

바이오텍 백테스트 리서치 시스템 재설계 기획서. 지금까지 쌓인 리서치 (v9~v12, v5.1, 여러 research_*/studies/reports) 를 반복 가능하고 공정 비교 가능한 시스템 으로 재편.

1. 목적 (Why)

현재 구조의 3가지 한계:

  1. 반복 리서치가 누적 안 됨 — exit 전략을 v1, v2 파고 v3 팔 때, ‘이전 결론이 뭐였더라?’ 가 분산된 파일 읽어야 파악 가능
  2. 공정 비교 불가능 — 서로 다른 실험이 다른 universe / period 로 돌았을 때 자동 감지 없음. 결과 차이가 실험 변수 때문인지 배경 때문인지 모름
  3. 의사결정 흐름 휘발 — v11 에서 p3 고정한 이유, v13 에서 entry 5종 확정한 이유 등이 회의 맥락에만 존재

목표:

  • 같은 주제를 반복 파도 이전 결과가 레이어처럼 쌓이는 구조
  • 실험 두 개를 비교할 때 공정 비교 가능한가 가 자동 판단
  • 의사결정 근거가 시간순 추적 가능
  • 과거 실험 재현 가능 (universe 가 바뀌어도)

2. 핵심 원칙

  1. Thread 는 시간축, 버전은 통합점 — 주제별 thread 가 무한히 자라고, 버전은 그 시점 thread 들의 최선 스냅샷
  2. Universe 는 변수 — 배경이 아님. Spec + snapshot 이중 버저닝
  3. 원본 repo 보존 — 과거 파일 이동/삭제 X. 새 구조는 병행 시작, 점진 확장
  4. 도구로 보장 — 규칙을 사람 기억에 의존 X. compare/lint 스크립트로 자동 검증
  5. Dogfooding — 다음 실험 (v13.3) 을 새 시스템으로 돌려 실전 검증

3. 최종 구조

3.1 디렉토리

projects/biolode-backtest/
├── biotech/                       ← 기존 코드 (수정 최소)
├── docs/                          ← 기존 문서 (보존)
├── notion_exports/                ← 기존 (보존)
│
├── research/                      ← 🆕 새 시스템 루트
│   ├── EXPERIMENT_SCHEMA.md       ← 실험 표준 스키마 정의
│   ├── THREAD_GUIDE.md            ← thread 관리 규칙
│   │
│   ├── threads/
│   │   ├── universe/                ← 스크리닝 (price filter 포함)
│   │   │   ├── README.md          ← 현재 best + open questions
│   │   │   ├── decisions.md
│   │   │   ├── specs/             ← V3.json, V3-p3.json 등 (완전한 필터 명세)
│   │   │   ├── snapshots/         ← V3_2026-03-15.csv 등 (불변)
│   │   │   └── experiments/       ← universe 차원 실험 (cash, ATH, price sweep, mcap, ...)
│   │   ├── entry/
│   │   ├── exit/
│   │   ├── ensemble/
│   │   ├── grid-search/
│   │   ├── catalyst/
│   │   └── regime/
│   │
│   ├── versions/                  ← 통합 배포 스냅샷
│   │   ├── v9~v12/
│   │   ├── v5.1/
│   │   └── v13/                   ← 새 시스템으로 돌 첫 버전
│   │
│   └── scripts/
│       ├── compare.py             ← 실험 2개 공정비교 진단
│       ├── lint.py                ← 스키마 / snapshot 참조 검증
│       └── snapshot_universe.py   ← universe 빌드 + 저장
│
└── (기존 biotech/results/ 등은 그대로)

3.2 실험 단위 표준

research/threads/<thread>/experiments/<NNN>-<slug>/

003-chandelier-atr/
├── README.md         ← 질문/가설/방법/결과/결론
├── config.json       ← 재현 가능한 파라미터 (universe/period/oos 포함)
├── metrics.json      ← 결과 지표 스냅샷
├── charts/           ← PNG / SVG
├── trades.csv        ← (옵션) 거래 원본
└── notebook.ipynb    ← (옵션)

3.3 표준 메타 (필수 4필드)

모든 실험의 config.json 또는 README frontmatter 에 반드시:

---
thread: exit
id: 003-chandelier-atr
universe_snapshot: V3_2026-03-15    # 불변 스냅샷 참조
period: 2016-01-01 / 2024-12-31
oos_split: 2024-01-01
---

이 4필드 동일 → 공정 비교 가능. 하나라도 다르면 → 경고.

3.4 ID 스키마

NNN-slug (001, 002, …) + thread 내 sequence. 날짜는 frontmatter 에만.

이유: 순서가 URL 에서도 직관적, 3자리로 999개까지 커버.

4. Phase 단계

Phase 0 — 결정 ✅ (2026-04-21 확정)

  • Thread 7개: universe / entry / exit / ensemble / grid-search / catalyst / regime
    (price-filter 는 universe spec 에 흡수 — 완전한 filter 명세 하나가 universe)
  • ID 스키마 NNN-slug (3자리 순번)
  • 이주 전략 점진 (B)
  • 새 루트 경로: projects/biolode-backtest/research/
  • bioreport 사이트 통합: /threads/ 섹션 추가 (기존 /research/ 와 병행)

Phase 1 — Foundation (1~2일)

목표: 새 실험을 이 시스템으로 시작할 수 있는 최소 기반.

  • research/EXPERIMENT_SCHEMA.md 작성 (표준 메타 명세)
  • research/THREAD_GUIDE.md 작성 (thread 관리 규칙, README 템플릿)
  • research/threads/<7개>/README.md 초안 (현재 알려진 best 로 채움)
  • research/scripts/snapshot_universe.py — universe builder wrapper. 호출하면:
    • spec 로드 → 종목 계산 → snapshots/<spec>_<date>.csv 저장 + hash
    • 동일 date/spec 이 있으면 skip
  • 기존 biotech/backtest/ universe builder 에 --save-snapshot flag 추가 (코드 수정 최소)
  • 첫 snapshot 생성: V3_2026-04-21.csv (현재 종목 리스트)

Phase 2 — Tooling (1~2일)

목표: 실험이 쌓이기 시작할 때 바로 쓸 수 있는 도구들.

  • research/scripts/compare.py MVP
    • 입력: 실험 ID 2개
    • 출력: 4필드 diff, 공정성 판정, 주요 metric 차이
  • research/scripts/lint.py
    • 각 실험이 표준 메타 갖췄는지
    • snapshot_id 가 실재하는지
    • decisions.md 가 최신인지 (optional)
  • 실험 README 템플릿 파일 (research/TEMPLATE_EXPERIMENT.md)
  • research/meta/roadmap.md 초안 (Dan 이 다음에 팔 것들)
  • research/meta/kpi.md (현재 v11 수준 baseline + 목표치)

Phase 3 — Dogfooding (1주)

목표: v13.3 (profit-gated time stop) 을 새 시스템으로 실행 → 실전 검증.

  • threads/exit/experiments/007-profit-gated-time-stop/ 생성
  • 표준 메타 + config + 실행 + README 작성
  • Snapshot 파이프라인 통해 universe pin
  • v11 best exit (005-fixed-70-30-180) 과 compare.py 돌려 비교
  • 결과 Thread README (exit/README.md) 에 업데이트
  • 발견된 friction 있으면 Phase 1/2 다듬기

Phase 4 — Backport (1주, 점진적)

목표: 과거 중요 실험을 새 구조에 태깅.

우선순위 순서:

  1. v11 의 5개 엔트리 → threads/entry/001~005/ 재생성
  2. v11 의 5개 exit → threads/exit/001~005/
  3. research_exit / research_exit_v2 → threads/exit/006~...
  4. grid_search_v1~v8 → threads/grid-search/001~005/
  5. research_* → 각 thread 로 분산
  6. phase_c_reversal → threads/entry/
  7. pattern_entry_research_v1 → threads/entry/

각 backport 는 원본 파일 건드리지 않고 research/threads/... 에 README + config + metrics 만 생성 (실제 results 는 기존 경로 링크).

소급 불가한 것 (universe snapshot 복원 못 함) 은 universe_snapshot: UNKNOWN 표기 + caveat.

Phase 5 — Site Integration (1일)

목표: bioreport.hyooni.io 에서 새 구조 노출.

  • quartz/build-content.sh 에 research/threads/ → /threads/ 매핑 추가
  • research/versions/ → /versions-new/ (기존 /versions/ 와 병행)
  • Home (index.md) 에 새 섹션 링크 추가
  • 탐색기 네비 정돈 (Dan 이 쓰는 순서대로 우선순위)
  • Mobile UI 점검

Phase 6 — Ongoing (상시)

  • 새 실험 → 이 시스템으로만
  • Thread README 주 1회 업데이트 (Open Questions, 최근 결과)
  • roadmap.md 월 1회 리뷰
  • 기존 backport 는 시간 날 때 조금씩

5. Deliverables 체크리스트

코드 / 스크립트

  • research/scripts/snapshot_universe.py
  • research/scripts/compare.py
  • research/scripts/lint.py
  • Universe builder --save-snapshot flag

문서

  • research/EXPERIMENT_SCHEMA.md
  • research/THREAD_GUIDE.md
  • research/TEMPLATE_EXPERIMENT.md
  • 7개 thread README
  • research/meta/roadmap.md
  • research/meta/kpi.md

사이트

  • quartz/build-content.sh 업데이트
  • bioreport 재배포

Dogfood

  • v13.3 실험 새 시스템으로 완료
  • compare 결과 첫 사례 저장

6. 리스크 / 열린 이슈

🟡 R1. Universe snapshot 복원 못 하는 과거 실험

  • 원인: 당시 universe 는 code 가 매 실행마다 새로 생성했고 별도 저장 안 됨
  • 영향: backport 시 상당수 실험이 universe_snapshot: UNKNOWN 됨
  • 완화: UNKNOWN 도 명시적 표기. 적어도 ‘universe 불명확’을 알 수 있게 함. 미래 실험은 문제 없음

🟡 R2. Thread 경계 모호

  • 예: reversal_pattern_research 는 entry thread? 또는 별도 pattern thread?
  • 완화: 일단 제일 가까운 thread 에 넣고, 수 늘어나면 분리. README 에 aliases: [pattern] 로 검색 가능하게

🟡 R3. 이중 구조로 혼란

  • research/ (새) 와 기존 파일들 (biotech/results/, docs/studies/) 이 한동안 공존
  • 완화:
    • 새 실험은 무조건 research/
    • 기존 파일은 읽기 전용 으로 취급, 참조만
    • Phase 4 backport 완료 시점에 기존 파일에 status: archived 태그

🔴 R4. Scope creep

  • 기획서 자체가 커지면서 “thread 자동 리포트 생성”, “실험 dependency graph 시각화” 같은 아이디어로 번질 위험
  • 완화: Phase 1~2 까지는 최소 기능. 3 부터 실전 쓰면서 필요한 것만 추가

7. 성공 기준

3개월 뒤 (2026-07-21) 다음 질문에 < 1분 안에 답 가능:

  1. “v11 에서 fixed_70_30_180 을 최종 선택한 이유는?” → exit thread decisions.md
  2. “003-chandelier-atr 와 005-fixed-70-30-180 을 공정 비교하면?” → compare.py 즉시
  3. “지금 팔고 있는 열린 질문은?” → roadmap.md + thread README Open Questions
  4. “2026-03-15 V3 universe 는 몇 종목이었고 지금과 어떻게 다른가?” → snapshots/ diff
  5. “exit 에서 새 실험 하나 추가하려면?” → TEMPLATE_EXPERIMENT.md 복사 + 번호 할당

8. Phase 0 — 확정됨 (2026-04-21)

모두 confirmed. Phase 1 착수 중.

그래프 뷰

백링크