ADR-0002: widgets 계층을 사용하지 않는다
상태
Accepted
날짜
2026-08-10
맥락
FSD는 여섯 계층을 정의하며 그중 widgets는 "재사용 가능한 UI 블록"을 담는 자리입니다. features는 "재사용 가능한 사용자 상호작용"을 담습니다.
문제는 실제 프론트엔드 코드에서 UI 블록이 데이터 조회·상태 관리·이벤트 처리를 함께 갖는다는 점입니다. 두 정의를 동시에 만족하는 코드가 흔합니다.
구체적인 시나리오는 다음과 같습니다. 헤더에 알림 뱃지가 있고 클릭하면 알림 목록을 불러와 패널로 보여줍니다. 이 코드를 UI 블록으로 보면 widgets/notification-badge이고, 사용자 상호작용으로 보면 features/notification입니다. 두 판정 모두 규칙에 부합하므로 배치 위치가 사람마다, 실행마다 달라집니다.
이는 1순위 품질 목표인 예측 가능성과 정면으로 충돌합니다.
결정
widgets 계층을 생성하지 않습니다. 해당 성격의 코드는 다음 네 곳으로 분배합니다.
| 코드의 성격 | 배치 위치 |
|---|---|
| 특정 화면 전용 조합 | pages/<해당 화면> |
| 여러 화면에서 재사용되는 사용자 동작과 그 UI | features/ |
| 비즈니스 맥락이 없는 공용 UI | shared/ui/ |
| 앱 전역 레이아웃 | app/ |
여러 features를 조합해야 하는 경우는 상위 계층(pages 또는 app)이 각각을 임포트해 연결합니다.
앞의 시나리오는 이렇게 갈립니다. 헤더 골격과 배치는 앱 전역 레이아웃이므로 app/, 알림 조회와 패널 표시는 사용자 동작이므로 features/notification, 둘의 결합은 app/이 수행합니다. 상위 계층이 하위 계층을 임포트하므로 규칙 위반이 아닙니다.
근거의 출처
FSD 현행 공식 문서 사이트인 fsd.how가 widgets 계층의 신규 도입을 비권장하며, 사유로 features와의 책임 중복을 명시합니다. 공식 FSD 스킬도 같은 입장입니다.
주의
구 문서 사이트는 다르게 기술합니다
feature-sliced.design은 widgets를 정상 계층으로 기술하며 비권장 문구가 없습니다. v2.1에서 폐기된 것은 processes 계층이며 widgets가 아닙니다. 두 사이트의 서술이 다르다는 사실을 기록해 두는 이유는, 구 사이트를 근거로 이 결정이 되돌려지는 것을 막기 위함입니다.
본 결정은 출처와 무관하게 자체 근거로도 성립합니다. 배치 판정이 갈리는 계층은 1순위 목표를 위반합니다.
검토한 대안
widgets를 도입하되 판정 기준을 문서로 보완
| 구분 | 내용 |
|---|---|
| 장점 | 큰 UI 블록을 담을 자리가 생겨 pages가 비대해지는 것을 막습니다 |
| 단점 | "UI 블록인가 사용자 동작인가"의 경계를 문서로 정의해야 하는데, 이 경계는 코드마다 달라 일반 규칙으로 표현되지 않습니다 |
| 기각 사유 | 판정 규칙을 아무리 정교하게 써도 두 정의가 겹치는 영역이 남습니다. 계층을 없애면 그 영역 자체가 사라집니다 |
결과
배치 판정에서 모호한 축 하나가 제거됩니다. pages가 커지는 문제는 계층이 아니라 슬라이스 내부의 컴포넌트 분할로 해결하며, 그 기준은 컴포넌트 설계에 있습니다.
감수하는 사항은 다음과 같습니다.
- 여러
features를 조합하는 경우 상위 계층에 조합 코드가 모입니다.app이나pages가 조합 책임을 지므로 해당 파일이 길어질 수 있습니다. - FSD 공식도 이 영역이 완결되지 않았음을 인정하고 있습니다. 정말 해소되지 않는 사례가 있으면 feature-sliced/skills#7에 보고하도록 안내하고 있으며, 우리도 그런 사례를 만나면 이 ADR을 개정 대상으로 봅니다.