Feature-Sliced Design 아키텍처 개발 지원 플러그인

GitHub stars
10

Install

/plugin install fsd-helper@jeongsk-claude-skills

Run it inside Claude Code after adding the marketplace with /plugin marketplace add jeongsk/claude-skills.

Contents

Discovered from source

Skills 1

Feature-Sliced Design Architecture Skill

Feature-Sliced Design(FSD) 아키텍처를 적용한 프론트엔드 프로젝트 개발을 지원합니다.

Description

이 스킬은 FSD 아키텍처에 대한 깊은 이해를 바탕으로 개발자가 올바른 구조를 설계하고 유지할 수 있도록 돕습니다. 레이어, 슬라이스, 세그먼트의 개념과 의존성 규칙을 적용하여 확장 가능하고 유지보수가 쉬운 코드베이스를 구축합니다.

When to Use

이 스킬은 다음과 같은 상황에서 자동으로 활성화됩니다:

  • FSD 아키텍처 관련 질문 (레이어, 슬라이스, 세그먼트)
  • 프로젝트 폴더 구조 설계
  • 의존성 규칙 및 import 방향 문의
  • shared, entities, features, widgets, pages 등의 레이어 사용법
  • FSD 마이그레이션 또는 리팩토링

Trigger Patterns

  • "FSD", "Feature-Sliced Design" 언급
  • "레이어 구조", "슬라이스 생성", "세그먼트 추가"
  • "shared 레이어", "entities 레이어", "features 레이어" 등
  • "의존성 규칙", "import 방향"
  • "프론트엔드 아키텍처", "폴더 구조 설계"

Core Concepts

레이어 (Layers)

FSD는 7개의 표준화된 레이어를 정의합니다 (상위 → 하위):

  1. app - 애플리케이션 진입점, 라우팅, 프로바이더
  2. processes - (deprecated) 복잡한 페이지 간 시나리오
  3. pages - 라우트 기준 화면 단위
  4. widgets - 독립적인 대규모 UI 블록
  5. features - 사용자 가치를 제공하는 기능 단위
  6. entities - 비즈니스 엔티티 (User, Product 등)
  7. shared - 재사용 가능한 유틸리티, UI 컴포넌트

의존성 규칙

app → pages → widgets → features → entities → shared
         ↓
   상위 레이어는 하위 레이어만 import 가능
   같은 레이어 내 슬라이스 간 import 금지

세그먼트 (Segments)

각 슬라이스 내부는 역할별로 구분됩니다:

  • ui/ - UI 컴포넌트, 스타일
  • api/ - API 요청 함수
  • model/ - 비즈니스 로직, 상태 관리
  • lib/ - 유틸리티 함수
  • config/ - 설정값

References

External Documentation

최신 공식 문서는 WebFetch를 통해 참조합니다:

https://feature-sliced.design/kr/docs/get-started/overview
https://feature-sliced.design/kr/docs/reference/layers
https://feature-sliced.design/kr/docs/reference/slices-segments

Commands 5

FSD Check Command

FSD 구조와 의존성 규칙 준수 여부를 검사합니다.

Task

  1. 프로젝트 구조 분석:

    • FSD 레이어 존재 여부 확인
    • 각 레이어 내 슬라이스 구조 확인
  2. 의존성 규칙 검사:

레이어 간 의존성 검사

허용되는 Import 방향:
app → pages → widgets → features → entities → shared

각 파일의 import 문을 분석하여:

  • 상위 레이어에서 하위 레이어로의 import만 허용
  • 역방향 import 탐지 및 보고

슬라이스 간 의존성 검사

같은 레이어 내 슬라이스 간 import 탐지:

// ❌ 위반: features 내 슬라이스 간 import
// features/checkout/ui/CheckoutForm.tsx
import { useAuth } from '@/features/auth';

Public API 검사

슬라이스 내부에 직접 접근하는 import 탐지:

// ❌ 위반: 내부 구조 직접 접근
import { Button } from '@/shared/ui/Button/Button';

