docs: update a lot of plans, readmes, descriptions

2026-11-13 17:08:20 +00:00 · 2026-09-27 09:10:26 +05:00
parent 9c6f223b13
commit 82207c82f2
47 changed files with 1029 additions and 4615 deletions
@@ -1,129 +1,102 @@
 # AGENTS.md

-Инструкции для агентов (и IDE-ассистентов) по работе с этим репозиторием.
+Краткий обязательный контракт. Правило: **у каждой темы ровно один источник
+истины**; здесь только то, что агент обязан знать до чтения остального, и то,
+что линтер не проверяет. Подробности — по ссылкам ниже.

-## Стек
+## Стек и команды

 - **SvelteKit** (`web/`) — основное приложение, Svelte 5 (runes).
- Менеджер пакетов: **pnpm**. Запускать команды из `web/`, либо через обёртки в
-  корне: `pnpm build`, `pnpm dev` (это `pnpm --dir web ...`). Не использовать
-  npm.
- Сборка: `pnpm --dir web build`, проверка типов: `pnpm --dir web check`, тесты:
-  `pnpm --dir web test` (Vitest), тесты с coverage-гейтом:
-  `pnpm --dir web test:coverage`, тесты lint-правил:
-  `pnpm --dir web test:rules`, e2e: `pnpm --dir web test:e2e` (Playwright,
-  `web/e2e/`, свой webServer на `pnpm build` + `scripts/serve-static.mjs`, порт
-  4173).
- Форматирование: `pnpm format` в корне (оба прогона) или
-  `pnpm --dir web format` (только код web/). Проверка: `pnpm check:docs`
-  (docs) + `pnpm --dir web format:check` (код).
- Полный быстрый gate: `pnpm verify`; подробная матрица команд и CI —
-  `docs/quality-gates.md`.
- После пуша результат CI проверяется явно: смотреть статусы отдельных job, а не
-  общий conclusion прогона. У `e2e` стоит `continue-on-error`, поэтому прогон с
-  упавшим e2e помечается как `success`. `Quality` workflow запускается на каждом
-  пуше в `main` и на `pull_request`, поэтому browser matrix проверяется сама;
-  ручной запуск нужен только для старого коммита.
- Линтинг: `pnpm --dir web lint` (ESLint). Полный прогон дизайн-проверок:
-  `pnpm --dir web lint:all` (ESLint + stylelint + токен-аудит). Каждый шаг
-  выполняется, даже если предыдущий упал. Новые изменения не должны добавлять
-  предупреждения без записи в baseline.
+- **pnpm** обязателен, npm не использовать. Команды — из корня (`pnpm build`,
+  `pnpm dev`, `pnpm verify`) или из `web/` с префиксом `pnpm --dir web`.

-## Правила кода
+| Что                     | Команда                                           |
+| ----------------------- | ------------------------------------------------- |
+| Полный быстрый gate     | `pnpm verify`                                     |
+| Типы                    | `pnpm --dir web check`                            |
+| Юнит-тесты              | `pnpm --dir web test`                             |
+| Тесты lint-правил       | `pnpm --dir web test:rules`                       |
+| Линтинг                 | `pnpm --dir web lint:all`                         |
+| E2E                     | `pnpm --dir web test:e2e`                         |
+| Форматирование          | `pnpm format` (код + docs)                        |
+| Проверка форматирования | `pnpm check:docs` + `pnpm --dir web format:check` |

-Синтаксические ограничения описывать не нужно — они проверяются линтером (весь
-список правил и токены-префиксы в `web/eslint-plugins/README.md`, прогон:
-`pnpm --dir web lint` / `pnpm --dir web lint:all`). Здесь — только то, что
-линтер не умеет.
+## Что читать под задачу

-### Svelte 5
+Читать только нужную строку, а не все документы подряд.

-Типизация пропсов через локальный `interface Props` закреплена правилом
-`conventions/interface-props`; руками его нигде дублировать не надо.
+| Задача                                        | Документ                           |
+| --------------------------------------------- | ---------------------------------- |
+| Слои, поток данных, новый инструмент/поле     | `docs/architecture.md`             |
+| Какие проверки запускать, пороги, CI          | `docs/quality-gates.md`            |
+| Правка самих гейтов: «почему так, а не иначе» | `docs/decisions.md`                |
+| Порядок работы, нагрузка на машину            | `docs/agent-workflow.md`           |
+| Locator-ы, fixtures, browser matrix           | `docs/testing-strategy.md`         |
+| Детали lint-правил и токенов                  | `web/eslint-plugins/README.md`     |
+| Задачи и идеи                                 | `docs/backlog.md`                  |
+| Актуальный список инструментов                | `docs/tools-map.md`                |
+| Ручная приёмка UI                             | `docs/checklist-manual-testing.md` |
+| Индекс остальных документов                   | `docs/README.md`                   |

