@bonesofspring/ai-rules 0.1.37 → 0.1.40

package/presets/claude/next/rules/api-and-data/http-client.md

@@ -0,0 +1,40 @@
+---
+paths:
+  - app/src/lib/clients/**/*.ts
+  - app/src/api/clients/**/*.ts
+---
+
+# HTTP-транспорт
+
+**Имена** фабрик, классов ошибок, типов ответа и конфига — **как в текущем коде репозитория** и в barrel `app/src/types/index.ts`. Ниже — **архитектурные правила**, а не спецификация переименований.
+
+## Роль слоя
+
+- Обычные REST‑вызовы к backend идут через **одну реализацию** в `app/src/lib/clients/**` (модуль общего клиента) и **преднастроенные экземпляры** в `app/src/api/clients/**`, по тому же паттерну, что уже принят в проекте.
+- Место транспорта в общей картине **порты и адаптеры** — в `architecture/architecture-boundaries.md` (раздел **«Порты и адаптеры»**).
+- **Не** вызывать `fetch` напрямую из `app/src/api/services/**`, store и UI (см. `architecture/architecture-boundaries.md`, `api-and-data/api-services.md`); из store/UI — только вызовы через сервисы из `@/api` (`architecture/api-public-imports.md`).
+- **Исключения** (узкие протоколы, отдельный транспорт) — только там, где в репозитории уже есть образец; повторять его, не плодить произвольные обходы общего клиента.
+
+## Типы
+
+- Всё, что относится к **контракту запроса/ответа/ошибки** приложения и реэкспортируется для HTTP‑слоя, импортировать **только** из barrel `@/types`, без deep‑импортов из внутренних файлов `app/src/types/**` (см. `architecture/types-public-imports.md`).
+- Не поднимать в новом коде **типы и зависимости от внешнего HTTP‑клиента**, от которого проект ушёл; ориентир — **`package.json`** и существующие вызовы.
+
+## Контракт ошибок
+
+- Ошибки сети и HTTP должны приходить в **едином виде**, который задаёт общий клиент (обычно класс/обёртка с полем вроде `response` для тела и статуса).
+- В **`catch`** ориентироваться на **фактическую форму** ошибки в этом репозитории (как в соседних слайсах/сервисах): доступ к телу ошибки, статусу, диагностическому коду — **по полям текущей реализации**, без выдумывания второго формата.
+
+## Поведение, которое остаётся в клиенте
+
+- Общие заголовки, `credentials`, загрузка файлов (**FormData** / снятие лишних заголовков), бинарные ответы (**blob** и аналоги), единообразный разбор JSON и прочих тел.
+- Перехват **401 / refresh**, обработка **404** и т.п. — **централизованно**, если так уже сделано в клиенте; не дублировать ту же логику в каждом сервисе.
+
+## Связь со store
+
+- Thunk может возвращать **тип обёртки успешного ответа**, если сервис так устроен; в **state** по возможности класть **доменные** типы после маппинга. Подробнее — `api-and-data/store-rtk.md`.
+
+## Требование к агенту
+
+- Меняя реализацию общего клиента — **обновить или добавить behavior‑тесты** рядом с модулем клиента (`testing/tests-unit.md`).
+- Не вводить **второй полноценный HTTP‑стек** без явной задачи и согласования с архитектурой репозитория.

package/presets/claude/next/rules/api-and-data/store-rtk.md

