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 + токен-аудит). Каждый шаг выполняется, даже если предыдущий упал. Новые изменения не должны добавлять предупреждения без записи в baseline.

Правила кода

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

Svelte 5

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

E2E

Сначала используй role, aria-*, label и стабильный href; data-testid разрешён только для source/result/verdict/empty-state.
test.fixme допускается только для зарегистрированной задачи в backlog или checklist; после исправления тест и ссылку обновляют вместе.
Полные переводы проверяются в unit-тестах; e2e проверяет поведение.

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

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

Дизайн

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

Новый дизайн живёт в web/src/app.css и применяется ко всем production-маршрутам.
Все повторяющиеся визуальные элементы — отдельные компоненты в 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/, указывать дату архивирования и срок удаления; архив — только справка, не источник требований.
Trunk-based: коммиты делает разработчик после ревью, самому не коммитить. Изменения делать небольшими (< ~500 строк), атомарными.

5.3 KiB Raw Blame History