mirror of
https://github.com/Ku6epXBOCTuK/easy-png-tools.git
synced 2026-11-13 17:08:20 +00:00
88 lines
6.1 KiB
Markdown
88 lines
6.1 KiB
Markdown
# 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. Не добавлять исключения линтера ради отдельных модулей без записи в baseline.
|
||
|
||
## 2. Порядок изменения
|
||
|
||
- Сначала исправляются тесты или контракт, который фиксирует неверное поведение,
|
||
затем production-код — если это не отдельная продуктовая задача.
|
||
- Не начинать следующий этап плана в том же шаге: изменение атомарное, ревью
|
||
идёт между шагами (раздел 6).
|
||
|
||
## 3. Проверки
|
||
|
||
Матрица «изменение → минимальный набор проверок», состав `pnpm verify`, политика
|
||
warnings и чтение CI — в `docs/quality-gates.md`. Здесь только то, что относится
|
||
к работе агента.
|
||
|
||
`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` (обоснование — `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.
|