@@ -0,0 +1,65 @@
+---
+paths:
+  - app/src/store/**/*.ts
+---
+
+# Общие принципы
+
+- Использовать **Redux Toolkit**:
+  - `createSlice`, `createAsyncThunk`, RTK Query (если используется).
+- Хранить в store **доменные модели**, не «сырые» DTO из API.
+- Все вычисления и преобразования данных (включая вычисляемые поля, булевые флаги, агрегаты, человеко‑читаемые строки и т.п.) должны выполняться **между ответом API и записью в store** — в мапперах или отдельном слое подготовки данных. Store хранит уже подготовленную доменную модель.
+- Разделять:
+  - «серверное» состояние (данные из API) и
+  - локальное UI‑состояние (выбор/фильтры/флаги).
+
+# Структура слайсов
+
+- Каждый доменный модуль — свой слайс в `app/src/store/slices/**`.
+- Слайс экспортирует:
+  - `reducer` по умолчанию;
+  - `actions` именованным экспортом;
+  - селекторы `selectSomething(state: RootState): Type`.
+- Состояние:
+  - явный тип для state;
+  - аккуратная инициализация initialState.
+
+# Асинхронность и сайд‑эффекты
+
+- Асинхронные запросы:
+  - через `createAsyncThunk` или RTK Query.
+  - внутри thunk:
+    - вызывать API через сервисы, импортированные из `@/api` (**`architecture/api-public-imports.md`**);
+    - не вызывать HTTP‑клиент напрямую — только через эти сервисы.
+- Сайд‑эффекты (логирование, аналитика, работа с файлами):
+  - выносить в middleware (`app/src/store/middleware/**`) или специализированные слайсы.
+
+# Типизация
+
+- Использовать `RootState`, `AppDispatch` и типизированные хуки `useAppDispatch`, `useAppSelector` (если есть).
+- **HTTP и ошибки API**:
+  - не импортировать типы **сторонних HTTP‑библиотек**, которых нет в актуальных зависимостях и существующих слайсах (ориентир — **`package.json`** и соседние файлы);
+  - когда сервис возвращает **обёртку ответа** прикладного клиента — использовать **соответствующий тип из `@/types`** (как в barrel и в аналогичных thunk’ах);
+  - при ошибках после вызова сервиса — опираться на **тот же класс/контракт ошибки транспорта**, что использует общий клиент (из `@/types`), и разбирать тело/статус **по полям текущей реализации**, а не по воображаемому API;
+  - в **`catch`** предпочитать **`instanceof`** на класс ошибки транспорта из `@/types` (если он есть в коде) вместо голого `as`, когда это выразимо без шума (см. `stack/no-type-assertion.md`).
+- Для сущностей:
+  - доменные типы (включая вычисляемые поля) определять в `app/src/types/**`, экспортировать через barrel и импортировать в слайсы из `@/types` как **источник правды** (`architecture/types-public-imports.md`);
+  - избегать дублирования описаний сущностей в нескольких местах.
+- **Граница домена**: в **state** хранить доменные модели; тип **обёртки ответа клиента** допустим как тип **возвращаемого значения thunk** или промежуточно до маппинга — без дублирования DTO в полях state без нужды (согласовано с `api-and-data/api-services.md` и `api-and-data/http-client.md`).
+
+# Тестирование слайсов
+
+- Для важных слайсов:
+  - тестировать редюсеры (инициализация, основные переходы состояний);
+  - тестировать селекторы (включая edge cases).
+- Thunk’и:
+  - по возможности покрывать тестами с моками API‑слоя.
+
+# Требование к агенту
+
+При изменении/создании слайса:
+
+- Не класть логику API внутрь редюсеров/компонентов.
+- Строго типизировать state и actions.
+- Использовать **единый стиль именования actions и селекторов**, как в существующих слайсах.
+- При работе с ошибками и ответами HTTP опираться на **`api-and-data/http-client.md`** и контракты из `@/types`, а не на типы внешних HTTP‑библиотек вне зависимостей проекта.

package/presets/claude/next/rules/architecture/README.md

@@ -1,3 +1,13 @@
 # Architecture
 
-Границы модулей, слоёв и зависимостей (аналог темы architecture / boundaries в Cursor-пресете).
+Границы модулей, слоёв, зависимостей и сквозная доставка фич.
+
+| Файл | Содержание |
+|------|------------|
+| `architecture-boundaries.md` | UI / store / API, порты и адаптеры, организация фич |
+| `layer-barrel-exports.md` | Двухуровневые barrel и чеклист public API |
+| `types-public-imports.md` | Импорт типов только через `@/types` |
+| `api-public-imports.md` | Импорт API только через `@/api` |
+| `feature-delivery-workflow.md` | Чеклист новой фичи, матрица зона → правило |
+
+Все файлы — **session start** (без `paths:`).

package/presets/claude/next/rules/architecture/api-public-imports.md

@@ -0,0 +1,25 @@
+# Импорты из `@/api`
+
+- **Публичный API слоя API** — barrel `app/src/api/index.ts`. Для файлов **вне** `app/src/api/**` импортировать сервисы, клиенты, эндпоинты и публичные типы API **только** как `import … from '@/api'` (или `from '@/api/index'` при необходимости явного пути).
+- **Запрещено** для таких потребителей обходить barrel: любой импорт вида `@/api/<что‑угодно>`, кроме `@/api/index`. Это дублирует правило ESLint `no-restricted-imports` в `app/eslint.config.mjs` (паттерн `@/api/*` с исключением `@/api/index`).
+- При **добавлении** публичного символа в регламентированный слой — реэкспорт в корневой barrel по **`architecture/layer-barrel-exports.md`**.
+
+## Внутри слоя `app/src/api/**`
+
+- При реализации сервисов, клиентов и barrel допустимы **относительные** импорты и пути вида `@/api/services/**`, `@/api/clients/**` между файлами этого слоя. Это не относится к потребителям снаружи `app/src/api/**`.
+
+## Примеры
+
+```typescript
+// ✅ Допустимо в store, UI, lib вне app/src/api — только barrel
+import { MedcardApiService, MarketplaceApiService } from '@/api'
+import type { TReferenceRequest } from '@/api'
+
+// ❌ Запрещено снаружи app/src/api (сработает ESLint)
+import { MedcardApiService } from '@/api/services/MedcardApiService/MedcardApiService'
+import { MedcardApiClient } from '@/api/clients/MedcardApiClient'
+```
+
+При ревью и правках кода **не добавлять** новые импорты из `@/api/...` кроме `@/api` / `@/api/index` в файлах вне `app/src/api/**`.
+
+**Коллизии формулировок:** по **импорту из API‑слоя** (store, UI, прочий код вне `app/src/api/**`) — источник правды — **этот файл** (`@/api`).

package/presets/claude/next/rules/architecture/architecture-boundaries.md

