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 строк), атомарными.

4.0 KiB Raw Blame History