[PonsLink] 처음 열린 저장소에서 제품의 경계를 읽는 법

처음 열린 저장소를 보면 제품의 경계가 한눈에 보일 거라고 생각했다. 폴더 이름을 읽고, 기능을 분류하고, 용어 사전을 만들면 PonsLink가 무엇인지 설명할 수 있을 줄 알았다.

실제로는 반대였다. 같은 기능이 화면과 API, 연결 계층과 운영 문서에 서로 다른 이름으로 남아 있었다. 무엇을 만들었는지보다 왜 그 위치에 두었는지를 따라가야 전체 제품의 모양이 보였다.

이름보다 먼저 본 것

처음에는 용어를 정리하려 했다. 하지만 단어의 뜻을 고정하는 것만으로는 부족했다. 같은 “방”이라도 화면에서는 참가자가 들어가는 공간이고, API에서는 권한과 상태를 확인하는 경계이며, 연결 계층에서는 실시간 이벤트가 오가는 runtime이었다.

저장소를 읽을 때 기능 이름만 따라가면 이런 차이가 사라진다. 어떤 요청이 들어와 어떤 상태가 되고, 어느 시점에 세션이 열리는지 흐름을 먼저 그려야 했다.

저장소가 드러낸 제품의 층

PonsLink의 화면은 방과 요청을 보여 주고, API는 그 사이의 상태와 권한을 지킨다. 연결 계층은 실제 세션을 시작하지만, 세션이 열려야 할 이유까지 결정하지는 않는다.

이 경계를 섞으면 화면에서 버튼 하나를 누른 일이 권한 발급인지, 세션 시작인지, 단순한 요청 변경인지 설명하기 어려워진다. 저장소를 읽는 일은 파일을 분류하는 일이 아니라 책임이 겹치는 지점을 찾는 일이었다.

지도 대신 흐름을 남기다

그래서 문서에는 모든 용어를 나열하지 않고 실제 흐름을 적었다. 요청이 들어오고, 필요한 판단을 거치고, 권한이 생기고, 방이 열리고, 종료 뒤 기록이 다시 요청에 붙는 순서다.

이 흐름을 기준으로 보면 어느 코드가 제품의 결정을 담고 어느 코드가 실행만 담당하는지 구분할 수 있다. 구현을 바꿀 때도 파일 이름보다 책임을 먼저 확인할 수 있게 됐다.

마치며

처음 저장소를 읽을 때는 폴더 목록을 제품 지도라고 착각했다. 지금은 실패가 어느 경계에서 시작됐는지, 상태가 어디서 바뀌는지, 사용자에게 어떤 문장으로 보이는지를 함께 적는다. 그 세 가지가 맞아야 저장소의 구조도 제품의 구조를 설명한다.