docs: large update docs

2026-11-13 17:08:20 +00:00 · 2026-09-25 14:20:44 +05:00
parent c187619933
commit acf9f19f1b
13 changed files with 379 additions and 82 deletions
@@ -0,0 +1,103 @@
+# Workflow для агентов
+
+> Статус: **active**. Подробная процедура работы с репозиторием; краткие
+> обязательные правила остаются в `AGENTS.md`. Этот документ не заменяет source
+> of truth конкретной подсистемы.
+
+## 1. Подготовка к задаче
+
+1. Прочитать `AGENTS.md` и `docs/README.md`.
+2. Найти релевантный активный план, backlog или checklist.
+3. Проверить `git status`: не перезаписывать чужие незакоммиченные изменения.
+4. Найти существующие типы, константы, helpers и тестовые паттерны до создания
+   нового определения.
+5. Определить границу изменения:
+   - новый 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`; после Q1 их точная
+матрица будет поддерживаться в `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` после Q1;
+- тестовая архитектура — `docs/testing-strategy.md` после Q3;
+- lint implementation — `web/eslint-plugins/README.md`;
+- продуктовые решения — backlog и активные планы.
+
+Не дублировать длинные объяснения в нескольких файлах. Если правило требует
+пояснения, в `AGENTS.md` оставить короткую понятную формулировку и ссылку на
+подробный документ.
+
+### Архивирование завершённых документов
+
+- Если план или исследование больше не является рабочим источником, перенести
+  файл в `docs/archive/`.
+- В начало файла добавить `Статус`, `Архивирован`, `Удалить после` и причину.
+- Архив хранить 30 дней для быстрой справки; после срока удалить после проверки
+  ссылок. Если решение понадобится снова, использовать git history.
+- Не переносить активный план в архив только потому, что он пока не начат.
+
+## 6. Протокол ревью между шагами
+
+После каждого шага плана агент:
+
+1. останавливается и не начинает следующий Q-этап;
+2. перечисляет изменённые файлы и принятые решения;
+3. указывает выполненные проверки и их фактический результат;
+4. отдельно перечисляет warnings, fixme, долги и вопросы;
+5. ждёт подтверждения на продолжение.
+
+Следующий шаг начинается только после ревью текущего изменения.