# Workflow для агентов

> Статус: **active**. Порядок исследования, изменения и проверки. Обязательные
> инварианты — в `AGENTS.md`, этот документ не заменяет source of truth
> подсистемы.

## 1. Подготовка к задаче

1. Прочитать `AGENTS.md` и выбрать документ по карте «что читать под задачу».
2. Найти релевантный активный план, backlog или checklist.
3. Проверить `git status`: не перезаписывать чужие незакоммиченные изменения.
4. Определить границу изменения: production UI, shared-модуль или инфраструктура
   — `AGENTS.md`, раздел «Границы изменений». Изменение shared-кода требует
   проверки production-потребителей.
5. Не добавлять исключения линтера ради отдельных модулей: осознанные
   отступления живут в конфиге правила (`allowPaths`, `allowWords`,
   `ignoreMissingPatterns`, `allowDefaultProject` —
   `web/eslint-plugins/README.md`), а не в самих проверяемых файлах.

## 2. Порядок изменения

- Сначала исправляются тесты или контракт, который фиксирует неверное поведение,
  затем production-код — если это не отдельная продуктовая задача.
- Не начинать следующий этап плана в том же шаге: изменение атомарное, ревью
  идёт между шагами (раздел 6).

## 3. Проверки

Матрица «изменение → минимальный набор проверок», состав `pnpm verify`, политика
warnings и чтение CI — в `docs/quality-gates.md`. Здесь только то, что относится
к работе агента.

`lint:all` роняет gate на любых ESLint warnings (`--max-warnings=0`).
Единственное, что он пропускает, — unused-token сообщения (неблокирующие).
Поэтому «команда прошла» не равно «нечего чинить»: нужно отдельно показать число
errors, warnings и token warnings.

E2E запускается отдельно от быстрых проверок, потому что поднимает build и
статический сервер. Для UI-изменений сначала выбирается минимальный
пользовательский поток, затем при необходимости расширяется smoke.

### Нагрузка на машину

Агент работает на компьютере пользователя, поэтому тяжёлые прогоны не
запускаются «по умолчанию»:

- Playwright-прогоны запускаются только по явной команде пользователя: один
  прогон за раз, без циклов повторов и без фонового запуска.
- Локально `workers: 1` (`web/playwright.config.ts`). Browser matrix проходит
  медленно, зато не забирает память и не мешает работе пользователя. Скорость
  проверки уступает отзывчивости компьютера.
- Нельзя запускать тяжёлый прогон параллельно с другим прогоном или в момент,
  когда пользователь работает с приложением.
- Диагностика флаков идёт от меньшего к большему: один spec, один проект,
  `--workers=1`, и только затем полный прогон.
- Таймауты не подбираются под конкретную машину. Если проверка падает из-за
  нехватки ресурсов, это фиксируется как ограничение окружения, а не лечится
  увеличением `expect.timeout` (обоснование — `docs/decisions.md`, раздел 7).
- При необходимости повторного прогона сначала спрашивается пользователь.

## 4. Работа с тестами

Политика locator-ов, запрещённые зависимости, fixtures, browser matrix и
`test.fixme` — в `docs/testing-strategy.md`. Здесь только рабочая рутина:

- Поведенческий тест проверяет пользовательский контракт, а не текущую
  реализацию.
- Спецификация вызывает общие операции из `web/e2e/helpers/page.ts`, а не
  повторяет raw-селекторы.
- Не фиксировать абсолютное число инструментов, если проверка не связана с этим
  инвариантом.
- Новые fixtures должны быть воспроизводимыми и не требовать ручного создания
  больших бинарных файлов.

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

Порядок работы с документами и карта источников истины — `docs/README.md`.
Архивирование — `docs/archive/README.md`.

## 6. Протокол ревью между шагами

После каждого шага плана агент:

1. останавливается и не начинает следующий этап;
2. перечисляет изменённые файлы и принятые решения;
3. указывает выполненные проверки и их фактический результат;
4. отдельно перечисляет warnings, fixme, долги и вопросы;
5. ждёт подтверждения на продолжение.

Коммит и пуш делает разработчик. Следующий шаг начинается только после ревью
текущего изменения; после пуша результат CI читается по процедуре из
`docs/decisions.md`, раздел 10.