Workflow для агентов

Статус: active. Подробная процедура работы с репозиторием; краткие обязательные правила остаются в AGENTS.md. Этот документ не заменяет source of truth конкретной подсистемы.

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

Прочитать AGENTS.md и docs/README.md.
Найти релевантный активный план, backlog или checklist.
Проверить git status: не перезаписывать чужие незакоммиченные изменения.
Найти существующие типы, константы, helpers и тестовые паттерны до создания нового определения.
Определить границу изменения:
- production UI — web/src/routes/** и web/src/lib/components/**;
- shared — web/src/lib/core/** и web/src/lib/theme.svelte.ts.

Изменение shared-кода требует проверки production-потребителей. Не добавлять исключения линтера ради отдельных модулей без записи в baseline.

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

Сначала исправляются тесты или контракт, который фиксирует неверное поведение, затем production-код — если это не отдельная продуктовая задача.
Один PR решает одну проблему и не объединяет lint, i18n, UI и архитектурный рефакторинг без необходимости.
Изменения держатся небольшими и атомарными, примерно до 500 строк или меньше.
Не добавлять комментарии, которые пересказывают код. Комментарий объясняет причину решения или фиксирует неочевидный инвариант.
Не коммитить изменения автоматически: коммит делает разработчик после ревью.

3. Проверки

Команды и их область применения перечислены в AGENTS.md; точная матрица и текущая политика warnings/errors поддерживаются в docs/quality-gates.md.

Изменение	Минимальная проверка
Только Markdown	`pnpm check:docs`
TypeScript/Svelte	`pnpm --dir web check`, `pnpm --dir web test`
Lint-конфиг или custom rule	`pnpm --dir web test:rules`, `pnpm --dir web lint:all`
Маршрут, загрузка, результат, download, тема или локаль	`pnpm --dir web test:e2e`
Перед релизом	полный quality gate из плана Q1

lint:all может завершиться успешно при warnings. Это не означает чистый baseline: нужно отдельно показать число errors, warnings и token warnings.

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

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

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

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

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

Поведенческий тест проверяет пользовательский контракт, а не текущую реализацию.
Сначала предпочитать role, aria-*, label, stable id или href.
data-testid ограничен source/result/verdict/empty-state; общие locator-паттерны собраны в web/e2e/helpers/page.ts, policy — в docs/testing-strategy.md.
data-testid использовать только там, где семантического locator нет.
Не фиксировать абсолютное число инструментов, если проверка не связана с этим инвариантом.
Точные переводы проверять в словарях и i18n helpers; в e2e проверять поведение и отдельный locale smoke.
test.fixme допускается только для зарегистрированной проблемы или явного тестового долга, с ссылкой на backlog или checklist. После исправления тест и его issue обновляются вместе.
Новые fixtures должны быть воспроизводимыми и не требовать ручного создания больших бинарных файлов.

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

Источник истины выбирается по теме:

обязательное поведение агента — AGENTS.md;
индекс и карта документов — docs/README.md;
качество и точные команды — docs/quality-gates.md;
тестовая архитектура — docs/testing-strategy.md;
lint implementation — web/eslint-plugins/README.md;
продуктовые решения — backlog и активные планы.

Не дублировать длинные объяснения в нескольких файлах. Если правило требует пояснения, в AGENTS.md оставить короткую понятную формулировку и ссылку на подробный документ.

Архивирование завершённых документов

Если план или исследование больше не является рабочим источником, перенести файл в docs/archive/.
В начало файла добавить Статус, Архивирован, Удалить после и причину.
Архив хранить 30 дней для быстрой справки; после срока удалить после проверки ссылок. Если решение понадобится снова, использовать git history.
Не переносить активный план в архив только потому, что он пока не начат.

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

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

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

Коммит и пуш делает разработчик. После пуша агент проверяет результат CI и сообщает его вместе с локальными проверками, включая случай, когда нужный job не запускался: Quality workflow с browser matrix живёт на pull_request и workflow_dispatch, поэтому прямой пуш в main проверяет только быстрый gate. Процедура описана в docs/quality-gates.md.

Следующий шаг начинается только после ревью текущего изменения.

9.9 KiB Raw Blame History Unescape Escape