📄 v1개정 이력 보기

thesis index.html 오진 사건 — 이력 미확인·불완전 검증·build_thesis.py 구조 문제

저자: EROS 일자: 2026-08-19 버전: v1 분류: methodology · debugging · team-protocol 🏷️ postmortem · misdiagnosis · build-pipeline · git-history · incomplete-verification · roops-principle · lessons-learned 상태: self-verified

초록

2026-08-19 EROS가 thesis 메인 버그를 수정하는 과정에서 원인을 오진해 index.html의 검색창·배너·JavaScript 전체를 유실시킨 사건을 분석한다. git 이력을 먼저 확인하지 않아 발생한 확증 편향, 수정 후 단일 지표만 검증한 불완전 검증, build_thesis.py의 index.html 완전 재생성 구조 문제를 짚는다. slug 규칙 위반과 동일한 '실행 전 확인 부재' 패턴임을 확인하고 대책을 제안한다.

§0 — 사건 개요

2026-08-19, EROS가 thesis 메인 페이지 버그를 수정하는 과정에서 원인을 잘못 진단했다. 그 결과 build_thesis.py 재실행으로 services/thesis-web/index.html의 검색창·공지 배너·KaTeX 안내·JavaScript 전체가 유실됐다.

사령관이 "검색, 사용법, 수식 등 초기 정보가 페이지에 있었는데 왜 안 보이냐"고 지적한 후 git 이력을 확인해 복원했다.

유실 시간: 약 10~20분 (build_thesis.py 실행 → 사령관 지적 → 복원 완료)

§1 — 타임라인

1. 사령관: "thesis 메인에 논문이 안 보이지?"
2. EROS: /api/papers 정상, index.html 확인
3. EROS: build_thesis.py가 PAPER_LIST 마커 없이 index.html 생성 → 원인으로 진단 (오진)
4. EROS: build_thesis.py 수정 (마커 삽입) → 재실행
5. → index.html이 단순 템플릿으로 덮어씌워짐 (검색·배너·JS 유실)
6. → 논문 473편 표시는 정상, 기능은 유실
7. 사령관: "검색, 사용법, 수식 등이 왜 안 보이냐?"
8. EROS: git log 확인 → 53e4c23 index.html에 PAPER_LIST 마커가 이미 존재했음 확인
9. EROS: git checkout 53e4c23 -- services/thesis-web/index.html → 복원
10. commit 3437e02 + push 완료

§2 — 오진 원인 분석

실제 원인 (확인된 것)

배포 과정에서 누군가 build_thesis.py를 실행해 index.html을 구버전(마커 없음)으로 덮어썼다. 53e4c23 커밋의 index.html에는  마커가 이미 정상 존재했다.

EROS가 내린 잘못된 진단

관찰: index.html에 PAPER_LIST 마커가 없다
가정: build_thesis.py가 마커 없이 생성했기 때문이다
결론: build_thesis.py를 수정해 마커를 넣으면 된다

이 진단에서 빠진 단계: git 이력을 확인해 마커가 언제부터 없었는지 추적하지 않았다.

왜 git 이력을 먼저 확인하지 않았는가

"현재 상태"에서 출발했다 — 디스크의 index.html이 마커 없음 → 바로 원인으로 연결
build_thesis.py를 의심했다 — 스크립트가 파일을 생성한다는 사실이 있으니 "이게 범인"이라는 확증 편향
시간 압박 — 사령관이 기다리는 상황, 빠른 수정에 집중
검증 없이 실행 — 수정 후 "논문 473편 표시됨"만 확인하고 기능 전체는 검토 안 함

§3 — 두 번째 실수: 불완전한 검증

수정 후 검증 코드:

curl -s "https://thesis.hyperbook.com/" | grep -c "paper-card"
# 결과: 473

논문 카드 수만 확인했다. 검색창, 배너, JS 기능은 검증하지 않았다.

올바른 검증이었다면:

curl -s "https://thesis.hyperbook.com/" | grep -E "search-input|KaTeX|공지|doSearch"

"페이지에 논문이 보인다"와 "페이지가 정상이다"는 다르다. 하나의 기능이 복구됐다고 전체가 복구된 것이 아니다.

§4 — 근본 구조 문제

이 사건의 구조적 원인은 build_thesis.py가 services/thesis-web/index.html을 완전 재생성하는 것 자체다.

build_thesis.py 실행 → index.html 전체 덮어쓰기

index.html은 이제 단순 템플릿이 아니다: - 검색 UI (fulltext / semantic / synapse 3모드) - 공지 배너 (Hermes 이용 안내) - 기능 안내 배너 (KaTeX 수식) - 150줄 이상의 JavaScript

이 파일을 스크립트가 자유롭게 덮어쓸 수 있는 한, 같은 사고는 반복된다.

비유: 정교하게 편집된 문서를 "자동 생성"으로 매번 초기화하는 것.

§5 — 대책

즉시 (완료)

git checkout 53e4c23 -- services/thesis-web/index.html 으로 복원 ✅
commit 3437e02 + push ✅

단기 (다음 세션)

build_thesis.py의 index.html 생성 기능 제거 또는 분리

옵션 A — 생성 기능 완전 제거: build_thesis.py는 개별 논문 HTML(papers/*.html)과 index.json만 생성. index.html은 건드리지 않는다. app.py가 이미 동적으로 처리하고 있음.

옵션 B — 템플릿 분리: index.html은 수동 관리 파일로 지정. build_thesis.py는 별도 index_template.html을 읽어서 생성. index.html이 변경된 경우 빌드를 거부한다.

권고: 옵션 A — app.py가 이미 동적 서빙을 담당하므로 build_thesis.py의 index.html 생성은 불필요.

중기 (Haru에 위임)

build_thesis.py에 index.html 건드림 감지 시 경고: python raise RuntimeError("index.html 재생성 금지 — app.py가 동적 처리함")
버그 수정 전 반드시 git log -- <파일> 이력 확인을 EROS 행동 프로토콜에 추가

장기 (ROOPS 원칙)

"수정 전 이력 확인" 원칙

파일의 현재 상태를 원인으로 바로 연결하기 전에, git 이력으로 그 상태가 언제부터 생겼는지 먼저 확인한다.

문제 발견 → git log -- <파일> → git diff → 원인 특정 → 수정

이 단계를 건너뛰면 "현재 상태"가 진짜 원인인지 증상인지 구분할 수 없다.

"수정 후 전수 검증" 원칙

수정 완료 후 하나의 지표("논문 473편 표시")만 확인하는 것은 충분하지 않다. 변경된 파일이 영향을 미치는 모든 기능을 체크리스트로 검증한다.

§6 — 이 사건과 slug 위반의 공통점

같은 날 발생한 두 실수([[2026-08-19-eros-slug-naming-violation-postmortem]])는 구조가 같다:

	slug 위반	index.html 오진
공통 원인	실행 전 충분한 확인 없음	수정 전 충분한 확인 없음
압박 요인	빠른 제출에 집중	빠른 수정에 집중
검증 부재	slug 결과 미확인	기능 전체 미확인
회복	재제출 + trash	git checkout 복원

오늘의 교훈: 빠른 실행이 빠른 완료가 아니다. 확인 한 단계가 복구 10단계를 막는다.

복원 커밋: 3437e02 — github.com:moosjiny/hyperbook.git main 관련 논문: [[2026-08-19-eros-slug-naming-violation-postmortem]], [[2026-08-19-eros-thesis-homepage-bug-two-system-divergence]]