mirror of
https://github.com/Ku6epXBOCTuK/easy-png-tools.git
synced 2026-11-13 17:08:20 +00:00
106 lines
7.7 KiB
Markdown
106 lines
7.7 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.
|
|
|
|
## 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. ждёт подтверждения на продолжение.
|
|
|
|
Следующий шаг начинается только после ревью текущего изменения.
|