-### E2E
+## Инварианты, которые линтер не проверяет

- Сначала используй `role`, `aria-*`, label и стабильный `href`; `data-testid`
-  разрешён только для source/result/verdict/empty-state.
- `test.fixme` допускается только для зарегистрированной задачи в backlog или
-  checklist; после исправления тест и ссылку обновляют вместе.
- Полные переводы проверяются в unit-тестах; e2e проверяет поведение.
- Playwright-прогоны запускаются только по явной команде пользователя, по одному
-  прогону, без циклов повторов и без фонового запуска: локально matrix идёт с
-  `workers: 1`. Отзывчивость компьютера пользователя важнее скорости проверки —
-  подробности в `docs/agent-workflow.md`.
+- **Сначала искать.** Новая константа, тип или утилита не заводится, пока не
+  найдено существующее определение — по ключу в соседних модулях и по всему
+  `web/src/`.
+- **Комментарий объясняет «почему»**, а не пересказывает код. `TODO`/`FIXME` —
+  только для зарегистрированной задачи: ссылка на `docs/backlog.md` и критерий
+  закрытия.
+- **Один шаг — одна проблема**, примерно до 500 строк; не смешивать lint, i18n,
+  UI и рефакторинг.
+- **Не коммитить.** Коммит и пуш делает разработчик после ревью.
+- **Не запускать тяжёлое без спроса.** Playwright — только по явной команде
+  пользователя, один прогон, без циклов повторов и фонового запуска.
+- **Не писать изменяемые числа** (количество инструментов, тестов, локалей,
+  проценты покрытия): вместо числа — ссылка на источник или команда. Число
+  допустимо, только если его проверяет конфиг или тест. Обоснование и границы
+  автоматизации — `docs/decisions.md`, раздел 3.
+- **Результат CI смотреть по отдельным job**: у `e2e` стоит `continue-on-error`,
+  поэтому общий conclusion может быть зелёным при красном e2e
+  (`docs/decisions.md`, раздел 10).

-### Сначала искать
+## Границы изменений

-Новая константа или тип не заводится, пока не произведён поиск существующего
-определения (по ключу в соседних модулях и по всему `web/src/`). Это правило в
-первую очередь для ИИ-агентов: дублирующее определение ухудшает правки в
-нескольких местах и запутывает. (Синтаксис самих определений — под линтером:
-строка `conventions/no-string-union-alias` и т.д.)
+- Production-UI — `web/src/routes/**` и `web/src/lib/components/**`. Старый UI
+  (`/v1/**`) удалён и не возвращается.
+- `web/src/lib/core/**` и `web/src/lib/theme.svelte.ts` — общие модули: их
+  правка проверяется unit-тестами и smoke-сценариями production-потребителей.
+- Направление зависимостей, точки расширения и рецепт правки (инструмент, вид
+  поля, маршрут, токен) — `docs/architecture.md`, разделы 1–2, 7, 8.

-### Границы изменений
+## Что проверяется линтером

- Production — только текущие маршруты и `web/src/lib/components/**`. Старый
-  UI (`/v1/**`) удалён и не возвращается: без redirects и совместимого режима;
-  исторические упоминания живят только в `docs/archive/`. Будущий API-контракт
-  `POST /v1/process` из `docs/plan-platform.md` не связан с удалённым UI-v1.
- `core/` и `theme/` — общие модули: их изменение проверяется unit-тестами и
-  smoke-сценариями production-потребителей.
+`pnpm --dir web lint:all` — ESLint с `--max-warnings=0` (warn-only правила тоже
+блокируют gate), Stylelint и token audit. Синтаксические ограничения здесь не
+дублируются: полный список правил и префиксы токенов —
+`web/eslint-plugins/README.md`; новое правило сначала появляется в warn-only
+режиме с fixtures и тестами (`test:rules`).