// ✅ 올바른 방법
import { Button } from '@/shared/ui';
  1. 구조 검사:

필수 파일 검사

  • 각 슬라이스에 index.ts (Public API) 존재 여부
  • 세그먼트별 index.ts 존재 여부

네이밍 규칙 검사

  • 슬라이스 이름: kebab-case
  • 컴포넌트 이름: PascalCase
  • 유틸리티 함수: camelCase
  1. 결과 리포트:

위반 사항 분류

심각도유형설명
ErrorLayer Violation역방향 레이어 import
ErrorSlice Cross-import같은 레이어 슬라이스 간 import
WarningInternal ImportPublic API 우회
InfoMissing Indexindex.ts 누락

수정 제안 (--fix)

❌ Error: features/checkout/ui/CheckoutForm.tsx
   Line 5: import { useAuth } from '@/features/auth'

   슬라이스 간 직접 import는 금지됩니다.

   ✅ 해결 방법:
   1. 상위 레이어(widgets)에서 조합
   2. Props/Callbacks로 의존성 주입
   3. 공통 로직을 entities 또는 shared로 이동

Output Format

FSD Structure Check Report
==========================

📁 Structure Analysis
├── app/          ✅ Valid
├── pages/        ✅ Valid (3 slices)
├── widgets/      ✅ Valid (4 slices)
├── features/     ⚠️ 2 warnings
├── entities/     ✅ Valid (5 slices)
└── shared/       ✅ Valid

🔗 Dependency Analysis
├── Layer violations:     2 errors
├── Slice cross-imports:  1 error
├── Internal imports:     3 warnings
└── Missing public API:   0

📋 Details
...

Summary: 3 errors, 5 warnings

Examples

/fsd-check
/fsd-check --path src/features
/fsd-check --fix

FSD Docs Command

Feature-Sliced Design 공식 문서를 조회합니다.

Task

지정된 토픽에 해당하는 FSD 공식 문서를 가져와 요약합니다.

토픽별 문서 URL

토픽URL
overviewhttps://feature-sliced.design/kr/docs/get-started/overview
layershttps://feature-sliced.design/kr/docs/reference/layers
sliceshttps://feature-sliced.design/kr/docs/reference/slices-segments
segmentshttps://feature-sliced.design/kr/docs/reference/slices-segments
ruleshttps://feature-sliced.design/kr/docs/reference/isolation
migrationhttps://feature-sliced.design/kr/docs/guides/migration
exampleshttps://feature-sliced.design/kr/docs/guides/examples
tutorialhttps://feature-sliced.design/kr/docs/get-started/tutorial

WebFetch 사용

WebFetch를 사용하여 해당 URL의 문서를 가져옵니다.

Topic Descriptions

overview

FSD의 핵심 개념과 목표, 기본 구조 소개

layers

7개 레이어(app, pages, widgets, features, entities, shared)의 역할과 책임

slices

슬라이스의 개념, 네이밍 규칙, 구조화 방법

segments

세그먼트(ui, api, model, lib, config)의 역할과 조직 방법

rules

의존성 규칙, Public API, 격리 원칙

migration

기존 프로젝트를 FSD로 마이그레이션하는 전략

examples

실제 FSD 적용 사례와 예제 프로젝트

tutorial

단계별 FSD 시작 가이드

Examples

/fsd-docs                    # overview 조회
/fsd-docs layers             # 레이어 문서
/fsd-docs rules              # 의존성 규칙
/fsd-docs migration          # 마이그레이션 가이드

Output

  • 문서 요약
  • 핵심 포인트 하이라이트
  • 관련 명령어 추천 (해당 시)

FSD Init Command

새 프로젝트에 Feature-Sliced Design 폴더 구조를 초기화합니다.

Task

  1. 현재 프로젝트 구조를 분석하여 기존 src 폴더 존재 여부 확인
  2. 프레임워크에 맞는 FSD 구조 생성:

기본 구조 생성

