FSD 패턴 입문: Layer·Slice·Segment 구조를 실무에서 적용하는 방법

FSD 패턴 입문: Layer·Slice·Segment 구조를 실무에서 적용하는 방법

FSD(Feature-Sliced Design)는 프론트엔드 코드를 비즈니스 책임 기준으로 분할하는 아키텍처 패턴이다. 규모가 커진 React 프로젝트에서 파일 위치 기준이 흔들릴 때 특히 효과가 크다. 검색 유입이 많은 키워드(폴더 구조, 마이그레이션, 안티패턴, 상태관리)를 기준으로 실무 적용 포인트를 정리했다.

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

핵심 개념

실무에서 먼저 결정할 기준

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

핵심 요소 3~6개

항목	의미	언제 쓰는지(실무 상황)
Layer	애플리케이션의 큰 책임 계층	의존성 방향과 폴더 최상위 구조를 정할 때
Slice	도메인/기능 단위 묶음	기능 경계를 분리하고 변경 영향도를 줄일 때
Segment	slice 내부 역할 분리(ui/model/api 등)	로직·UI·통신 코드를 섞지 않기 위해
Public API	외부에 노출할 진입점(index.ts)	임포트 경계를 강제하고 내부 구조 변경을 보호할 때
Import Rule	상위 레이어에서 하위 레이어로만 의존	순환 참조와 결합도 폭증을 막을 때

예시 코드

src/
  app/
  pages/
  widgets/
  features/
  entities/
  shared/

문제 상황 1개

상황: 신규 기능 추가마다 기존 파일 위치 논쟁이 생기고 리뷰 시간이 늘어난다.
원인: 역할 기반 계층 규칙이 없어 개인 취향대로 파일을 배치했다.
해결: Layer/Slice/Segment 규칙을 문서화하고 Public API import 규칙을 린트로 강제한다.
예방 팁: 기능 시작 전 slice 책임 한 줄 설명을 PR 템플릿에 포함한다.

참고/출처

공식 문서: Feature-Sliced Design
공식 문서: FSD Overview
신뢰 자료: FSD Documentation Repo