@@ -0,0 +1,67 @@
+# Границы между слоями
+
+## UI (`app/src/ui/**`)
+
+- Может импортировать: `@/ui/**`, `@/store/**`, типы из `@/types` и enum из `@/types/enums` (**только как в `architecture/types-public-imports.md`**), контракт к API — **только** `import … from '@/api'` (**`architecture/api-public-imports.md`**).
+- Не должен:
+  - обращаться к HTTP‑клиенту напрямую;
+  - знать детали DTO backend — только доменные типы.
+
+## Store (`app/src/store/**`)
+
+- Может импортировать: `@/store/**`, сервисы и публичные сущности API — **только** из `@/api` (**`architecture/api-public-imports.md`**), типы из `@/types` и enum из `@/types/enums` (**`architecture/types-public-imports.md`**).
+- Не должен:
+  - зависеть от конкретных UI‑компонентов;
+  - напрямую работать с global/window API.
+- Вызовы к backend — только через сервисы, импортируемые из `@/api`; **транспортные** типы ответа и ошибки (из `@/types`, в том же виде, что у прикладного HTTP‑клиента) во thunk допустимы, если так выстроен API‑слой (`api-and-data/http-client.md`, `api-and-data/store-rtk.md`).
+
+## API (`app/src/api/**`)
+
+Реализация в `services/**`, `clients/**`, реэкспорт в `app/src/api/index.ts`:
+
+- Внутри слоя: типы из `@/types` и enum из `@/types/enums` (**`architecture/types-public-imports.md`**); импорты `@/api/services/**`, `@/api/clients/**`, относительные пути между файлами слоя (`api-and-data/http-client.md`, `api-and-data/api-services.md`).
+- Не должен:
+  - тянуть в себя UI или store;
+  - смешивать HTTP‑слой и доменный слой — использовать мапперы.
+
+## UI и обращение к API (`@/api`)
+
+- По умолчанию сценарии с **изменением серверного состояния** и координация нескольких шагов — через **store** (`createAsyncThunk`, dispatch, паттерн фичи в репозитории).
+- Прямой вызов методов сервисов, импортированных из **`@/api`**, из UI допустим только в **узких случаях**: преимущественно **чтение** или действие **без необходимости держать результат в Redux**; те же **доменные типы**, что использовал бы thunk; **не** дублировать уже существующий сценарий из store и **не** протаскивать DTO в компоненты.
+- Предпочтительно оформлять такие вызовы так же, как в **соседних фичах** репозитория (хук‑фасад, отдельный хук и т.д.).
+
+## Порты и адаптеры (краткая карта)
+
+- **Входящий адаптер**: UI — ввод пользователя, отображение; зависит от store и доменных типов, не от транспорта.
+- **Оркестрация сценариев**: store (slices, thunk) — вызывает сервисы, кладёт в state **доменные** модели после маппинга.
+- **Исходящий порт (контракт к backend)**: публичный API **`@/api`** (barrel `app/src/api/index.ts`; реализация — в `app/src/api/services/**` и т.д., см. `architecture/api-public-imports.md`).
+- **Исходящий адаптер**: общая реализация HTTP в **`app/src/lib/clients/**`** и экземпляры в **`app/src/api/clients/**`**.
+
+## Фича как срез
+
+- Для сложной фичи выравниваются имена и термины (**единый язык** предметной области) в типах, селекторах, сервисах и UI; структура папок — как в соседних фичах репозитория.
+
+# Правила импортов
+
+- Всегда использовать алиас `@/...` для импортов между слоями.
+- Внутри одного модуля/фичи можно использовать относительные импорты, но **без подъёма выше корня фичи** (избегать `../../../`).
+- При обращении из компонентов, хуков, утилит и других модулей к чужому слою или фиче использовать только **public API** (barrel/index‑файлы и явно экспортируемые сущности), не делать deep‑импорты внутренних файлов других фич; для регламентированных слоёв — **`architecture/layer-barrel-exports.md`** и `architecture/*-public-imports.md`; для API‑слоя снаружи `app/src/api/**` — **`architecture/api-public-imports.md`** (только `@/api`).
+- При добавлении нового кода проверять:
+  - если модуль переиспользуемый — он должен зависеть только от более "низких" слоёв (types, utils, api), но не от страниц.
+
+# Организация фич
+
+- Для сложных фич (например, `OrderCheckout`):
+  - Страница: `app/src/ui/pages/OrderCheckoutPage/**`.
+  - Локальные компоненты: поддиректории `components/**` внутри страницы.
+  - Связанный store: `app/src/store/slices/OrderCheckout/**`.
+  - API: `app/src/api/services/OrdersApi/OrderCheckout/**` (имя корневого сервиса взять из принятой в проекте схемы).
+  - Типы: `app/src/types/**` с экспортом через barrel **`app/src/types/index.ts`** (`architecture/types-public-imports.md`).
+
+# Требование к агенту
+
+При добавлении новой функциональности:
+
+- Разместить файлы в **соответствующих слоях**.
+- Проверить существующие фичи с аналогичной структурой и **повторить их организацию**.
+- Не "коротить" слои (например, не вызывать API прямо из компонента только ради упрощения).

package/presets/claude/next/rules/architecture/feature-delivery-workflow.md

