@bonesofspring/ai-rules 0.1.36 → 0.1.39

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`** — полный каталог правил пресета.

package/presets/claude/next/rules/stack/no-type-assertion.md

@@ -0,0 +1,52 @@
+# Не использовать `as` для приведения типов при экспорте и импорте
+
+## О чём речь
+
+Речь о **type assertion** в TypeScript: выражение вида `значение as Тип`.
+
+**Не относится к правилу** (это не assertion, а синтаксис модулей):
+
+- переименование при экспорте: `export { foo as bar }`, `export { default as Baz } from '...'`;
+- переименование при импорте: `import { foo as bar } from '...'`;
+- `import type { Foo as Bar }` — алиас типа в импорте типов.
+
+## Требование
+
+- На **публичной границе модуля** (экспорт, присваивание импортированным символам с принудительным приведением) **не использовать** `as Тип` для «подгонки» типов, если можно обойтись нормальной типизацией.
+
+## Предпочитать вместо `as`
+
+- явную аннотацию: `const x: T = ...` / `function f(): T`;
+- **дженерики** у функций и классов;
+- **`satisfies`** (когда нужно проверить совместимость без сужения до `any`);
+- сужение **`unknown`** после проверки (type guards, `zod` и т.п.);
+- правку **исходных типов/DTO/мапперов**, а не assertion на выходе.
+
+## Когда `as` допустим
+
+- взаимодействие с **не типизированными** или некорректно типизированными внешними модулями;
+- узкие места после **валидации** данных;
+- **`as const`** — литеральные типы;
+- блок **`catch (error)`** после HTTP: по возможности **`instanceof`** на **класс ошибки транспорта** из `@/types`; голый **`as`** — только если `instanceof` недоступен.
+
+## Примеры
+
+```typescript
+// ❌ Плохо: assertion на экспортируемом API
+export const config = loadRaw() as AppConfig
+
+// ✅ Лучше: аннотация + проверка или маппер
+export const config: AppConfig = mapToAppConfig(loadRaw())
+
+// ❌ Плохо: сразу после импорта «ломаем» тип
+import { getData } from './api'
+export const data = getData() as MyDto[]
+
+// ✅ Лучше: типизировать getData / обернуть типобезопасной функцией
+```
+
+## Требование к агенту
+
+При ревью и генерации кода **не добавлять** новые `as Тип` на экспортируемые сущности без явной необходимости.
+
+В слайсах и сервисах при обработке ошибок API сначала рассматривать **`instanceof`** на класс ошибки транспорта из `@/types` (`api-and-data/http-client.md`, `api-and-data/store-rtk.md`).

package/presets/claude/next/rules/stack/types-jsdoc.md

@@ -0,0 +1,37 @@
+---
+paths:
+  - app/src/types/**/*.ts
+---
+
+# Документация типов в `app/src/types`
+
+При добавлении или существенном изменении типов в этом слое **следовать уже принятому в репозитории стилю JSDoc** (см. примеры: `User.types.ts`, `Common.types.ts`, `ServerValidation.types.ts`, `TreatmentPlan/*.types.ts`).
+
+## Язык и форма
+
+- Текст комментариев — **на русском**, кратко и по делу.
+- **Не использовать** `@param`, `@returns`, `@see`, `@deprecated` для описания типов — достаточно обычного текста в `/** … */`.
+
+## Экспортируемый `type` / `interface`
+
+- Сразу **перед объявлением** — блок `/** … */`.
+- Для вложенных объектов — отдельный блок над каждым объявлением.
+
+## Поля
+
+- У **каждого** публичного свойства — **однострочный** `/** … */` над полем.
+- Если поле **вычисляется на фронте** — префикс **`[computed]`**.
+- Форматы данных указывать **в тексте** (например дата `YYYY-MM-DD`).
+
+## Классы и enum
+
+- Для **классов** — блок над классом и комментарии к публичным полям.
+- В `enums.ts` исторически часто **без JSDoc** на каждом члене; для новых enum допустимо описание **над enum**.
+
+## Практика для агента
+
+- Не оставлять новые публичные поля без пояснения, если смысл не равен имени на 100%.
+- Поддерживать **тот же стиль**, что в файле.
+- Одна-две фразы на тип, одна строка на поле — норма.
+
+См. также импорты и barrel: `architecture/types-public-imports.md`.

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

@@ -1,3 +1,11 @@
 # Testing
 
-Unit-тесты, e2e, структура Playwright-агентов — по отдельным `.md` при необходимости.
+Unit, e2e, Playwright agents.
+
+| Файл | Содержание | Загрузка |
+|------|------------|----------|
+| `playwright-agents.md` | Planner / generator / healer — структура e2e | session start |
+| `tests-unit.md` | Unit/integration, именование на русском | `paths: app/src/**/*.spec.*`, `*.test.*` |
+| `tests-e2e-structure.md` | `*.cases.md`, page objects, data-testid | `paths: app/__tests__/e2e/**` |
+
+См. также `.claude/agents/playwright-test-*.md` после `ai-rules init`.