yim2412.github.io

개발 노트 허브. https://yim2412.github.io

만들면서 무엇이 어떻게 깨졌고 어떻게 알아냈는지를 적은 노트들을 프로젝트별로 모으고, 두 프로젝트 이상에서 같은 모양으로 나온 것을 주제별로 다시 묶는다.

왜 페이지가 하나인가

노트는 각 프로젝트 저장소의 docs/notes/ 에 있고, 이 페이지는 링크만 모은다. 노트 본문을 여기로 복사하지 않는다 — 복사하는 순간 다섯 벌 관리가 시작되고, 어느 쪽이 최신인지 알 수 없게 된다.

왜 두 프로젝트를 쓴 뒤에 만들었나

하나만 있을 때 만들면 그 프로젝트 전용 틀이 되고, 다섯 개를 다 쓴 뒤에 만들면 페이지를 다섯 벌 만들어 놓고 다시 뜯어고치게 된다. 둘이면 공통 요소가 추측이 아니라 관찰로 나온다.

실제로 그랬다. 장르도 언어도 다른 두 프로젝트에서 같은 모양이 넷 겹쳤다 — 통과는 증거가 아니다 · 기능이 아니라 측정이 틀렸다 · 한 번도 돌지 않은 것이 오래 살아남는다 · 안 여는 문서가 썩는다.

세 번째(Argus)를 얹으며 그 판단이 검증됐다 (2026-09-05). 노트 셋이 전부 기존 주제에 붙었고 새 주제는 하나도 안 생겼다. 넷이 두 사례가 아니라 세 사례로 두꺼워졌을 뿐이다 — 틀을 다시 짤 필요가 없었다는 것이 이 순서를 고른 이유였다.

네 번째(피파)에서 새 주제가 둘 생겼다 (2026-09-05). 「조용히 실패한다」와 「화면이 본문과 다른 말을 한다」 — 둘 다 Argus 에서 이미 두껍게 나왔던 것인데, 그때는 한 프로젝트짜리라 올리지 않고 기존 주제에 사례로만 붙여 뒀다. 피파가 두 번째 사례를 내면서 조건이 찼다. 규약이 실제로 일한 자리다 — Argus 때 성급히 올렸으면 지금 그 주제가 한 프로젝트 이야기로 남아 있었을 것이다.

세 번째 후보(「우연히 같은 값이 검증을 통과시킨다」)도 사례가 둘 생겼지만 만들지 않았다. 한쪽은 설정 배선(코드·YAML 기본값이 같아 배선이 끊겨도 참), 한쪽은 통계 표본("합계"와 "평균×100"이 100경기에서 같은 값)이라 성질이 꽤 다르다 — 묶으면 억지가 된다. 세 번째 사례가 나오면 그때 다시 본다.

다섯 번째(RL3D)에서 하나 더 생겼다 (2026-09-05). 「공개 저장소에 남의 것이 올라간다」 — 피파와 RL3D 둘 다 회귀 테스트 픽스처였다. 실제 응답을 그대로 두는 것이 골든 테스트의 가치인데, 그 실제 응답에 제3자 정보가 섞여 있다. 답이 갈린 것도 같이 적었다 — RL3D 는 생성 스크립트를 고쳤고(안 고치면 다음 갱신에 돌아온다), 피파는 생성 스크립트가 없어 익명화 규칙을 docstring 에 적었다.

세 번 다 같은 모양이었다. 새 주제 셋(조용히 실패한다 · 화면이 본문과 다른 말을 한다 · 공개 저장소에 남의 것이 올라간다)은 전부 한 프로젝트에서 먼저 두껍게 나왔지만 그때는 안 올린 것이고, 두 번째 사례를 만나서야 조건이 찼다. 그 사이의 기다림이 이 규칙의 값이다.

노트 규약

프로젝트마다 같다. 규약이 같아야 이 페이지가 긁을 때 규칙이 하나로 끝난다.

파일 위치	docs/notes/NN-slug.md (번호 2자리, 슬러그는 영문 케밥)
목록	docs/notes/README.md — 노트 표 하나
제목	무엇이 틀렸는지로 시작한다
헤더	프로젝트 · 날짜 · 근거 커밋 링크
수치	실측(지금 다시 잼)과 인용(그때 그렇게 적혀 있음)을 구분
끝	「이 건에서 남긴 규칙」 + 근거 표

현재

프로젝트	노트	저장소
Domynion	7편	domynion
합동 통합방어 시뮬레이터	3편	joint-defense-sim
Argus	3편	Argus
피파 전적 관리	2편	fifa-match-tracker ⚠️ 기본 브랜치가 master
RL3D	2편	RL3D

고칠 때

index.html 하나뿐이다. 외부 의존이 없고 빌드 단계도 없다 — 열어서 고치고 커밋하면 GitHub Pages 가 배포한다. 새 프로젝트를 얹을 때 손대는 곳은 셋이다:

1. 주제별 색인 — 그 노트가 기존 주제에 붙는지 본다. 새 주제는 두 프로젝트 이상에서 나왔을 때만 만든다(하나짜리 주제는 그 프로젝트 이야기지 공통이 아니다)
2. 프로젝트 카드 — 노트 목록을 채운다. (.soon 블록은 다섯 프로젝트가 다 공개돼 비었다 — CSS 는 남겨 뒀으니 새 프로젝트가 생기면 그때 다시 쓴다)
3. 머리말 개수 — 노트 편수·프로젝트 수