@@ -0,0 +1,99 @@
+# Доставка фичи (сквозной порядок)
+
+Типичная фича с данными с backend и общим состоянием. Детали слоёв — в `architecture/architecture-boundaries.md`, `stack/next-app-core.md`.
+
+Плейсхолдеры: `<FeatureName>`, `<ServiceRoot>`, `<Area>` — нейтральные имена; реальные имена брать из соседних фич того же типа.
+
+## Инварианты перед кодом
+
+- Найти в том же слое фичу сопоставимой сложности и **повторить структуру каталогов и паттерн именования**.
+- Не добавлять `any`; при необходимости — `unknown` и сужение типа.
+- После правок — **`tooling-and-review/post-change-lint.md`**: `lint:js` + `lint:css` + `type-check`; менеджер пакетов — `tooling-and-review/package-manager.md`.
+
+## Чеклист (порядок работ)
+
+1. **Доменные типы** — `app/src/types/**`, экспорт через barrel `app/src/types/index.ts` (`architecture/types-public-imports.md`, **`architecture/layer-barrel-exports.md`**); JSDoc полей — `stack/types-jsdoc.md`.
+2. **Контракт API** — DTO ответов/запросов там, где принято в репо; целевые доменные типы в `@/types`.
+3. **Мапперы** — DTO → домен в `*responseMappers.ts` или аналоге; чистые функции (`api-and-data/api-services.md`).
+4. **Сервисы** — `app/src/api/services/<ServiceRoot>/<Segment>/`: вызовы только через прикладные клиенты `app/src/api/clients/**`, public API модуля (`api-and-data/api-services.md`, `api-and-data/http-client.md`, **`architecture/layer-barrel-exports.md`**). Без `fetch` из UI/store. Новые публичные экспорты (фасады, типы, **константы путей** для моков) — в **`app/src/api/index.ts`** (`@/api`).
+5. **Моки (MSW)** — `app/src/mocks/data/<feature>/`: `data.ts`, `handlers.ts`; собрать хендлеры в **`app/src/mocks/handlers.ts`**. В хендлерах — **те же константы путей**, что и в API (импорт из `@/api`), **не дублировать сырые строки URL**. В репозитории могут быть **два контура** (браузерный worker и Node `setupServer` для тестов): общий список хендлеров должен оставаться согласованным — при добавлении проверять входные точки в `app/src/mocks/**`. Точка входа регистрации (например `app/src/mocks/index.js`).
+6. **Состояние** — `app/src/store/slices/<FeatureName>/`: `createSlice` / `createAsyncThunk`, доменные модели в state (`api-and-data/store-rtk.md`); thunk вызывает сервисы из `@/api`. Подключить редюсер в **`app/src/store/reducers.ts`**. Новый **middleware**: `app/src/store/middleware/**`, регистрация в **`app/src/store/index.ts`** в цепочке `configureStore` (порядок `prepend`/`concat` — как у соседних middleware).
+7. **UI** — `app/src/ui/pages/<FeatureName>Page/**` и/или `app/src/ui/components/**`; стили — как в проекте; тонкие компоненты, типы из `@/types`, без DTO (`ui-and-accessibility/react-ui.md`, `architecture/architecture-boundaries.md`, `ui-and-accessibility/no-props-spread.md`). Данные и загрузка — через store/hooks, без прямого HTTP.
+8. **Unit‑тесты** — `*.spec.ts` / `*.spec.tsx` (`testing/tests-unit.md`); мапперы и нетривиальная логика — обязательно; e2e Jest не запускает (см. `jest.config.js`). При смене HTTP‑клиента — behavior‑тесты (`api-and-data/http-client.md`).
+9. **E2E** — план: `app/__tests__/e2e/<Area>/<plan>.cases.md`; реализация: `*.spec.ts` рядом (`testing/tests-e2e-structure.md`, `testing/playwright-agents.md`).
+10. **Завершение** — **`tooling-and-review/post-change-lint.md`**: из `app/` обязательно `lint:js` + `lint:css` (полный прогон), затем `type-check`.
+
+## Полный flow (слой за слоем)
+
+```mermaid
+flowchart LR
+  typesNode["types_domain"]
+  apiNode["api_services_mappers"]
+  mocksNode["mocks_msw"]
+  storeNode["store_slice_thunks"]
+  mwNode["middleware_optional"]
+  uiNode["ui_pages_components"]
+  unitNode["unit_tests"]
+  e2eNode["e2e_plans_specs"]
+
+  typesNode --> apiNode
+  apiNode --> mocksNode
+  apiNode --> storeNode
+  storeNode --> mwNode
+  storeNode --> uiNode
+  apiNode --> unitNode
+  storeNode --> unitNode
+  uiNode --> unitNode
+  uiNode --> e2eNode
+  mocksNode --> e2eNode
+```
+
+## Поток данных (ориентир)
+
+```mermaid
+flowchart LR
+  subgraph transport [Транспорт]
+    HttpClient[HttpClient]
+  end
+  DTO[DTO] --> Mappers[Мапперы]
+  Mappers --> Domain[Доменные типы]
+  Domain --> Service[API сервис]
+  Service --> HttpClient
+  Service --> Thunk[Thunk]
+  Thunk --> Store[Store]
+  Store --> UI[UI]
+```
+
+## Частичные сценарии (вход с середины)
+
+| Задача | Минимум действий |
+|--------|------------------|
+| Только API + типы | Типы в `app/src/types/**`, сервис и мапперы, реэкспорт в `app/src/api/index.ts`; unit на маппер. |
+| Только моки | Константа пути уже в `@/api`; `handlers.ts` + данные; регистрация в `app/src/mocks/handlers.ts`; при необходимости убедиться, что хендлеры подхватываются и в браузерном, и в Node‑контуре MSW. |
+| Только store | Thunk на существующий метод `@/api`; slice + `app/src/store/reducers.ts`. |
+| Только UI | Читать готовое состояние из store; не добавлять HTTP/DTO; `data-testid` при необходимости для e2e. |
+| Только e2e | Синхронизировать `*.cases.md` и спеки; page object и `_shared`. |
+
+## Антипаттерны
+
+- DTO и структуры ответа бэкенда в UI или в нетипизированных кусках store.
+- Прямой вызов HTTP‑клиента из компонента или thunk’а в обход сервисного слоя.
+- Deep‑импорты в `app/src/api/services/**/…` из UI/store там, где принят импорт из `@/api`.
+- Проброс пропсов в компоненты через `{...props}` — см. `ui-and-accessibility/no-props-spread.md`.
+
+## Матрица: что меняю → какие правила перечитать
+
+| Зона в репозитории | Правила (`.claude/rules/`) |
+|--------------------|----------------------------|
+| `app/src/api/clients/**`, `app/src/lib/clients/**` | `api-and-data/http-client.md`; при изменении клиента — `testing/tests-unit.md` |
+| `app/src/api/services/**` | `api-and-data/api-services.md`, `architecture/layer-barrel-exports.md`; при необходимости `api-and-data/http-client.md` |
+| `app/src/store/**` | `api-and-data/store-rtk.md`, `architecture/architecture-boundaries.md`, `architecture/api-public-imports.md` |
+| `app/src/ui/**` | `ui-and-accessibility/react-ui.md`, `ui-and-accessibility/no-props-spread.md`, `architecture/types-public-imports.md`, `architecture/api-public-imports.md` |
+| `app/src/types/**` | `architecture/types-public-imports.md`, `stack/types-jsdoc.md`, `architecture/layer-barrel-exports.md` |
+| `app/__tests__/e2e/**` | `testing/tests-e2e-structure.md`, `testing/playwright-agents.md` |
+
+Path-scoped правила подгружаются при работе с соответствующими файлами; эта матрица нужна, когда открыт другой файл или идёт общий чат.
+
+## Требование к агенту
+
+При добавлении или существенном расширении фичи **пройти чеклист сверху** и при правках в зоне из таблицы **ориентироваться на указанные правила**, не смешивать слои и не обходить public API модулей.

