대규모 화면 개발에서 마주한 파일 영향 범위 추적의 한계
여기어때 서비스웹개발팀 정용욱 개발자는 기술블로그를 통해 대규모 항공 프론트엔드 프로젝트를 진행하며 겪은 디렉터리 구조 관리의 난점을 공개했습니다. 해외선 예약 상세와 같이 기능과 컴포넌트가 방대해지는 화면에서는 단일 폴더 안에 수십 개의 파일이 집중되는 현상이 발생했습니다.
이 과정에서 특정 컴포넌트를 수정하거나 삭제할 때 해당 파일이 특정 팝업 내부에서만 쓰이는지, 화면 전체 혹은 다른 화면에서도 참조되는지 파일명만으로는 식별할 수 없는 문제가 지적되었습니다. 결과적으로 파일 하나를 변경할 때마다 프로젝트 전체 검색을 반복해야 했고, 기존 컴포넌트의 공유 가능 여부를 판단하기 어려워 유사한 코드가 중복 생성되는 비효율이 이어졌습니다.
표준 방법론 FSD의 한계와 실무 현장의 타협
문제 해결을 위해 팀 내부에서는 널리 알려진 프론트엔드 아키텍처 표준인 기능 분할 설계(Feature-Sliced Design, FSD) 도입이 논의되었습니다. FSD 공식 사양에 따르면 코드는 app, pages, widgets, features, entities, shared 등의 명확한 계층(Layers)으로 나뉘며, 상위 계층이 하위 계층만 참조하는 단방향 의존성 규칙을 강제합니다.
그러나 실제 개발 일정과 팀 환경에서는 전면 도입이 보류되었습니다. 신규 파일을 생성할 때마다 해당 코드가 entity인지 feature인지 분류 기준을 지속적으로 합의해야 하는 인지 부하가 존재했습니다. 또한 급박한 릴리스 일정 속에서 팀 전체가 아키텍처 규칙을 숙지하고 기존 코드를 마이그레이션하기에는 시간적 제약이 컸다는 설명입니다.
참조 범위로 단순화한 세 가지 접두어 규칙
여기어때 팀은 '역할의 종류' 대신 '누가 사용하는가(참조 범위)'만을 기준으로 삼는 단순화된 규칙을 도출했습니다. 핵심은 특정 파일에 종속된 전용 리소스 폴더에 더하기 기호(+)를 붙이는 방식입니다. 예를 들어 RequestCancel.tsx의 하위 종속 파일들은 +RequestCancel/ 폴더에 격리하여, 부모 파일이 삭제될 때 해당 폴더 전체를 안전하게 함께 제거할 수 있도록 했습니다.
한 화면 내부에서 복수 컴포넌트가 공유하는 리소스에는 언더스코어(_)를 붙여 _hooks, _ui, _widget 등으로 관리했습니다. 둘 이상의 독립 화면에서 참조하는 요소는 최상위 shared/ 폴더로 승격시켰으며, 순수 뷰 컴포넌트(shared/ui)와 자체 데이터 패칭 로직을 갖는 모듈(shared/widget)로 구분해 재사용 위치의 제약을 명확히 했습니다.
인지 비용 절감과 재귀적 구조가 주는 실무적 이점
이 방식의 주요 장점은 구조적 판단의 기준을 극단적으로 단순화했다는 점입니다. FSD가 레이어와 슬라이스라는 다차원 축을 통해 코드를 분류하는 반면, 접두어 규칙은 현재 파일을 참조하는 대상의 개수만 파악하면 되므로 팀원 간의 소통 비용과 초기 학습 곡선을 낮출 수 있습니다.
또한 화면 단위의 대칭성을 확보하기 유리합니다. 국내선과 해외선 등 도메인 구조가 유사한 서비스에서 동일한 네이밍 규칙을 반복 적용할 수 있어 다른 영역을 작업할 때도 예측 가능성이 높아집니다. 깊은 계층으로 들어가더라도 동일한 규칙이 재귀적으로 동작하므로 컴포넌트 간의 종속 관계가 디렉터리 경로에 직접적으로 투영됩니다.
강제 도구 부재와 디렉터리 심도 심화라는 기술적 과제
하지만 이 접근법이 완전한 아키텍처 대안으로 기능하기 위해서는 몇 가지 기술적 제약을 점검해야 합니다. FSD는 eslint-plugin-boundaries 등 정적 분석 린터를 통해 레이어 간 참조 방향을 컴파일 또는 빌드 타임에 엄격히 차단할 수 있습니다. 반면 접두어 기반 방식이 단순 컨벤션에만 머무를 경우, 개발자의 실수로 인한 잘못된 import 참조를 기계적으로 방지할 수 있는지 검증이 필요합니다.
또한 복잡한 화면일수록 폴더의 중첩 깊이(depth)가 물리적으로 깊어지면서 경로 추적과 탐색의 복잡성이 커지는 한계가 존재합니다. 코드 중복 감소율이나 유지보수 비용 개선에 대한 정량적 수치가 함께 검증되지 않은 만큼, 도메인 특성과 조직 규모에 맞춰 자동화 린트 규칙 결합 여부 등을 신중히 검토한 뒤 도입하는 과정이 요구됩니다.
출처
여기어때 기술블로그의 원출처와 본문에 표시한 참고자료를 바탕으로 한국어로 재구성했습니다. ‘ARCH.B 분석’은 자료를 읽고 덧붙인 편집 해석입니다.
항공 프론트엔드 구축기 (10/10): 폴더 이름 앞의 기호 하나 (새 창)
