FSD 마이그레이션 가이드: 기존 프론트엔드 구조를 단계적으로 전환하는 순서

FSD 마이그레이션 가이드: 기존 프론트엔드 구조를 단계적으로 전환하는 순서

기존 프로젝트를 한 번에 FSD로 재구성하면 리스크가 크다. 기능 단위로 경계를 만들고 import 규칙을 강화하는 점진 전환이 현실적이다. 검색 유입이 많은 키워드(폴더 구조, 마이그레이션, 안티패턴, 상태관리)를 기준으로 실무 적용 포인트를 정리했다.

FSD 공식 사이트 참조 이미지 (출처: feature-sliced.design)

핵심 개념

실무에서 먼저 결정할 기준

이 주제는 코드 배치 기준을 먼저 정하고, 이후 네이밍과 import 경계를 린트로 고정하는 순서가 가장 안정적이다.

핵심 요소 3~6개

항목	의미	언제 쓰는지(실무 상황)
Step 1	현재 구조 의존성 진단	순환 참조와 공통 모듈 과밀 구간을 식별할 때
Step 2	shared/ui와 shared/lib 분리	가장 재사용 빈도가 높은 공통 코드부터 정리할 때
Step 3	핵심 기능 1개를 features로 이관	변경 영향이 제한된 영역에서 시범 전환할 때
Step 4	entities 도입 및 모델 정리	도메인 타입/모델 중복을 통합할 때
Step 5	린트로 public API import 강제	구조 회귀를 막고 팀 규칙을 자동 검증할 때

예시 코드

eslint rule example:
import/no-internal-modules: ["error", {"forbid": ["**/features/*/*"]}]
allowed: features/auth/index.ts only

문제 상황 1개

상황: 대규모 리팩터링 브랜치가 길어져 머지 충돌이 폭증한다.
원인: 전환 범위를 한 번에 넓게 잡아 릴리스 사이클과 분리됐다.
해결: 기능 단위로 작은 PR을 연속 적용하고 각 단계별 안정화 테스트를 수행한다.
예방 팁: 마이그레이션 로드맵에 완료 기준(coverage, import 규칙, 문서화)을 수치로 정의한다.

참고/출처

공식 문서: FSD Migration Guide
공식 문서: ESLint Documentation
신뢰 자료: Martin Fowler - Refactoring mindset