package/presets/claude/next/rules/architecture/layer-barrel-exports.md

@@ -0,0 +1,53 @@
+# Barrel-экспорты слоёв с public API
+
+## Когда применять
+
+Для **любого слоя** (каталога, пакета, bounded context), у которого:
+
+- есть **корневой barrel** — единая точка импорта для внешних потребителей;
+- deep-импорты внутрь слоя **запрещены** снаружи (ESLint `no-restricted-imports`, правила `architecture/*-public-imports.md`).
+
+Примеры alias/entry point в разных проектах: `@/api`, `@/types`, `@/core`, `@/store`, `packages/foo`.
+
+## Два уровня barrel
+
+1. **Локальный** — `index.ts` модуля/фичи внутри слоя.
+2. **Корневой public API** — barrel слоя (например `src/<layer>/index.ts`).
+
+**Внутри** слоя — относительные импорты и пути между подмодулями. **Снаружи** — только корневой barrel и **явно разрешённые** вторичные entry points (если зафиксированы в правилах проекта, напр. `@/types/enums`).
+
+## Что реэкспортировать наружу
+
+Только символы, которые **должны быть доступны** потребителям слоя: публичные функции/сервисы/фасады, типы контракта, константы и helpers, нужные другим слоям или тестам.
+
+**Не реэкспортировать:** внутренние адаптеры, мапперы, детали транспорта, промежуточные объекты для сборки фасада внутри слоя.
+
+Группировка в корневом barrel — **по конвенции репозитория** (ориентир — соседние модули того же слоя).
+
+## Чеклист агента (обязателен)
+
+При добавлении или существенном расширении **модуля внутри регламентированного слоя**:
+
+1. Определить слой, его **корневой barrel** и доп. entry points (`architecture/*-public-imports.md`).
+2. Создать/обновить **локальный** `index.ts` — только публичные символы.
+3. Если в слое есть **фасад/агрегатор** (`*ApiService.ts`, `rootReducer`, …) — подключить модуль там.
+4. Добавить **реэкспорт** новых публичных символов в **корневой barrel** слоя.
+5. **Проверка:** grep по имени символа или пути `./<Module>` в корневом barrel; снаружи слоя нет deep-импортов.
+
+Модуль **не готов**, пока чеклист не пройден.
+
+## Как найти регламентированные слои в репозитории
+
+1. Правила `architecture/*-public-imports.md` в `.claude/rules/architecture/`.
+2. ESLint `no-restricted-imports` — паттерны `@/<layer>/*` с исключением barrel.
+3. `architecture/architecture-boundaries.md`, README проекта.
+
+## В этом репозитории
+
+| Слой | Корневой barrel | Правило импортов |
+|------|-----------------|------------------|
+| API | `app/src/api/index.ts` | `architecture/api-public-imports.md` |
+| Types | `app/src/types/index.ts` | `architecture/types-public-imports.md` (+ `@/types/enums`) |
+| Core | `app/src/core/index.ts` | ESLint: `@/core/index` |
+
+Иллюстрация двух уровней (API): локальный `services/.../<Feature>/index.ts` → фасад `*ApiService.ts` → `app/src/api/index.ts`.

