Workflow для агентов

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

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

Прочитать AGENTS.md и выбрать документ по карте «что читать под задачу».
Найти релевантный активный план, backlog или checklist.
Проверить git status: не перезаписывать чужие незакоммиченные изменения.
Определить границу изменения: production UI, shared-модуль или инфраструктура — AGENTS.md, раздел «Границы изменений». Изменение shared-кода требует проверки production-потребителей.
Не добавлять исключения линтера ради отдельных модулей: осознанные отступления живут в конфиге правила (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. Протокол ревью между шагами

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

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

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

6.5 KiB Raw Blame History Unescape Escape