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), тесты с coverage-гейтом: pnpm --dir web test:coverage, тесты 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 format:check (код).
Полный быстрый gate: pnpm verify; подробная матрица команд и CI — docs/quality-gates.md.
После пуша результат CI проверяется явно: смотреть статусы отдельных job, а не общий conclusion прогона. У e2e стоит continue-on-error, поэтому прогон с упавшим e2e помечается как success. Quality workflow запускается на каждом пуше в main и на pull_request, поэтому browser matrix проверяется сама; ручной запуск нужен только для старого коммита.
Линтинг: 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 проверяет поведение.
Playwright-прогоны запускаются только по явной команде пользователя, по одному прогону, без циклов повторов и без фонового запуска: локально matrix идёт с workers: 1. Отзывчивость компьютера пользователя важнее скорости проверки — подробности в docs/agent-workflow.md.

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

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

Границы изменений

Production — только текущие маршруты и web/src/lib/components/**. Старый UI (/v1/**) удалён и не возвращается: без redirects и совместимого режима; исторические упоминания живят только в docs/archive/. Будущий API-контракт POST /v1/process из docs/plan-platform.md не связан с удалённым UI-v1.
core/ и theme/ — общие модули: их изменение проверяется unit-тестами и smoke-сценариями production-потребителей.

i18n

Новый пользовательский текст — только через словари и t(). Исключения: бренд, форматы и имена файлов, технические значения, registry source strings и /kit. Проверяется warn-правилом i18n/no-hardcoded-user-text, детали и список исключений — в web/eslint-plugins/README.md.
Новые ключи добавляются во все локали сразу: паритет ключей и плейсхолдеров проверяет i18n/dict-consistency.

Комментарий объясняет «почему», а не пересказывает код.
TODO/FIXME — только зарегистрированные задачи: ссылка на docs/backlog.md или issue и критерий закрытия. В коде незарегистрированных пометок не оставляем.

Новые lint-правила

Новое правило сначала появляется в report-only/warn-only режиме, получает fixtures и тесты (test:rules), и только после очистки baseline может стать blocking. Учитывай: lint:all гоняет ESLint с --max-warnings=0, поэтому warn-правило обязано приземлиться без срабатываний на текущем коде.

Дизайн

Источник правды по визуальному языку — сам код: web/src/app.css (дизайн-токены и глобальные стили), web/src/lib/components/** (компоненты и локальные стили) и витрина /kit. Приёмка — docs/checklist-manual-testing.md, ограничения линтера — web/eslint-plugins/README.md. Общие правила, которые линтер не проверяет:

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

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

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

9.1 KiB Raw Blame History Unescape Escape