# AGENTS.md

Инструкции для агентов (и IDE-ассистентов) по работе с этим репозиторием.

## Стек

- **SvelteKit** (`web/`) — основное приложение, Svelte 5 (runes).
- Менеджер пакетов: **pnpm**. Запускать команды из `web/`, либо через обёртки в
  корне: `pnpm build`, `pnpm dev` (это `pnpm --dir web ...`). Не использовать
  npm.
- Сборка: `pnpm --dir web build`, проверка типов:
  `pnpm --dir web exec svelte-check --tsconfig ./tsconfig.json`, тесты:
  `pnpm --dir web test` (Vitest), e2e: `pnpm --dir web test:e2e` (Playwright,
  `web/e2e/`, свой webServer на `pnpm build` + `scripts/serve-static.mjs`, порт
  4173).
- Форматирование: `pnpm format` в корне (оба прогона) или
  `pnpm --dir web format` (только код web/). Проверка: `pnpm check:docs`
  (docs) + `pnpm --dir web exec prettier --check .` (код).
- Линтинг: `pnpm --dir web lint` (ESLint). Полный прогон дизайн-проверок:
  `pnpm --dir web lint:all` (ESLint + stylelint + токен-аудит). Каждый шаг
  выполняется, даже если предыдущий упал. Текущие «ожидаемые долги» (hardcoded
  размеры в kit до C19, не-Prefix токены в `app_v1.css`) — техдолг: чинить
  только по заведённым tasks, не игнорировать правилом.

## Правила кода

Синтаксические ограничения описывать не нужно — они проверяются линтером
(весь список правил и токены-префиксы в `web/eslint-plugins/README.md`,
прогон: `pnpm --dir web lint` / `pnpm --dir web lint:all`). Здесь — только то,
что линтер не умеет.

### Svelte 5

Типизация пропсов через локальный `interface Props` закреплена правилом
`conventions/interface-props`; руками его нигде дублировать не надо.

### Сначала искать

Новая константа или тип не заводится, пока не произведён поиск существующего
определения (по ключу в соседних модулях и по всему `web/src/`). Это правило
в первую очередь для ИИ-агентов: дублирующее определение ухудшает правки в
нескольких местах и запутывает. (Синтаксис самих определений — под линтером:
строка `conventions/no-string-union-alias` и т.д.)

### Дизайн

Описание нового визуального языка — в `docs/plan-redesign.md`. Общие правила,
которые линтер не проверяет:

- Новый дизайн живёт в `web/src/app.css` (корневые маршруты), старый — в
  `web/src/app_v1.css` (маршруты `/v1/*`).
- Все повторяющиеся визуальные элементы — отдельные компоненты в
  `web/src/lib/components/`, даже «просто div с двумя стилями».
- Дизайн-токены (цвета, размеры, длительности, z-index) — только из
  CSS-переменных; детали ограничений — в `web/eslint-plugins/README.md`.

### Изоляция веток old ↔ new

Старый (`v1/`) и новый UI изолированы: `isolation/no-mixed-imports` резолвит
каждый импорт до файла и запрещает смешивание.

- Trunk-based: коммиты делает разработчик после ревью, самому не коммитить.
  Изменения делать небольшими (< ~500 строк), атомарными.