토스테크

안녕하세요, 토스코어 Business Onboarding Team 프론트엔드 개발자 조성륜입니다.
토스팀에 합류하고 처음 받은 과제는 판매자 입점 퍼널을 이해하는 것이었습니다. 판매자 입점 퍼널은 판매자가 토스페이에 가입하는 과정을 말해요.
"이 페이지 다음에 어디로 가요?"
"음... 조건에 따라 달라요. 코드 보시면..."
39개의 페이지 파일을 하나씩 열어보며 며칠을 보냈습니다. 파일을 열 때마다 이런 코드가 나왔어요.
39개 페이지가 82개의 서로 다른 조건으로 연결되어 있었습니다. 한 페이지에서 평균 2개 이상의 분기가 있는 셈이죠. 판매자 본인이 직접 신청하는지(대표자), 위임받은 사람이 신청하는지(대리인), 개인사업자인지 법인사업자인지, 본인인증 결과가 어떤지에 따라 경로가 달라졌습니다.
그리고 생각했어요.
"어차피 코드에 다 있는 정보인데, 자동으로 문서를 만들 수 없을까?"
이 글에서는 코드를 분석해서 '절대 Outdated 되지 않는 퍼널 문서'를 만든 경험을 공유합니다.
"그 문서는 아직 최신화 안되어 있어요"
팀에 합류하고 가장 먼저 한 일은 기존 문서를 찾아보는 것이었습니다. ‘판매자 입점 퍼널 플로우’라는 문서가 있었어요. 페이지 간 연결을 화살표로 그린 다이어그램이었죠. "오, 이거 보면 되겠다!" 싶었습니다.
그런데 막상 코드를 보니 뭔가 이상했습니다.
"문서에는 A 다음에 B로 가는데, 코드에서는 C로 가네요?"
"아, 그 문서는 아직 최신화 안되어 있어요. 코드를 보셔야 해요."
알고 보니 3개월 전에 마지막으로 수정된 문서였습니다. 그 사이에 퍼널 구조가 여러 번 바뀌었지만, 문서는 업데이트되지 않은 거예요. 그래서 제가 직접 플로우차트를 다시 그려보기로 했습니다. 코드를 하나씩 읽으면서 문서에 정리했어요.
하지만 금방 한계에 부딪혔습니다.
1. 조건부 분기를 표현하기 어려웠습니다
‘대표자이면서 개인사업자일 때’는 A로, ‘대리인이면서 법인일 때’는 B로 가는 건 그림으로 그리기 복잡했습니다. 화살표에 조건을 다 적으면 다이어그램이 읽을 수 없을 정도로 지저분해졌어요.
2. 제가 그린 문서도 금방 Outdated 됐습니다
열심히 그렸는데, 3일 뒤에 다른 팀원이 퍼널에 새 페이지를 추가했습니다. 제 문서는 이미 현실과 달라져 있었어요. 매번 코드가 바뀔 때마다 문서를 수정하는 건 현실적으로 불가능했습니다.
결국 같은 문제가 반복되는 거였죠. 수기로 작성한 문서는 결국 Outdated 됩니다.
런타임 vs 정적 분석
코드에서 Navigation 정보를 추출하는 방법은 크게 두 가지입니다.
방식
설명
장점
단점
런타임 분석
실제로 코드를 실행하면서 어떤 경로로 가는지 기록
실제 동작 그대로
한 번에 한 경로만, 모든 케이스 실행 필요
정적 분석
코드를 텍스트로 읽어서 AST로 파싱
모든 경로를 한 번에, 빠르고 안전
동적 로직 파악 어려움
저희는 정적 분석을 선택했습니다.
🔍 모든 경로를 한 번에 찾을 수 있습니다: 런타임에는 조건에 따라 한 경로만 실행되지만, 정적 분석은 if문 안의 모든 분기를 찾을 수 있어요.
⚡ 빠르고 안전합니다: 실제로 코드를 실행할 필요 없이, 소스코드만 읽으면 됩니다.
📍 정확한 위치를 알 수 있습니다: "이 Navigation은 applicant.tsx의 157번째 줄에 있어요" 같은 정보를 얻을 수 있습니다.
AST(Abstract Syntax Tree)는 코드를 트리 구조로 표현한 것입니다. TypeScript 컴파일러가 코드를 이해하는 방식과 동일해요. ts-morph 라이브러리를 사용해서 소스코드를 AST로 파싱했습니다.
코드에서 퍼널 흐름을 추출하기까지
‘코드를 읽어서 Navigation을 추출한다’는 아이디어는 간단하지만, 실제로 구현하려면 여러 단계가 필요합니다. 하나씩 풀어가 볼게요.
Step 1. 분석할 페이지 파일 찾기
먼저 39개의 페이지 파일을 찾아야 합니다. Next.js 프로젝트에서 페이지는 src/pages/ 디렉토리에 있고, 각 페이지의 진입점은 index.tsx나 universal.tsx 파일입니다.
components/나 hooks/ 폴더는 페이지가 아니니까 제외합니다. _app.tsx 같은 특수 파일도 제외하고요. 이렇게 하면 순수하게 페이지 컴포넌트만 남습니다.
Step 2. Navigation Edge 데이터 구조 설계
코드를 분석하기 전에, 어떤 정보를 추출할지 먼저 정해야 했습니다. 처음에는 단순하게 ‘A 페이지에서 B 페이지로 간다’만 저장하려고 했어요.
그런데 이것만으로는 부족했습니다. 다이어그램을 봐도 왜 이 경로로 가는지, 어떤 조건일 때 가는지 알 수 없었어요. 결국 코드를 다시 찾아가야 했죠.
고민 끝에 Navigation의 맥락 정보까지 함께 저장하기로 했습니다.
각 필드를 이렇게 설계한 이유가 있습니다:
필드
왜 필요한가
method
push는 뒤로가기 가능, replace는 불가능. 사용자 경험에 영향을 주므로 구분 필요
condition
"대표자일 때만 이 경로로 간다" 같은 분기 조건을 알아야 퍼널 로직 이해 가능
queryParams
다음 페이지에 어떤 상태를 전달하는지 파악 가능
lineNumber
다이어그램에서 코드로 바로 점프할 수 있음
sourceType
페이지 직접 호출인지 훅 내부 호출인지 구분해야 디버깅이 쉬움
이 구조가 이후 모든 분석의 기반이 됩니다.
Step 3. 페이지에서 Navigation 패턴 추출하기
이제 각 페이지 파일을 AST로 파싱해서 router.push(), router.replace() 같은 Navigation 호출을 찾습니다.
핵심은 getDescendantsOfKind(SyntaxKind.CallExpression)입니다. 파일 전체에서 모든 함수 호출을 찾아온 뒤, 그중에서 router.push()나 router.replace() 패턴인지 확인합니다.
조건문(condition)은 어떻게 추출할까요? Navigation 노드를 찾으면 AST를 부모 방향으로 거슬러 올라가면서 가장 가까운 if문이나 삼항 연산자를 찾습니다.
이렇게 하면 어떤 조건일 때 이 경로로 가는지까지 알 수 있어요.
Step 4. 커스텀 훅 안에 숨어있는 Navigation 찾기
페이지 파일만 분석하면 놓치는 Navigation이 있습니다. 로직이 커스텀 훅으로 분리된 경우예요.
페이지 컴포넌트만 분석하면 이 Navigation을 놓치게 됩니다. 그래서 페이지가 import하는 훅을 역추적하는 방식을 사용했습니다.
이렇게 찾은 훅 파일을 다시 AST로 파싱해서 Navigation 호출이 있는지 확인합니다.
훅에서 Navigation을 찾으면, 해당 훅을 사용하는 페이지에서 나가는 edge로 기록합니다. 출처도 함께 기록해서 나중에 ‘이 Navigation은 훅에서 온 것’임을 알 수 있게 했어요.
Step 5. URL 상수를 실제 경로로 변환하기
여기까지 하면 Navigation edge들이 추출되는데, 문제가 있습니다. 도착지가 URLS.FUNNEL.PAY_METHOD 같은 상수 형태예요.
그래서 URL 상수 파일을 AST로 파싱해서 상수 → 실제 경로 매핑 테이블을 만듭니다.
Step 6. 그래프 구축하기
이제 모든 edge를 모아서 그래프를 만들 차례입니다. 이 과정에서 진입점과 이탈점도 자동으로 분류합니다.
Step 7. Mermaid 다이어그램 생성하기
마지막으로 그래프를 Mermaid 문법의 플로우차트로 변환합니다.
push는 단일 화살표(-->), replace는 이중 화살표(==>)로 구분합니다. 브라우저 히스토리에 남는지 여부가 다르니까, 시각적으로도 구분해주는 거예요.
완성된 다이어그램, 그리고 효과
최종적으로 생성되는 다이어그램 예시입니다.
진입점(파란색)에서 시작해서 조건에 따라 분기
이탈점(빨간색)에 도달하는 과정을 한눈에
화살표 라벨에 조건문과 쿼리 파라미터 표시
이중 화살표(==>)는 replace, 단일 화살표(->)는 push
무엇이 바뀌었나
1. 신규 입사자 온보딩 시간 단축
‘판매자 입점 퍼널이 어떻게 돌아가는지’를 설명할 때, 이제 다이어그램 하나면 충분합니다. 39개 파일을 읽을 필요 없이, 전체 흐름을 한눈에 보여줄 수 있어요.
2. 영향 범위 파악이 쉬워짐
"이 페이지를 수정하면 어디에 영향을 주지?"라는 질문에 바로 답할 수 있습니다. 다이어그램에서 해당 노드에서 뻗어나가는 화살표만 보면 되니까요. 예를 들어 신청자 정보 페이지에서는 6개의 서로 다른 경로가 있고, 각각 어떤 조건일 때 실행되는지 한눈에 파악할 수 있어요.
3. 데드엔드 발견
이탈점이 아닌데 나가는 edge가 없는 페이지(데드엔드)를 자동으로 찾을 수 있습니다. 실제로 개발 중에 실수로 Navigation을 빼먹은 페이지를 발견하기도 했어요.
4. 코드 변경과 문서 동기화
코드를 변경하면, 스크립트를 다시 실행하는 것만으로 문서가 자동으로 업데이트됩니다. 더 이상 "문서가 Outdated 됐는지" 걱정할 필요가 없어요.
마치며
신규 입사자로서 처음 마주한 39개의 페이지 파일들. "이 페이지는 어디로 연결되지?"를 파악하는 데만 며칠이 걸렸습니다. 하지만 그 경험이 이 도구를 만드는 출발점이 되었어요.
신규 입사자의 시선이 오히려 도움이 됐습니다. 팀원들에게는 익숙한 것들이, 처음 보는 사람에게는 명확한 Pain Point로 보이거든요. 그 불편함을 ‘원래 그런 거니까’로 넘기지 않고, 실제 코드베이스를 활용해 해결책을 만들 수 있었습니다.
문서화는 항상 "중요하지만 급하지 않은" 일로 밀려나기 쉽습니다. AST를 활용하면 코드가 변경될 때마다 자동으로 동기화되는, 절대 Outdated 되지 않는 문서를 만들 수 있어요.
비슷한 고민이 있으시다면, 꼭 퍼널이 아니더라도 정적 분석으로 해결할 수 있는 문제가 많습니다. 라우팅 구조, 컴포넌트 의존성, API 호출 패턴 등 코드에 있는 정보를 자동으로 추출하고 시각화 해보세요.
이 글을 읽고 궁금한 점이나 비슷한 경험이 있으시다면 댓글로 공유해주세요!

AST로 Outdated 없는 퍼널 문서 만들기

댓글