Feature-Sliced Design

Feature-Sliced Design(FSD)은 프론트엔드 코드를 레이어(layer)·슬라이스(slice)·세그먼트(segment) 세 단계로 나누고, 누가 누구를 import할 수 있는지를 규칙으로 정하는 아키텍처 방법론이다. 폴더 이름 규약처럼 보이지만 본질은 의존 방향 규칙이다.

세 단계

src/
  app/        앱을 돌리는 것: 라우팅, 진입점, 전역 스타일, 프로바이더
  pages/      화면 단위(중첩 라우팅이면 큰 화면 조각)
  widgets/    스스로 완결된 큰 UI 블록
  features/   재사용되는 사용자 기능 단위(장바구니 담기, 좋아요)
  entities/   다루는 비즈니스 개체(상품, 사용자, 주문)
  shared/     프로젝트 도메인과 무관한 재사용 코드(UI 킷, API 클라이언트)
    └ product/          슬라이스: 레이어 안의 도메인 단위
        ├ ui/ api/ model/ lib/ config/   세그먼트: 기술적 역할
        └ index.ts      공개 API(Public API)

• 레이어는 표준 7개였는데 processes가 폐기돼 위의 6개를 쓴다(2026 기준). app과 shared는 슬라이스 없이 세그먼트로만 나눈다
• 슬라이스는 비즈니스 도메인별로 자른다
• 세그먼트는 목적별로 자른다. 표준 이름은 ui·api·model·lib·config

규칙

1. 아래로만 import. 슬라이스의 파일은 자기보다 엄격히 아래 레이어의 슬라이스만 가져온다. features는 entities·shared를 쓰지만 widgets는 못 쓴다
2. 같은 레이어 슬라이스끼리 import 금지. features/cart가 features/order를 가져오면 위반이다. 공통 부분은 아래 레이어로 내린다
3. 슬라이스 밖에서는 공개 API만. 슬라이스 내부 파일을 직접 import하지 않고 index.ts 같은 진입점(배럴 파일과 re-export)만 본다

규칙을 지키면 의존 그래프가 한 방향으로만 흘러 순환이 생기지 않고, 공개 API 뒤의 내부를 바꿔도 바깥이 깨지지 않는다. 결과적으로 결합도가 레이어 경계에서 끊긴다. 공식 문서가 꼽는 장점은 구조의 균일성(새 팀원이 빨리 읽음), 변경의 안정성, 통제된 재사용, 도메인 중심 언어다.

트레이드오프

• 분류 비용이 매번 든다. "이건 feature인가 entity인가 widget인가"를 처음 한 번이 아니라 PR마다 판단한다. 한 슬라이스에서 쓰던 것을 여러 곳이 쓰기 시작하면 아래 레이어로 옮겨야 하고, 그때 import 경로가 줄줄이 바뀐다. "좋아요 누르기"처럼 명사와 동사가 붙은 코드는 어느 쪽도 방어 가능해 리뷰 논쟁이 길어지기 쉽다. "두 슬라이스 이상이 쓰면 내린다" 같은 횟수 기준을 두면 판단이 빨라진다
• 같은 레이어 금지가 정당한 의존도 막는다. 주문이 장바구니 데이터를 읽는 것은 자연스럽지만 둘이 같은 레이어면 금지다. 우회로는 아래로 내리기(재분류 비용), 위 레이어에서 조립해 props로 넘기기(페이지 비대화), 공식 교차 참조 표기 @x(문서는 entities 사이 관계용으로 소개한다)다. @x를 남용하면 규칙이 없는 것과 같아진다
• 파일 기반 라우팅과 부딪힌다. Next.js App Router의 app/은 FSD의 app·pages 레이어와 이름이 겹친다. 공식 가이드는 FSD 쪽 두 레이어를 _app·_pages로 바꾸고, 라우트 파일에서는 _pages의 페이지를 다시 내보내기만 하라고 권한다. 라우트당 파일이 두 벌이 된다
• 서버·클라이언트 경계를 표현하지 않는다. 세그먼트는 RSC 경계를 담는 축이 없어서, 서버 전용 세그먼트 같은 확장을 팀이 직접 정해야 한다
• 도구 없이는 유지되지 않는다. 공개 API 파일을 만들어 두고도 급할 때 내부 파일을 직접 import하기 시작하면 금방 무너진다. 공식 린터(Steiger)나 ESLint 경계 규칙으로 강제해야 한다
• 작은 팀·초기 프로젝트에서는 얻는 것보다 의례가 크다. 라이브러리에는 맞지 않고, 지금 구조가 잘 돌아가면 굳이 필요 없다고 공식 문서도 말한다

가장 쓸모 있는 부분은 "import 방향을 한쪽으로 강제한다"는 아이디어 하나다. 레이어 6개를 다 쓰지 않고 shared와 도메인 폴더 2~3단으로 줄여 쓰는 것도 흔하다. 비슷한 생각은 도메인 주도 설계 (DDD)의 바운디드 컨텍스트, 계층형 구조의 의존성 역전과 이어진다.

출처: Feature-Sliced Design - Overview · FSD - Layers · FSD - Usage with Next.js · Steiger