easy-png-tools2/docs/agent-workflow.md

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

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

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

1. Прочитать `AGENTS.md` и `docs/README.md`.
2. Найти релевантный активный план, backlog или checklist.
3. Проверить `git status`: не перезаписывать чужие незакоммиченные изменения.
4. Найти существующие типы, константы, helpers и тестовые паттерны до создания
   нового определения.
5. Определить границу изменения:
   - 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. Протокол ревью между шагами

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

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

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

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