# 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`.
- После пуша результат 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` и т.д.)

### Дизайн

Описание нового визуального языка — в `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 строк), атомарными.