feature-sliced-design

Feature-Sliced Design Guidelines

Directory structure

skills/feature-sliced-design/
  SKILL.md
  references/
    README.md
    import-rules.md
    layers.md
    public-api.md
    slices-segments.md
  samples/
    README.md
    project-structure.md
    slice-public-api.md
    layer-imports.md
    cross-entity-import.md
    slice-groups.md
    composition-in-pages.md
    nextjs-app-router.md
    react-query-integration.md
  scripts/
    README.md
    install.md
    generate.md
    lint.md
  rules/
    README.md
    layer-dependency.md
    public-api-enforcement.md
    slice-isolation.md
    segment-naming.md

Exploration procedure

Derive the category from the task, and identify the target page in the category's README.md:

Find the category corresponding to the task in the mapping table below
For that category, README.md Refer to to identify the target page
Read the .md of the relevant page to check the details

Task → Category Mapping

Task	Category	Reference README
Want to know the layer structure and responsibilities	references	references/README.md
Want to check import rules and dependency direction	references	references/README.md
Want to understand the Public API pattern	references	references/README.md
Want to know the definitions of slices and segments	references	references/README.md
Want to see an example of a typical FSD project structure	samples	samples/README.md
Want to see examples of combinations with Next.js / React Query	samples	samples/README.md
Want to see real examples of the @x notation and cross-entity dependencies	samples	samples/README.md
Want to know composition patterns in pages / widgets	samples	samples/README.md
Want to know toolchain installation and CLI commands	scripts	scripts/README.md
Want to run architecture compliance checks with steiger	scripts	scripts/README.md
Want to generate code with @feature-sliced/cli	scripts	scripts/README.md
Want to automatically enforce layer dependency direction rules	rules	rules/README.md
Want to check the rule that allows only Public API access	rules	rules/README.md
Want to check slice isolation and segment naming conventions	rules	rules/README.md

For details on core concepts, see references/<topic>.md, and the check rule is rules/<rule>.md .

Mandatory rules

Divide code into 6 standard layers: app, pages, widgets, features, entities, shared
Imports areOnly one-way to lower layersAllowed. Imports between slices within the same layer are prohibited
Each slice defines a Public API in index.ts . From the outside, import only via the Public API
export * Do not use . Explicitly enumerate what is exposed
Name segments by "purpose" (ui, model, api). Do not name them by "essence" (components, hooks, types）
app と shared has no slices. It consists only of segments

Layer structure (upper → lower)

app        — ルーティング、プロバイダー、グローバル設定（スライスなし）
pages      — 画面単位のスライス
widgets    — 複数ページで再利用される大規模 UI ブロック
features   — ビジネス価値をもたらすユーザーインタラクション
entities   — ビジネスエンティティ（User, Product 等）
shared     — 汎用的な再利用可能コード（スライスなし）

Standard segments

Segment	Contents
`ui`	UI components, formatters, styles
`api`	Backend integration, request functions, response types
`model`	Data schemas, stores, business logic
`lib`	Slice-local utilities
`config`	Configuration constants, feature flags

Directory structure example

src/
├── app/
│   ├── routes/
│   ├── store/
│   └── styles/
├── pages/
│   └── feed/
│       ├── ui/
│       ├── api/
│       └── index.ts
├── widgets/
│   └── header/
│       ├── ui/
│       └── index.ts
├── features/
│   └── search-articles/
│       ├── ui/
│       ├── model/
│       └── index.ts
├── entities/
│   └── user/
│       ├── ui/
│       ├── model/
│       ├── api/
│       └── index.ts
└── shared/
    ├── ui/
    ├── api/
    ├── lib/
    └── config/

Common mistakes

Use components/, hooks/, types/ for segment names → ui/, model/, lib/ Use
export * export together in → Explicitly export { Name } from enumerate with
Directly import slices in the same layer → Compose in a higher layer, or@x use the notation
Move code that will not be reused to features や widgets prematurely → first pages place it in, and promote it after reuse is confirmed
shared place business logic in → business logic in entities place it in or above
Add a custom layer → Use only the standard 6 layers
Create a slice without a Public API → Always define index.ts first
Place type definitions in the types/ group into the folder → per domain model/ segment