---
category: Unified
tags: [auto-consolidated, technical-documentation]
title: [[FSD (Feature-Sliced Design)|FSD (Feature-Sliced Design]]
last_updated: 2026-05-02
---

# [[FSD (Feature-Sliced Design)|FSD (Feature-Sliced Design]]

## 📌 Brief Summary
> FSD(Feature-Sliced Design)는 프론트엔드 개발에서 프로젝트의 복잡성을 줄이고 유지보수성과 확장성을 향상시키기 위해 고안된 아키텍처입니다. 기존의 역할 중심 폴더 구조가 가지는 한계를 극복하고자 '기능(Feature)'을 기준으로 코드를 분리하는 방식을 채택합니다. 기능 간의 결합도를 낮추고 각 기능이 독립적으로 관리되도록 설계되어, 특히 대규모 프로젝트를 관리하는 데 효과적인 방법론입니다.

---

**[[Feature-Sliced Design|Feature-Sliced Design]] (FSD)**는 프런트엔드 시스템 내 앱과 패키지의 코드를 체계적으로 조직화하여 조직 전체의 일관성을 보장하도록 돕는 아키텍처 방법론입니다 [1]. 명확한 책임과 의존성 규칙을 가진 계층(Layer)으로 코드베이스를 나누어, 개발자가 코드가 어디에 위치해야 하고 어떻게 임포트되어야 하는지 예측할 수 있게 합니다 [1, 2]. 결과적으로 '전역 공유 폴더'가 무분별한 스파게티 코드의 쓰레기장으로 변하는 것을 방지하고, 리팩토링의 안전성을 확보하며 새로운 팀원의 온보딩 시간을 단축합니다 [1-3].

## 📖 Core Content
*   **등장 배경 및 기존 구조의 한계:** 
    프로젝트의 규모가 커지고 복잡해짐에 따라 기존의 역할(Role) 중심 폴더 구조만으로는 다양한 관심사와 요구 사항을 관리하는 데 명확한 한계가 발생했습니다. 컴포넌트 기반 개발 방식에서 역할별로 코드를 분리하더라도 결국 기능 간의 결합도가 높아지는 문제를 피하기 어려웠고, 이를 해결하기 위해 FSD가 등장하게 되었습니다.
*   **기능(Feature) 중심의 분리:** 
    FSD 아키텍처는 이름 그대로 '기능'을 기준으로 코드를 분리합니다. 하나의 기능을 구현하는 데 필요한 모든 파일과 코드를 같은 폴더에 모아 단위별로 관리하는 것을 목표로 합니다. 이를 통해 각 기능이 독립적으로 동작하게 하며, 불필요한 결합도를 줄여 유지보수성을 극대화합니다.
*   **문서화된 표준으로서의 의의:** 
    FSD가 완전히 새롭거나 전례 없던 아키텍처는 아닙니다. 대규모 프로젝트에서 기능 단위로 묶어 관리하는 것이 효율적이라는 인식은 이전부터 존재했습니다. 하지만 FSD는 이러한 구조를 공식적인 형태로 갖추고 '문서화된 표준'으로 제공한다는 점에서 큰 의의가 있습니다. 명확한 공식 문서를 통해 팀원 간의 멘탈 모델(Mental Model)을 통일하고 구조에 대한 합의를 이끌어내는 데 드는 커뮤니케이션 비용을 줄여줍니다.
*   **적용 시 주의사항 (은탄환은 없다):** 
    공식 설명에서도 명시하듯 FSD 구조는 주로 '규모가 큰 프로젝트'에 유용합니다. 모든 프로젝트에 완벽한 해결책이 되는 것은 아니며, 상황과 규모에 따라 기존의 역할 기반 폴더 구조나 다른 방식이 훨씬 더 효율적일 수 있습니다. 프로젝트의 성장 단계와 관심사의 변화에 따라 구조 역시 유연하게 진화해야 합니다.

---

- **명확한 계층적 구조 (Layered Structure):** FSD는 코드베이스를 엄격한 책임에 따라 여러 계층으로 나눕니다. 일반적인 UI 컴포넌트나 헬퍼 함수, 디자인 토큰을 담는 가장 낮은 계층인 `Shared`부터 시작하여, 비즈니스 도메인을 나타내는 `Entities`, 사용자를 위한 비즈니스 로직(예: 결제 처리)을 담은 `Features`, 이러한 기능과 엔티티를 결합하는 `Widgets`, 전체 화면을 구성하는 `Pages`, 그리고 스타일 및 라우팅이 초기화되는 진입점인 `App`으로 구성됩니다 [1].
- **의존성 방향 및 공개 API (Dependencies & [[Public APIs|Public APIs]]):** FSD는 상위 계층이 하위 계층을 향해서만 의존성을 가지도록 방향성을 통제하며, 슬라이스(slice) 경계에서 명시적인 공개 API(Public APIs)를 노출할 것을 권장합니다 [4, 5]. 예를 들어, 앱은 패키지의 깊은 내부 파일을 직접 임포트해서는 안 되며(`index.ts` 등을 통해서만 접근), 기능(`Features`)은 의도된 공유 슬라이스가 없는 한 다른 기능을 직접 임포트하지 않아야 합니다 [4, 5].
- **도메인 주도 설계(DDD)의 구체화:** 프런트엔드 환경에서 도메인 주도 설계를 실용적인 파일 시스템으로 변환하는 것은 까다롭지만, FSD는 이를 구체적인 프로젝트 구조로 맵핑해 줍니다 [6]. 핵심 도메인 개념은 `entities/`에, 사용자 대면 기능은 `features/`에, 재사용 가능한 원시 요소는 `shared/`에 배치함으로써 도메인 경계를 디렉토리 및 임포트 수준에서 시각적으로 명확하게 드러냅니다 [6].
- **모노레포 아키텍처와의 시너지:** 모노레포([[Monorepo|Monorepo]]) 환경에서 FSD를 적용하면 UI 키트나 API 클라이언트 등은 공유 패키지로 분리하고, 각 앱과 도메인 패키지 내부는 FSD 계층에 따라 구조화하는 "두 세계의 장점(best of both worlds)"을 취할 수 있습니다 [7]. 이는 대규모 시스템에서 우발적인 결합(accidental coupling)을 크게 줄여줍니다 [4].

## ⚖️ Trade-offs & Caveats
- **과거 데이터와의 충돌:** 자동화 엔진에 의해 매핑된 지식으로, 추후 정밀 검증 필요.
- **정책 변화:** Design & Experience 분야의 자동 자산화 수행.

## 🔗 Knowledge Connections
- **Related Topics:** [[관심사의 분리 (Separation of Concerns)|관심사의 분리 (Separation of Concerns]], 단일 책임 원칙 (SRP), [[컴포넌트 기반 아키텍처|컴포넌트 기반 아키텍처]]
- **Projects/Contexts:** 대규모 프론트엔드 프로젝트 아키텍처 및 폴더 구조 설계
- **Contradictions/Notes:** 소스에서는 FSD가 기능 간 결합도를 줄이고 유지보수를 돕는 훌륭한 표준이지만, 모든 상황에서 완벽한 정답은 아니라고 주장합니다. 프로젝트의 크기나 특성에 따라 오히려 기존의 단순한 폴더 구조가 더 적합할 수도 있으므로 프로젝트 상황에 맞는 유연한 폴더 구조 적용을 권장합니다.

---
*Last updated: 2026-04-18*

---

---

- **Related Topics:** [[Monorepo Architecture|Monorepo Architecture]], Atomic Design, Domain-Driven Design (DDD), [[Public APIs|Public APIs]]
- **Projects/Contexts:** [[대규모 확장성과 유지보수성이 요구되는 프런트엔드 모노레포 프로젝트|대규모 확장성과 유지보수성이 요구되는 프런트엔드 모노레포 프로젝트]], [[Turborepo 및 Nx와 같은 빌드 오케스트레이션 도구를 활용하는 대규모 조직의 React 시스템|Turborepo 및 Nx와 같은 빌드 오케스트레이션 도구를 활용하는 대규모 조직의 React 시스템]]
- **Contradictions/Notes:** 소스에 따르면 [[Atomic Design|Atomic Design]]은 UI 컴포넌트와 디자인 시스템을 구성하는 데는 강력한 언어지만 도메인 로직의 위치를 일관되게 지정하기 어렵게 만드는 반면, FSD는 명확한 기능(Feature) 경계와 의존성 방향을 제공하여 대규모 애플리케이션의 아키텍처적 일관성을 유지하는 데 더 적합하다고 비교됩니다 [4].

---
*Last updated: 2026-04-26*