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 check, тесты: pnpm --dir web test (Vitest), тесты lint-правил: pnpm --dir web test:rules, 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 . (код).
Полный быстрый gate: pnpm verify; подробная матрица команд и CI — docs/quality-gates.md.
Линтинг: pnpm --dir web lint (ESLint). Полный прогон дизайн-проверок: pnpm --dir web lint:all (ESLint + stylelint + токен-аудит). Каждый шаг выполняется, даже если предыдущий упал. app_v1.css и legacy-ветка исключены из новых правил; их долг чинится только по заведённым задачам, а новые изменения не должны добавлять новые предупреждения без записи в baseline.

Правила кода

Синтаксические ограничения описывать не нужно — они проверяются линтером (весь список правил и токены-префиксы в 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.

Документация

Здесь держать только обязательные инварианты, команды и ссылки на подробные документы; не превращать AGENTS.md в полный справочник.
Индекс активных документов: docs/README.md; подробный workflow: docs/agent-workflow.md; quality gates: docs/quality-gates.md; текущий план: docs/plan-codebase-quality.md.
Новые подробные правила, процедуры и таблицы хранить в docs/, а детали конкретных lint-правил — в web/eslint-plugins/README.md.
Завершённые или устаревшие документы переносить в docs/archive/, указывать дату архивирования и срок удаления; архив — только справка, не источник требований.

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

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

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

5.2 KiB Raw Blame History