package/presets/claude/next/rules/architecture/types-public-imports.md

@@ -0,0 +1,28 @@
+# Импорты из `@/types`
+
+- **Публичный API типов** — barrel `app/src/types/index.ts`, импортировать типы и интерфейсы только как `@/types` (или `@/types/index` при необходимости явного пути).
+- **Запрещено** для потребителей слоя обходить barrel: любой импорт вида `@/types/<что‑угодно>`, кроме перечисленного ниже исключения для enum.
+- Отдельно **нельзя** импортировать из вложенных файлов `*.types.ts` по путям `@/types/**/…*.types.ts` (типичный deep‑импорт).
+- **Исключение — enum**: перечисления можно импортировать только из `@/types/enums` / `@/types/enums.ts` (не из других файлов под `@/types`).
+
+## Внутри слоя `app/src/types/**`
+
+- При реализации и поддержке barrel‑файла допустимы **относительные** импорты между файлами внутри `app/src/types` (например `from './User.types'`). Это не относится к потребителям слоя.
+
+## Примеры
+
+```typescript
+// ✅ Допустимо — доменные и транспортные сущности с теми именами, что экспортирует barrel
+import type { TUserProfile } from '@/types'
+import { SomeEnum } from '@/types/enums'
+
+// ❌ Запрещено (обход публичного API)
+import type { TUserProfile } from '@/types/User.types'
+import { TransportError } from '@/types/TransportError'
+```
+
+При ревью и правках кода **не добавлять** новые импорты типов из `@/types/...` кроме `@/types` и `@/types/enums`.
+
+- Новые публичные типы — реэкспорт в `app/src/types/index.ts` по **`architecture/layer-barrel-exports.md`**.
+
+**Коллизии формулировок:** если в разных правилах расходятся детали **импорта типов**, источник правды — **этот файл** (`@/types`, `@/types/enums`).

package/presets/claude/next/rules/stack/README.md

@@ -1,3 +1,11 @@
 # Stack (Next.js, React, TypeScript)
 
-Правила уровня фреймворка и языка для пресета `next`.
+Правила уровня фреймворка и языка.
+
+| Файл | Содержание | Загрузка |
+|------|------------|----------|
+| `next-app-core.md` | Стек, структура `app/`, слои, принципы агента | session start |
+| `arrow-functions.md` | Стрелочный синтаксис | session start |
+| `no-type-assertion.md` | Ограничение `as` на границах модулей | session start |
+| `navigation-router.md` | Next vs React Router — выбор по репозиторию | session start |
+| `types-jsdoc.md` | JSDoc в `app/src/types` | `paths: app/src/types/**/*.ts` |

package/presets/claude/next/rules/stack/arrow-functions.md

@@ -0,0 +1,40 @@
+# Стрелочные функции
+
+При разработке **использовать стрелочный синтаксис** для функций, где это допустимо в TypeScript/JavaScript.
+
+## Что делать
+
+- Объявлять функции как **`const имя = (...) => { ... }`** вместо **`function имя(...) { ... }`**, если не нужны особенности объявления `function`.
+- Колбэки и обработчики — стрелочные функции: `.map((x) => ...)`, `onClick={() => ...}`.
+- React-компоненты и хуки — как стрелочные функции с явной типизацией пропсов/возврата по принятому в проекте стилю.
+
+## Исключения (допустимо не стрелка)
+
+- **Генераторы** (`function*`) — стрелкой не выразить.
+- **Методы класса** — если в коде используются классы, допустимы обычные методы (`method() {}`).
+- Когда осознанно нужны **подъём (hoisting)** или **имя функции в стеке** только у `function` — редкие случаи.
+
+## Примеры
+
+```typescript
+// ❌ Избегать для нового кода
+function formatLabel(id: string): string {
+  return id.toUpperCase()
+}
+
+// ✅ Предпочтительно
+const formatLabel = (id: string): string => {
+  return id.toUpperCase()
+}
+```
+
+```tsx
+// ✅ Предпочтительно
+const UserCard = ({ name }: { name: string }) => {
+  return <span>{name}</span>
+}
+```
+
+## Требование к агенту
+
+При генерации и правке кода **по умолчанию выбирать стрелочные функции**; отступать к `function` только в случаях из раздела исключений.

package/presets/claude/next/rules/stack/navigation-router.md