-### i18n
+- **E2E линтером не покрыт:** порядок locator-ов, допустимые `data-testid`,
+  `test.fixme` — `docs/testing-strategy.md`.

- Новый пользовательский текст — только через словари и `t()`. Исключения:
-  бренд, форматы и имена файлов, технические значения, registry source strings и
-  `/kit`. Проверяется warn-правилом `i18n/no-hardcoded-user-text`, детали и
-  список исключений — в `web/eslint-plugins/README.md`.
- Новые ключи добавляются во **все** локали сразу: паритет ключей и
-  плейсхолдеров проверяет `i18n/dict-consistency`.
+## Дизайн

-### Комментарии
-
- Комментарий объясняет «почему», а не пересказывает код.
- `TODO`/`FIXME` — только зарегистрированные задачи: ссылка на `docs/backlog.md`
-  или issue и критерий закрытия. В коде незарегистрированных пометок не
-  оставляем.
-
-### Новые lint-правила
-
-Новое правило сначала появляется в report-only/warn-only режиме, получает
-fixtures и тесты (`test:rules`), и только после очистки baseline может стать
-blocking. Учитывай: `lint:all` гоняет ESLint с `--max-warnings=0`, поэтому
-warn-правило обязано приземлиться без срабатываний на текущем коде.
-
-
-### Дизайн
-
-Источник правды по визуальному языку — сам код: `web/src/app.css` (дизайн-токены
-и глобальные стили), `web/src/lib/components/**` (компоненты и локальные стили)
-и витрина `/kit`. Приёмка — `docs/checklist-manual-testing.md`, ограничения
-линтера — `web/eslint-plugins/README.md`. Общие правила, которые линтер не
-проверяет:
-
- Новый дизайн живёт в `web/src/app.css` и применяется ко всем
-  production-маршрутам.
- Все повторяющиеся визуальные элементы — отдельные компоненты в
-  `web/src/lib/components/`, даже «просто div с двумя стилями».
- Дизайн-токены (цвета, размеры, длительности, z-index) — только из
-  CSS-переменных; детали ограничений — в `web/eslint-plugins/README.md`.
- Новый токен появляется вместе с потребителем: `pnpm --dir web lint:tokens`
-  сообщает о неиспользуемых токенах, и это не блокирует CI только потому, что
-  проверка оставлена предупреждением.
+Источник правды по визуальному языку — код: `web/src/app.css` (дизайн-токены и
+глобальные стили), `web/src/lib/components/**` и витрина `/kit`. Новый дизайн
+живёт в `app.css` и применяется ко всем production-маршрутам; повторяющийся
+визуальный элемент — отдельный компонент, даже «просто div с двумя стилями»;
+дизайн-токены — только из CSS-переменных, новый токен появляется вместе с
+потребителем (`pnpm --dir web lint:tokens` сообщает о неиспользуемых). Приёмка —
+`docs/checklist-manual-testing.md`.

 ## Документация

- Здесь держать только обязательные инварианты, команды и ссылки на подробные
-  документы; не превращать `AGENTS.md` в полный справочник.
- Индекс активных документов: `docs/README.md`; подробный workflow:
-  `docs/agent-workflow.md`; quality gates: `docs/quality-gates.md`; тестовая
-  архитектура: `docs/testing-strategy.md`.
- Новые подробные правила, процедуры и таблицы хранить в `docs/`, а детали
-  конкретных lint-правил — в `web/eslint-plugins/README.md`.
- Завершённые или устаревшие документы переносить в `docs/archive/`, указывать
-  дату архивирования и срок удаления; архив — только справка, не источник
-  требований.
-
- Trunk-based: коммиты делает разработчик после ревью, самому не коммитить.
-  Изменения делать небольшими (< ~500 строк), атомарными.
+- Новый документ создаётся, только если темы нет в существующем; иначе
+  обновляется источник истины. У документа есть статус (`draft`, `active`,
+  `completed`, `archived`).
+- Не дублировать длинные объяснения в нескольких файлах: короткая формулировка и
+  ссылка на канонический документ.
+- **Backlog живёт открытыми задачами:** выполненные удаляются, а критичные для
+  проекта факты переносятся в тематический документ. Завершённые планы и
+  исследования — в `docs/archive/`, удаляются через 30 дней; процедура в
+  `docs/archive/README.md`.