# AGENTS.md

Краткий обязательный контракт. Правило: **у каждой темы ровно один источник
истины**; здесь только то, что агент обязан знать до чтения остального, и то,
что линтер не проверяет. Подробности — по ссылкам ниже.

## Стек и команды

- **SvelteKit** (`web/`) — основное приложение, Svelte 5 (runes).
- **pnpm** обязателен, npm не использовать. Команды — из корня (`pnpm build`,
  `pnpm dev`, `pnpm verify`) или из `web/` с префиксом `pnpm --dir web`.

| Что                     | Команда                                           |
| ----------------------- | ------------------------------------------------- |
| Полный быстрый gate     | `pnpm verify`                                     |
| Типы                    | `pnpm --dir web check`                            |
| Юнит-тесты              | `pnpm --dir web test`                             |
| Тесты lint-правил       | `pnpm --dir web test:rules`                       |
| Линтинг                 | `pnpm --dir web lint:all`                         |
| Только токены           | `pnpm --dir web lint:tokens`                      |
| E2E                     | `pnpm --dir web test:e2e`                         |
| Форматирование          | `pnpm format` (код + docs)                        |
| Проверка форматирования | `pnpm check:docs` + `pnpm --dir web format:check` |

## Что читать под задачу

Читать только нужную строку, а не все документы подряд.

| Задача                                        | Документ                           |
| --------------------------------------------- | ---------------------------------- |
| Слои, поток данных, новый инструмент/поле     | `docs/architecture.md`             |
| Какие проверки запускать, пороги, CI          | `docs/quality-gates.md`            |
| Правка самих гейтов: «почему так, а не иначе» | `docs/decisions.md`                |
| Порядок работы, нагрузка на машину            | `docs/agent-workflow.md`           |
| Locator-ы, fixtures, browser matrix           | `docs/testing-strategy.md`         |
| Детали lint-правил и токенов                  | `web/eslint-plugins/README.md`     |
| Задачи и идеи                                 | `docs/backlog.md`                  |
| Актуальный список инструментов                | `docs/tools-map.md`                |
| Правка полей и раскладки по волнам            | `docs/plan-fields-audit-fixes.md`  |
| Ручная приёмка UI                             | `docs/checklist-manual-testing.md` |
| Индекс остальных документов                   | `docs/README.md`                   |

## Инварианты, которые линтер не проверяет

- **Сначала искать.** Новая константа, тип или утилита не заводится, пока не
  найдено существующее определение — по ключу в соседних модулях и по всему
  `web/src/`.
- **Комментарий объясняет «почему»**, а не пересказывает код. `TODO`/`FIXME` —
  только для зарегистрированной задачи: ссылка на `docs/backlog.md` и критерий
  закрытия.
- **Один шаг — одна проблема**, примерно до 500 строк; не смешивать lint, i18n,
  UI и рефакторинг.
- **Не коммитить.** Коммит и пуш делает разработчик после ревью.
- **Не запускать тяжёлое без спроса.** Playwright — только по явной команде
  пользователя, один прогон, без циклов повторов и фонового запуска.
- **Не писать изменяемые числа** (количество инструментов, тестов, локалей,
  проценты покрытия): вместо числа — ссылка на источник или команда. Число
  допустимо, только если его проверяет конфиг или тест. Обоснование и границы
  автоматизации — `docs/decisions.md`, раздел 3.
- **Результат CI смотреть по отдельным job**: у `e2e` стоит `continue-on-error`,
  поэтому общий conclusion может быть зелёным при красном e2e
  (`docs/decisions.md`, раздел 10).

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

- Production-UI — `web/src/routes/**` и `web/src/lib/components/**`.
- `web/src/lib/core/**` и `web/src/lib/theme.svelte.ts` — общие модули: их
  правка проверяется unit-тестами и smoke-сценариями production-потребителей.
- Направление зависимостей, точки расширения и рецепт правки (инструмент, вид
  поля, маршрут, токен) — `docs/architecture.md`, разделы 1–2, 7, 8.

## Что проверяется линтером

`pnpm --dir web lint:all` — ESLint с `--max-warnings=0` (warn-only правила тоже
блокируют gate), Stylelint и token audit. Синтаксические ограничения здесь не
дублируются: полный список правил и префиксы токенов —
`web/eslint-plugins/README.md`; новое правило сначала появляется в warn-only
режиме с fixtures и тестами (`test:rules`).

- **E2E линтером не покрыт:** порядок locator-ов, допустимые `data-testid`,
  `test.fixme` — `docs/testing-strategy.md`.

## Дизайн

Источник правды по визуальному языку — код: `web/src/app.css` (дизайн-токены и
глобальные стили), `web/src/lib/components/**` и витрина `/kit`. Новый дизайн
живёт в `app.css` и применяется ко всем production-маршрутам; повторяющийся
визуальный элемент — отдельный компонент, даже «просто div с двумя стилями»;
дизайн-токены — только из CSS-переменных, новый токен появляется вместе с
потребителем (`pnpm --dir web lint:tokens` сообщает о неиспользуемых). Приёмка —
`docs/checklist-manual-testing.md`.

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

- Новый документ создаётся, только если темы нет в существующем; иначе
  обновляется источник истины. У документа есть статус (`draft`, `active`,
  `completed`, `archived`).
- Не дублировать длинные объяснения в нескольких файлах: короткая формулировка и
  ссылка на канонический документ.
- **Backlog живёт открытыми задачами:** выполненные удаляются, а критичные для
  проекта факты переносятся в тематический документ. Завершённые планы и
  исследования — в `docs/archive/`, удаляются через 30 дней; процедура в
  `docs/archive/README.md`.