mirror of
https://github.com/Ku6epXBOCTuK/easy-png-tools.git
synced 2026-11-13 17:08:20 +00:00
131 lines
9.9 KiB
Markdown
131 lines
9.9 KiB
Markdown
# 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 не
|
||
запускался: статусы смотрятся по отдельным job, потому что общий conclusion
|
||
прогона с `continue-on-error` у `e2e` остаётся зелёным. Процедура описана в
|
||
`docs/quality-gates.md`.
|
||
|
||
Следующий шаг начинается только после ревью текущего изменения.
|