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, не игнорировать правилом.

Правила кода

Svelte 5: типизация props через `interface Props`

Все типизированные пропсы компонентов описываются через локальный interface Props, а деструктуризация идёт через аннотацию типа при $props():

<script lang="ts">
  import type { Snippet } from 'svelte';

  interface Props {
    label: string;
    accent?: boolean;
    children?: Snippet;
  }

  let { label, accent = false, children }: Props = $props();
</script>

Не использовать инлайн-дженерик $props<{ ... }>() — он тяжело читается и разносит тип и деструктуризацию по разным местам. Также не использовать инлайн-импорты в типах (children?: import('svelte').Snippet;) — все import type поднимаются наверх файла.

Правило «всегда interface Props + let {...}: Props = $props()» стандартным ESLint-правилом не покрывается — остаётся конвенцией.

Дизайн: новый визуальный язык

Описание дизайна — в docs/plan-redesign.md. Общие правила:

Новый дизайн живёт в web/src/app.css (корневые маршруты), старый — в web/src/app_v1.css (маршруты /v1/*).
Все повторяющиеся визуальные элементы — отдельные компоненты в web/src/lib/components/, даже «просто div с двумя стилями».

Линтинг дизайн-токенов

Запрещено «захардкоживать» дизайн: цвета, размеры, длительности и z-index обязаны приходить из CSS-переменных. Прогон: pnpm --dir web lint:all.

Цвета: только hct(...) в app.css, seed-токены (--brand-main/--brand-alt) и color-mix(...) — исключения. oklch()/rgb()/#hex в --color-* запрещены.
Размеры: --space-*, --text-*, --radius-*, --size-*.
Breakpoints: @custom-media --bp-* (объявления в app.css, используются как @media (--bp-*)).
z-index: --z-*; длительности: --duration-*, --ease-*.
В <style> svelte-компонентов: нельзя хардкодить цвета/размеры/длительности, нельзя использовать необъявленные var(--x), нельзя путать категории (color-токен в size-свойстве).

Детали: полный список правил плагина, токены-префиксы, настройка stylelint — см. web/eslint-plugins/README.md.

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

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

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

5.0 KiB Raw Blame History Unescape Escape