@@ -0,0 +1,56 @@
+# Навигация и роутинг: сначала стек проекта
+
+**При любой задаче, связанной с навигацией, переходами между страницами, URL, редиректами, хлебными крошками, защищёнными маршрутами или программной сменой маршрута** — перед предложением кода или импортов **нельзя** опираться на «типичный React» по умолчанию. Нужно **явно свериться со стеком целевого репозитория** и использовать **один** согласованный с проектом механизм.
+
+## Зависимости: что проверить в первую очередь
+
+1. **`package.json`** в корне приложения (например `app/package.json` в монорепо — тот пакет, который реально собирается и деплоится). Смотреть **`dependencies`** и при необходимости **`peerDependencies`**:
+   - **`next`** — Next.js; версия важна для нюансов API (сверяться с документацией под эту major).
+   - **`react-router-dom`**, **`@remix-run/*`**, **`@tanstack/react-router`** и т.д. — отдельный роутинг; не подменять их API вызовами Next без проверки, что в проекте действительно используется этот стек.
+   - **`next`** и **`react-router-dom`** одновременно — возможно легаси или гибрид; **не** выбирать API по умолчанию — смотреть раздел «Реализация в коде» ниже.
+
+2. **Монорепо / workspaces** — роутинг может жить не в корневом `package.json`. Открыть **`package.json` того workspace**, где лежат страницы и `next.config.*` / точка входа SPA.
+
+3. **Факт установки** — при сомнениях смотреть lockfile (`bun.lock`, `package-lock.json`, `pnpm-lock.yaml`, `yarn.lock`) или каталог `node_modules` у соответствующего пакета: убедиться, что заявленный пакет реально установлен, а не только прописан в документации.
+
+## Реализация роутинга в проекте (код и структура)
+
+Перед предложением паттерна навигации **свериться с тем, как уже сделано в репозитории**:
+
+1. **Дерево маршрутов**
+   - Next **App Router**: каталог **`app/`** (или `src/app/`) с `layout.tsx`, `page.tsx`, сегменты `[id]` и т.п.
+   - Next **Pages Router**: каталог **`pages/`** с `_app`, динамические `[slug].tsx`.
+   - Наличие **обоих** `app/` и `pages/` — уточнить по `next.config` и документации проекта, какой слой основной.
+
+2. **Точки входа и обёртки**
+   - Поиск по коду импортов: **`from 'next/navigation'`**, **`from 'next/router'`**, **`from 'next/link'`**, **`from 'react-router-dom'`**, **`createBrowserRouter`**, **`RouterProvider`**, **`BrowserRouter`**.
+   - Где объявлены маршруты (файловая структура Next vs конфиг маршрутов / `routes.tsx` в SPA).
+
+3. **Общие абстракции проекта**
+   - Обертки над ссылками (`@/ui/...`, `Link` из дизайн-системы), хелперы путей, константы роутов — **использовать их**, а не дублировать сырой роутер.
+
+4. **Соседние файлы фичи**
+   - Новый код навигации — в том же стиле, что страницы/хуки той же области (`next/navigation` vs `react-router-dom` как в соседних импортах).
+
+## Как определить, что использовать (сводка)
+
+1. **Зависимости** — см. раздел выше; по ним задаётся допустимый набор пакетов.
+2. **Структура** — App Router vs Pages vs SPA по каталогам и конфигу.
+3. **Фактический код** — какие импорты и обёртки уже доминируют в приложении.
+
+## Что использовать (краткая матрица)
+
+| Стек | Программная навигация / чтение пути | Ссылки |
+|------|-------------------------------------|--------|
+| **Next.js App Router** | `next/navigation` (`useRouter`, `usePathname`, `useSearchParams`, `redirect` и т.д. по документации Next для вашей версии) | `next/link` |
+| **Next.js Pages Router** | `next/router` | `next/link` |
+| **SPA + React Router** | `react-router-dom` (`useNavigate`, `useParams`, `useLocation`, …) | `<Link>` из `react-router-dom` |
+
+**Не делать:** подключать `react-router-dom` в проект на Next.js «по привычке»; импортировать хуки из `next/router` в компонентах App Router без проверки; смешивать два роутера в одном приложении без явной архитектурной причины в кодовой базе.
+
+## Требование к агенту
+
+- Перед генерацией или ревью кода навигации **коротко зафиксировать вывод** (например: «зависимости: `next` без `react-router-dom`; в коде везде `next/navigation` → используем то же») и следовать ему.
+- **Обязательная проверка:** актуальные **`dependencies`** в `package.json` нужного workspace + **как в проекте уже реализованы** маршруты и импорты (поиск по репозиторию, соседние файлы). Не полагаться только на предположение по одному признаку (например, только на наличие папки `app/`).
+- Если стек неочевиден (два роутера в зависимостях, гибрид) — **сверить lockfile / установленные пакеты** и **доминирующие импорты** в `src`/`app`, затем выбрать API.
+- Для **этого** пресета базовый ориентир — **`stack/next-app-core.md`**: Next.js; предпочитать **`next/navigation`** и **`next/link`** там, где используется App Router.

package/presets/claude/next/rules/stack/next-app-core.md

