frontend-fsd-guard

name	frontend-fsd-guard
description	Enforce Feature-Sliced Design 2.1 during frontend work. Use when editing or reviewing code under the main frontend `src/` tree or the admin console `apps/admin-console/src/`, especially for refactors, new slices, import-boundary cleanup, public API design, or architecture-sensitive UI changes.

Frontend Fsd Guard

Overview

Apply this workflow before making structural frontend changes. Use it to keep code inside the canonical FSD layers, expose stable public APIs, and prevent accidental cross-layer or deep-import drift.

Read references/fsd-2.1-rules.md when you need the official FSD reminders behind a decision.

Workflow

1. Identify the frontend scope first:

   • main frontend: src/
   • admin console: apps/admin-console/src/

2. Read the local constraints before editing:

   • read the nearest nested AGENTS.md for the target frontend tree, if one exists
   • treat nested AGENTS.md files as the repository-specific policy layer; keep this skill focused on reusable FSD workflow

3. Map the change to the correct layer before moving code:

   • app: providers, entrypoints, global runtime wiring
   • pages: route/screen composition roots
   • widgets: large reusable page blocks
   • features: user-facing interactions or actions
   • entities: domain concepts and their UI/model/api
   • shared: framework, UI kit, cross-domain utilities, API plumbing
   • avoid processes; the official spec marks it deprecated

4. Enforce import boundaries while editing:

   • import only from lower layers
   • do not let shared import from entities, features, widgets, pages, or app
   • keep same-layer cross-slice imports rare and only through explicit public APIs
   • avoid deep imports into another slice internals

5. Keep public APIs deliberate:

   • add or update index.ts exports for slices/segments that are used outside
   • do not use wildcard exports by default
   • if a file inside a slice needs another file from the same slice, import it directly, not through that slice's barrel

6. Place code by purpose, not by essence:

   • prefer ui, api, model, lib, config
   • avoid vague segments like components, hooks, or types unless they are already an established local convention

7. Validate with the repo guardrails after structural changes:

   • main frontend: pnpm lint:fsd, then relevant pnpm typecheck, pnpm lint, pnpm test
   • admin console: pnpm lint:fsd:admin, pnpm typecheck:admin, pnpm build:admin

Review Checklist

• Does each changed file belong to the layer/slice that owns its responsibility?
• Are cross-slice imports going through public APIs instead of internal paths?
• Did shared remain business-agnostic?
• Are pages composing slices instead of accumulating domain logic?
• Did new reusable UI blocks stop at widgets or entities/ui instead of leaking into shared/ui?
• If the change adds generated/API files, are they kept in the owning frontend and not in generic tooling folders?

References

• Official FSD summary and local translation notes: references/fsd-2.1-rules.md
• Repository-specific frontend policy: nearest nested AGENTS.md under the target frontend tree, if present