{src}/
├── app/
│   ├── providers/
│   ├── routes/
│   └── styles/
├── pages/
├── widgets/
├── features/
├── entities/
└── shared/
    ├── ui/
    ├── api/
    ├── lib/
    ├── config/
    └── types/
  1. 각 레이어에 기본 index.ts 파일 생성
  2. tsconfig.json에 path aliases 추가 (존재하는 경우)

Path Aliases 설정

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["{src}/*"],
      "@/app/*": ["{src}/app/*"],
      "@/pages/*": ["{src}/pages/*"],
      "@/widgets/*": ["{src}/widgets/*"],
      "@/features/*": ["{src}/features/*"],
      "@/entities/*": ["{src}/entities/*"],
      "@/shared/*": ["{src}/shared/*"]
    }
  }
}

Framework별 추가 설정

Next.js:

  • app/ 디렉토리가 이미 존재하면 FSD의 app 레이어는 _app 또는 layout.tsx로 통합
  • Next.js App Router 사용 시 라우팅은 Next.js 방식 유지

Vite:

  • vite.config.ts에 alias 설정 추가
  1. .eslintrc에 FSD import 규칙 추가 권장사항 안내

Output

  • 생성된 폴더 구조 트리 출력
  • 추가 설정 필요 사항 안내
  • 다음 단계 가이드 (슬라이스 생성 방법)

FSD Segment Command

기존 슬라이스에 새 세그먼트를 추가합니다.

Task

  1. 슬라이스 경로 검증:

    • 슬라이스가 존재하는지 확인
    • 경로 형식: {layer}/{slice-name}
  2. 세그먼트 유효성 검사:

    • 허용: ui, api, model, lib, config
    • 이미 존재하는 세그먼트인지 확인
  3. 세그먼트 생성:

세그먼트별 템플릿

ui:

{slice}/ui/
├── index.ts
└── .gitkeep
// ui/index.ts
// UI components for this slice

api:

{slice}/api/
├── index.ts
└── types.ts
// api/index.ts
// API functions for this slice

// api/types.ts
// Request/Response types
export interface ApiResponse<T> {
  data: T;
  error?: string;
}

model:

{slice}/model/
├── index.ts
├── types.ts
└── store.ts (optional)
// model/types.ts
// Domain types for this slice

// model/index.ts
export type {} from './types';

lib:

{slice}/lib/
└── index.ts
// lib/index.ts
// Utility functions for this slice

config:

{slice}/config/
├── index.ts
└── constants.ts
// config/constants.ts
export const CONFIG = {} as const;

// config/index.ts
export * from './constants';
  1. Public API 업데이트:
    • 슬라이스의 index.ts에 새 세그먼트 export 추가
// {slice}/index.ts
export {} from './ui';
export {} from './model';
export {} from './api';     // 새로 추가

Examples

/fsd-segment features/auth api
/fsd-segment entities/user lib
/fsd-segment features/checkout config

Output

  • 생성된 파일 목록
  • 업데이트된 Public API
  • 사용 예시

FSD Slice Command

지정된 레이어에 새 슬라이스를 생성합니다.

Task

  1. 레이어 유효성 검사:

    • 허용: entities, features, widgets, pages
    • shared, app은 슬라이스 없이 세그먼트만 사용
  2. 슬라이스 이름 검증:

    • kebab-case 형식 확인
    • 기존 슬라이스와 중복 확인
  3. 슬라이스 구조 생성:

레이어별 기본 구조

entities:

src/entities/{name}/
├── ui/
│   └── index.ts
├── model/
│   ├── types.ts
│   └── index.ts
├── api/
│   └── index.ts
└── index.ts

features:

src/features/{name}/
├── ui/
│   └── index.ts
├── model/
│   └── index.ts
├── api/
│   └── index.ts
└── index.ts

widgets:

src/widgets/{name}/
├── ui/
│   └── index.ts
└── index.ts

pages:

src/pages/{name}/
├── ui/
│   └── index.ts
└── index.ts
  1. Public API 템플릿 생성:
// {layer}/{name}/index.ts
// Public API for {name} {layer}

