혼자 플랫폼을 만들며 힘들었던 것들

가족용 블로그 하나 띄우는 데 238커밋을 썼어요. 그중 절반쯤은 기능이 아니라 경계를 긋는 데 들어갔고요.

아키텍처와 성능 얘기는 앞의 글들에서 다 했으니, 오늘은 혼자 개발하면서 진짜 힘들었던 것들 얘기예요. 코드 말고, 사람 얘기요.

용어가 흔들리면 코드도 흔들린다

혼자 개발하면 용어를 협의할 상대가 없어요. 그래서 오히려 더 쉽게 흔들립니다. 초기에 가장 오래 저를 괴롭힌 건 Registry와 Repository였어요. 플러그인이 renderer를 등록하는 곳도 "저장소"고, 사용자가 쓴 글이 저장되는 곳도 "저장소"거든요. 어떤 날은 확장 지점을 Repository라고 부르고, 어떤 날은 콘텐츠 저장 경계를 Registry라고 불렀어요. 같은 사람이 쓴 코드인데 파일마다 같은 단어가 다른 걸 가리켰고, 리팩터링할 때마다 "이 Registry는 어느 쪽이지"를 다시 추적해야 했습니다.

해결은 코드가 아니라 문서였어요. CONTEXT.md에 도메인 용어집을 만들고, 각 용어에 정의와 함께 금지어(_Avoid_)를 못 박았습니다.

**Registry**:
무엇을 만들고 확장할 수 있는지를 보관하는 typed extension 저장소.
_Avoid_: Repository

**Repository**:
사용자가 실제로 만든 Workspace, Site, ContentResource,
Release 같은 데이터를 저장하는 경계.
_Avoid_: Registry

"Registry는 확장 가능성을, Repository는 실제 생성 데이터를 다룬다"는 한 줄이 생기고 나서야 새 코드에서 이름 고민이 사라졌어요. 혼자여도 — 아니, 혼자라서 더 — 용어는 문서로 고정해야 하더라고요.

순서와 경합은 항상 예상 밖에서 터진다

혼자 만든 시스템에서도 동시성 버그는 나와요. 다만 남이 만든 경합이 아니라, 과거의 내가 심어둔 경합이라는 점이 다르죠.

(원망할 사람도 저뿐입니다.)

"CI가 이상하다"의 진실

각 패키지의 prebuild 스크립트가 편의상 다른 패키지의 빌드 출력을 대신 만들어주고 있었어요. 이건 Nx 의존성 그래프 밖의 일이라, 병렬 검증이 돌면 두 작업이 같은 출력 디렉터리를 동시에 건드렸죠. 증상은 어이없게도 .d.ts 선언 파일이 중간에 잘려 있는 것. 로컬에서는 재현이 안 되고 CI에서만 간헐적으로 터지니, 한동안 "CI가 이상하다"고 생각했습니다.

결국 16개 패키지에서 교차 패키지 prebuild를 전부 걷어내고, "다른 프로젝트의 출력을 생성하지 않는다"는 규칙을 워크스페이스 의존성 검사 스크립트에 기계화해서 넣었어요. 사람이 기억할 규칙은 언젠가 잊히니까, 규칙은 검사기로 만들어야 재발하지 않아요.

실패 이후의 시간 순서

글 생성이 한 번 실패하면 그 오류 상태가 에디터 애플리케이션에 남아서, 이후의 모든 게시 요청을 영구히 차단하는 버그도 있었어요. 실패한 건 생성 하나인데 사이트 전체 게시가 멈춘 거예요. 수정 자체는 5줄이었습니다. 오류의 유효 범위를 "진행 중인 생성"으로 좁히면 끝. 그런데 회귀 테스트는 74줄을 썼어요.

(수정 5줄에 테스트 74줄. 비율이 이상해 보이지만, 맞는 비율이에요.)

이런 버그의 공통점은 코드 한 줄이 아니라 "실패 이후의 시간 순서"를 설계하지 않은 데서 온다는 거예요.

문서 먼저 쓰는 습관, 그리고 과잉 설계라는 자문

이 프로젝트는 스펙과 플랜 문서를 먼저 쓰고 구현하는 방식으로 진행했어요. ADR만 16편이에요. 얻은 건 분명합니다. Draft/Release 분리나 저장 buffer의 flush 정책 같은 결정은, 코드로 먼저 달려들었다면 두 극단 중 하나를 골랐다가 갈아엎었을 거예요. 문서에서 대안을 기각하는 이유를 적다 보면 세 번째 길이 보이는 경우가 많았어요. 그리고 몇 주 뒤의 나는 사실상 타인이라, "왜 이렇게 했더라"의 답이 문서에 있다는 것만으로 재작업이 크게 줄었습니다.

비용도 분명해요. 기능 하나에 문서-구현-검증 사이클이 붙으니 절대 속도는 느려요. 별도 편집 화면을 만들었다가 약 2,000줄을 통째로 버리고 동일 URL 편집으로 다시 쓴 적도 있고요. 문서를 먼저 썼는데도 방향 전환이 있었던 셈이죠.

그래서 "가족 블로그 하나에 이게 과잉 설계 아닌가" 자문을 여러 번 했어요. 지금의 답은 이래요. 블로그가 목적이었다면 과잉이 맞아요. 하지만 목적은 두 번째, 세 번째 사이트를 플랫폼 코드 수정 없이 올리는 거고, 그 검증은 아직 남아 있어요. 다만 기준은 정해뒀습니다. 플랫폼 패키지에 if blog 분기가 생기거나 두 번째 제품에서 플랫폼이 크게 바뀌면 이 설계는 실패. 과잉인지 아닌지는 지금 판정할 수 없고, 판정 조건을 미리 적어두는 것까지가 지금 할 수 있는 최선이었어요.

238커밋을 돌아보면, 힘들었던 건 어려운 알고리즘이 아니었어요. 이름을 정하는 일, 실패 이후를 설계하는 일, 그리고 속도를 스스로 늦추는 결정을 견디는 일이었습니다.