@@ -0,0 +1,83 @@
+# Стек и окружение
+
+Конкретные версии пакетов и инструментов — **из `package.json` и конфигов целевого репозитория**. Ниже — рамка preset (Next.js + React + TypeScript), без привязки к конкретному вендору UI, моков или APM:
+
+- **Фреймворк:** Next.js, React, TypeScript (strict — если включён в проекте).
+- **Сборка и Node:** как задано в репозитории.
+- **Тесты:** unit/integration — runner и библиотеки проекта; e2e — инструмент проекта (правила для агентов Playwright — в `testing/playwright-agents.md`).
+- **Моки HTTP/API:** если приняты в репо — повторять существующую схему (каталоги, регистрация, точка входа).
+- **Стили и UI:** способ стилизации и **дизайн‑система / токены** — как уже заведено в коде; приоритет общим примитивам и токенам вместо разрозненных «магических» значений.
+- **Наблюдаемость:** только если уже подключена в проекте — централизованно (клиент, обёртки), без дублирования в каждом методе.
+
+# Структура проекта (верхний уровень)
+
+- `app/` — корень Next.js приложения.
+  - `app/src/**` — исходный код приложения.
+  - `app/__tests__/e2e/**` — e2e‑тесты и планы.
+- `app/tsconfig.json`:
+  - `baseUrl: "."`
+  - `paths: { "@/*": ["./src/*"] }`
+
+**Требование:** во всех новых изменениях использовать алиас `@/*` вместо относительных импортов выше по дереву.
+
+# Архитектурные слои
+
+- **UI слой** (`app/src/ui/**`):
+  - `app/src/ui/pages/**` — страницы и контейнеры.
+  - `app/src/ui/components/**` — переиспользуемые компоненты.
+- **Store слой** (`app/src/store/**`):
+  - `app/src/store/slices/**` — модули состояния (Redux Toolkit; подробности в `api-and-data/store-rtk.md`).
+  - `app/src/store/middleware/**` — middleware для сайд‑эффектов (например, файлы, аналитика).
+- **API слой** (`app/src/api/**` — прежде всего `services/**`, плюс `clients/**`, корневой barrel `index.ts`):
+  - Сервисы и мапперы; **потребители вне каталога** импортируют только через `@/api` (`architecture/api-public-imports.md`).
+- **HTTP‑транспорт** (`app/src/lib/clients/**`, `app/src/api/clients/**`):
+  - Один механизм запросов, без разбросанного «сырого» `fetch`/`XMLHttpRequest` по фичам. Детали — **`api-and-data/http-client.md`**.
+- **Типы** (`app/src/types/**`):
+  - Доменные модели и транспортные контракты; **потребители** импортируют только через **`architecture/types-public-imports.md`** (`@/types`, `@/types/enums`).
+- **Моки и тестовые данные** (`app/src/mocks/**`):
+  - По структуре и назначению — как принято в репозитории.
+
+## Порты и адаптеры (сопоставление с каталогами)
+
+Та же идея, что в `architecture/architecture-boundaries.md` (раздел **«Порты и адаптеры»**): UI и store зависят от **контракта** к backend (`@/api` + доменные типы), реализация HTTP — в **`app/src/lib/clients/**`** и **`app/src/api/clients/**`**. Детали транспорта — `api-and-data/http-client.md`; импорты `@/api` — `architecture/api-public-imports.md`.
+
+# Общие архитектурные принципы
+
+- **Чёткое разделение слоёв**:
+  - UI знает о доменных типах (из `@/types` / `@/types/enums`) и публичных API store; при необходимости импортирует из **`@/api`** — см. `architecture/api-public-imports.md` и `architecture/architecture-boundaries.md` (**«UI и обращение к API»**).
+  - Store знает о доменных типах и вызывает API‑сервисы через **`@/api`**.
+  - API‑сервисы знают о DTO, мапперах и вызовах через клиенты из `app/src/api/clients/**` (`api-and-data/http-client.md`).
+- **Никаких «проникновений» слоёв**:
+  - UI не вызывает HTTP‑клиент и не работает с DTO; сценарии с записью в общий state — через store; узкие исключения для сервисов из UI — только по `architecture/architecture-boundaries.md`.
+  - Store не собирает запросы сам и не обходит API‑сервисы; данные для state — доменные модели после маппинга. Транспортные типы ответа/ошибки во thunk — как в `@/types`, согласованно с `api-and-data/http-client.md`, `api-and-data/store-rtk.md`.
+- **Доменная логика и state**:
+  - DTO → домен — в **мапперах** и чистых функциях (`api-and-data/api-services.md`); **редюсеры и селекторы** — узкие. Подробности — `api-and-data/store-rtk.md`.
+- **Типы — источник правды**:
+  - При коллизии по **импорту типов** — **`architecture/types-public-imports.md`**.
+  - Новые сущности — в `app/src/types/**` с экспортом через barrel.
+  - Не использовать `any`; при необходимости — `unknown` + безопасное сужение типа.
+
+# Кодстайл и качества кода
+
+- Следовать конфигам линтеров и форматтера **проекта** (`eslint`, `prettier`, `stylelint` — какие есть в репо).
+- KISS, DRY, SOLID; модульность; визуальная консистентность через UI‑примитивы и токены.
+- При добавлении нового кода **искать и копировать существующие паттерны**:
+  - Для страниц — `app/src/ui/pages/**`.
+  - Для блоков — `app/src/ui/components/**`.
+  - Для API — `app/src/api/services/**`.
+  - Для состояния — `app/src/store/slices/**`.
+
+# Работа агента
+
+При генерации кода:
+
+- При добавлении или существенном расширении фичи — **`architecture/feature-delivery-workflow.md`**.
+- Определить целевой слой (UI/store/API/типизация/тесты).
+- Найти похожие примеры и **копировать архитектурный паттерн** (структура файлов, типы, именование).
+- Не упрощать архитектуру (не тянуть DTO и HTTP в UI; вызовы сервисов из UI — только в рамках `architecture/architecture-boundaries.md`).
+- Избегать `any`; при необходимости — `unknown` с безопасным сужением.
+- После **любых** изменений — **`tooling-and-review/post-change-lint.md`** и **`tooling-and-review/package-manager.md`**.
+
+Задачи на **сеть, замену HTTP‑библиотеки, новые эндпоинты**: **`api-and-data/http-client.md`** + **`api-and-data/api-services.md`** + **`api-and-data/store-rtk.md`**.
+
+См. также **`rules/README.md`** — полный каталог правил пресета.