프론트엔드 아키텍처 마이그레이션 (VSA 하이브리드)
2026년 4월Frontend Developer주식회사 루멘테라
Next.js (App Router)ReactTypeScriptNode.js CLIPlaywrightGitHub Actions
Overview
수백 개 파일 규모의 프론트엔드 구조를 재설계했습니다. 후보 4안을 비교한 뒤 의존성을 전수조사해 교과서적인 정답(완전한 Vertical Slice)을 근거와 함께 기각하고, 하이브리드 구조를 택했습니다.
기능이 늘면서 관련 코드가 레이어별로 흩어져 변경 영향 범위를 예측하기 어려웠습니다. FSD·Screaming Architecture·Vertical Slice·점진적 하이브리드 네 가지를 비교했고, 여기서 멈추지 않고 실제 hooks·types·api가 몇 개의 라우트에서 쓰이는지 전수조사했습니다. 그 결과 '완전한 코로케이션'이 이 코드베이스에서는 불가능하다는 사실이 드러나 하이브리드로 방향을 정했고, 정한 규칙은 검증 CLI로 만들어 CI에 고정했습니다.
Challenges & Solutions
어떤 구조를 택할 것인가 — 후보 4안 비교
Before
기능 추가마다 컴포넌트·훅·타입·API가 레이어별로 흩어져, 하나를 고칠 때 무엇이 영향을 받는지 예측하기 어려운 구조
After
- FSD / Screaming Architecture / Vertical Slice / 점진적 하이브리드 4안을 App Router 호환성·마이그레이션 비용·현재 구조와의 거리 기준으로 비교
- 이미 라우트 코로케이션이 적용돼 있던 웨비나 화면을 실증 사례로 삼아 Vertical Slice를 유력안으로 선정
교과서적인 정답을 그대로 적용할 수 없었던 이유
Before
'모든 코드를 라우트 안으로 모은다'는 원칙을 그대로 따르면 되는 것처럼 보였던 상황
After
- hooks·types·api가 실제로 몇 개 라우트에서 쓰이는지 전수조사 실시
- hooks는 65%가 여러 라우트를 가로지르고, types는 100%가 전역 선언이라 물리적으로 이동조차 불가능함을 확인
- → 완전한 Vertical Slice를 근거와 함께 기각. 컴포넌트만 라우트에 코로케이션하고 hooks·types·api는 공통 레벨에 유지하는 하이브리드 채택
수백 개 파일을 깨뜨리지 않고 옮기기
Before
한 번에 옮기면 회귀를 잡을 방법이 없고, 어디서 깨졌는지 특정하기도 어려운 규모
After
- 이동 전에 라우트 스모크 테스트 27개를 먼저 만들어 회귀 안전망 확보 (27/27 통과 유지)
- 네이밍 정규화 → 단일 파일 → 다중 파일 → 도메인별 → 정리 순으로 Phase를 나눠 티켓 11개로 분할 진행
- 컨테이너 약 92개·공통 모달 import 121곳·상대경로 27곳을 단계적으로 이관
- 이동 과정에서 방치돼 있던 미사용 파일과 라우트를 함께 정리
컨벤션을 코드리뷰에만 맡기지 않기
Before
폴더 구조와 의존 방향 규칙이 리뷰어의 기억에 의존해, 시간이 지나면 다시 무너질 수밖에 없는 상태
After
- 라우트 간 직접 import 금지·비표준 네이밍 금지·상대경로 금지 등 7개 규칙을 검증하는 CLI를 직접 구현
- PR마다 자동 실행되는 검사로 배선해 규칙 위반이 머지되지 않도록 고정
- 실제 운영해 보니 일부 규칙은 정상 패턴까지 잡아내어, 해당 규칙은 ERROR에서 WARN으로 재조정
Impact
수백 개
미사용 파일·라우트 정리 포함
마이그레이션 대상 TS/TSX 파일
상시 검증
모든 PR
아키텍처 규칙 자동 검증
0 errors
라우트 스모크 27/27 통과
7규칙 검증 통과 상태 유지