// UI exports
export {} from './ui';

// Model exports (if exists)
// export {} from './model';

// API exports (if exists)
// export {} from './api';
  1. 컴포넌트 템플릿 생성 (옵션):
// {layer}/{name}/ui/{PascalName}.tsx
import styles from './{PascalName}.module.css';

interface {PascalName}Props {
  // Define props
}

export function {PascalName}({ }: {PascalName}Props) {
  return (
    <div className={styles.root}>
      {/* {PascalName} */}
    </div>
  );
}

Examples

/fsd-slice entities user
/fsd-slice features auth --segments ui,api,model
/fsd-slice widgets header
/fsd-slice pages home

Output

  • 생성된 파일 목록
  • Public API 사용 예시
  • Import 방법 안내

Agents 1

FSD Architect Agent

Feature-Sliced Design 아키텍처 전문가로서 복잡한 구조 설계 및 마이그레이션을 지원합니다.

전문 분야

1. 아키텍처 설계

  • 프로젝트 요구사항 분석 후 최적의 FSD 구조 제안
  • 레이어별 슬라이스 설계
  • 의존성 방향 설계

2. 마이그레이션 전략

  • 기존 프로젝트 구조 분석
  • 단계별 마이그레이션 계획 수립
  • 리스크 최소화 전략

3. 코드 리뷰

  • FSD 규칙 준수 여부 검토
  • 의존성 위반 탐지 및 해결책 제시
  • 구조 개선 제안

4. 복잡한 문제 해결

  • 슬라이스 간 의존성 문제 해결
  • 순환 의존성 해결
  • 레이어 책임 분리

작업 방식

분석 단계

  1. 프로젝트 전체 구조 파악 (Glob, Read)
  2. 기존 import 패턴 분석 (Grep)
  3. 의존성 그래프 파악

설계 단계

  1. 비즈니스 도메인 식별
  2. 레이어별 책임 정의
  3. 슬라이스 경계 설정
  4. 의존성 방향 결정

구현 지원

  1. 구조 생성 (Write)
  2. 코드 리팩토링 (Edit)
  3. Import 경로 수정

분석 도구

구조 분석

# 레이어 구조 확인
Glob("src/{app,pages,widgets,features,entities,shared}/**/*")

# 특정 레이어 슬라이스 목록
Glob("src/features/*/index.ts")

의존성 분석

# 역방향 import 탐지 (entities → features)
Grep("from '@/features", path="src/entities")

# 슬라이스 간 cross-import 탐지
Grep("from '@/features/(?!{current-slice})", path="src/features/{current-slice}")

문서 참조

# 최신 FSD 문서 참조
WebFetch("https://feature-sliced.design/kr/docs/reference/layers")

대화 예시

마이그레이션 요청

사용자: "기존 컴포넌트 기반 프로젝트를 FSD로 마이그레이션하고 싶어요"

에이전트:

  1. 현재 프로젝트 구조 분석
  2. 비즈니스 도메인 식별
  3. 마이그레이션 우선순위 결정
  4. 단계별 마이그레이션 계획 제시
  5. 각 단계별 구체적인 작업 안내

구조 설계 요청

사용자: "이커머스 프로젝트의 FSD 구조를 설계해주세요"

에이전트:

  1. 이커머스 도메인 분석
  2. Entities: user, product, cart, order
  3. Features: auth, add-to-cart, checkout, search
  4. Widgets: header, product-list, cart-summary
  5. Pages: home, catalog, product-detail, cart, checkout

의존성 문제 해결

사용자: "features 간에 서로 import가 필요한데 어떻게 해야 하나요?"

에이전트:

  1. 문제 상황 분석
  2. 해결 패턴 제시:
    • 상위 레이어(widgets)에서 조합
    • Props/Callbacks로 의존성 주입
    • 공통 로직을 entities/shared로 이동
  3. 코드 예시 제공

Sponsors

Details

Marketplace
jeongsk/claude-skills
Source
fsd-helper
Category
Community

More from jeongsk/claude-skills

All 6