fsd-architecture

name	fsd-architecture
description	Feature-Sliced Design 아키텍처 패턴을 검증하고 적용합니다. "FSD 검증", "아키텍처 검토", "레이어 구조 확인", "슬라이스 분리", "의존성 검사" 요청 시 사용합니다.
metadata	{"author":"pjt3591oo","version":"1.0.0"}

Feature-Sliced Design (FSD) Pattern

애플리케이션을 레이어와 슬라이스로 구조화하여 확장 가능하고 유지보수하기 쉬운 아키텍처를 구현합니다.

핵심 개념

FSD는 기능별로 코드를 분리하고, 명확한 의존성 규칙을 통해 확장 가능한 아키텍처를 만드는 방법론입니다.

레이어 계층 구조

App (최상위)
  ↓
Processes (선택적)
  ↓
Pages
  ↓
Widgets
  ↓
Features
  ↓
Entities
  ↓
Shared (최하위)

핵심 규칙: 레이어는 자신보다 하위 레이어만 import 가능

디렉토리 구조

src/
├── app/          # 애플리케이션 초기화
├── processes/    # 복잡한 비즈니스 프로세스 (Optional)
├── pages/        # 페이지 컴포넌트
├── widgets/      # 독립적인 UI 블록
├── features/     # 사용자 기능
├── entities/     # 비즈니스 엔티티
└── shared/       # 공통 코드

슬라이스 구조

features/
├── auth/              # 슬라이스
│   ├── ui/           # UI 컴포넌트
│   ├── model/        # 비즈니스 로직
│   ├── api/          # API 호출
│   ├── lib/          # 유틸리티
│   └── index.ts      # Public API

레이어별 패턴 가이드

레이어	주요 패턴	부가 패턴	의존 가능 레이어
Shared	프레젠테이션, 커스텀 훅	합성	없음
Entities	서비스 레이어, 상태 관리	커스텀 훅, 프레젠테이션	Shared
Features	컨테이너/프레젠테이션, 커스텀 훅	컴파운드, 상태 끌어올리기	Shared, Entities
Widgets	합성, 컨테이너/프레젠테이션	Slot, 커스텀 훅	Shared, Entities, Features
Pages	컨테이너, 커스텀 훅	상태 끌어올리기	Shared, Entities, Features, Widgets
Processes	상태 머신, Context	커스텀 훅	Shared, Entities, Features
App	Provider, 라우팅	-	모든 레이어

핵심 규칙

1. 의존성 규칙

• ✅ 하위 레이어만 import 가능
• ❌ 상위 레이어 import 금지
• ❌ 같은 레이어의 다른 슬라이스 import 금지 (Cross-import)

2. Public API

• 각 슬라이스는 index.ts를 통해서만 export
• 내부 구현은 외부에 노출하지 않음

3. 슬라이스 책임

• 각 슬라이스는 단일 책임을 가짐
• 도메인별로 명확히 분리

빠른 가이드

코드 배치 방법

1. 재사용 가능한 UI/유틸? → Shared
2. 비즈니스 엔티티 (User, Product)? → Entities
3. 사용자 액션 (로그인, 장바구니 추가)? → Features
4. 독립적인 UI 블록 (Header, Footer)? → Widgets
5. 라우팅 대상 페이지? → Pages
6. 여러 페이지 걸친 프로세스? → Processes
7. 앱 초기화? → App

체크리스트

새 코드 작성 시:

• 올바른 레이어에 배치되었는가?
• 의존 가능한 레이어만 import 했는가?
• Public API를 통해서만 export 했는가?
• Cross-import를 하지 않았는가?
• 슬라이스가 단일 책임을 가지는가?

사용 방법

아키텍처 검증

# 전체 구조 검증
claude code review src

# 특정 레이어 검증
claude code review src/features

# 의존성 검사
claude code check-dependencies src/features/auth

슬라이스 생성

# 새 feature 생성
claude code create feature auth

# 새 entity 생성
claude code create entity user

더 알아보기

• 상세 가이드라인: reference.md 참조
• 코드 예시: examples.md 참조