Workflow для агентов

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

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

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

Изменение shared-кода требует проверки обеих веток. Смешивание old/new нельзя обходить относительными импортами или исключениями линтера.

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 использовать только там, где семантического 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 после Q3;
lint implementation — web/eslint-plugins/README.md;
продуктовые решения — backlog и активные планы.

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

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

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

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

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

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

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

7.5 KiB Raw Blame History Unescape Escape