План модернизации приложения

​

Цель

​

Принципы

• Сохранять текущую архитектуру, если только граница явно не вызывает лишнюю текучку, затраты производительности или видимые пользователю ошибки.
• Предпочитать минимальный корректный патч для каждой проблемы, затем повторять.
• Отделять обязательные исправления от необязательной полировки, чтобы мейнтейнеры могли принимать ценную работу без ожидания субъективных решений.
• Держать поведение, обращенное к плагинам, задокументированным и обратно совместимым.
• Проверять поставленное поведение, контракты зависимостей и тесты перед заявлением, что регрессия исправлена.
• Сначала улучшать основной пользовательский путь: онбординг, аутентификацию, чат, настройку провайдера, управление плагинами и диагностику.

​

Фаза 1: базовый аудит

• Определите ключевые пользовательские рабочие процессы и кодовые поверхности, которые ими владеют.
• Перечислите неработающие элементы управления, дублирующиеся настройки, неясные состояния ошибок и дорогие пути рендеринга.
• Зафиксируйте текущие команды валидации для каждой поверхности.
• Пометьте проблемы как обязательные, рекомендуемые или необязательные.
• Задокументируйте известные блокеры, которым нужно ревью владельца, особенно изменения API, безопасности, релиза и контрактов плагинов.

• Один список проблем со ссылками на файлы от корня репозитория.
• У каждой проблемы есть серьезность, поверхность владельца, ожидаемое влияние на пользователя и предложенный путь валидации.
• Спекулятивные задачи очистки не смешаны с обязательными исправлениями.

​

Фаза 2: очистка продукта и UX

• Уточните текст онбординга и пустых состояний вокруг аутентификации моделей, статуса gateway и настройки плагинов.
• Удалите или отключите неработающие элементы управления там, где действие невозможно.
• Держите важные действия видимыми на разных адаптивных ширинах вместо того, чтобы скрывать их за хрупкими предположениями макета.
• Консолидируйте повторяющиеся формулировки статусов, чтобы у ошибок был один источник истины.
• Добавьте постепенное раскрытие для расширенных настроек, сохраняя быструю базовую настройку.

• Ручной счастливый путь для первой настройки и запуска существующим пользователем.
• Сфокусированные тесты для любой логики маршрутизации, сохранения конфигурации или вывода статуса.
• Скриншоты браузера для измененных адаптивных поверхностей.

​

Фаза 3: укрепление frontend-архитектуры

• Переносите повторяющиеся преобразования состояния UI в узкие типизированные хелперы.
• Разделяйте ответственность за загрузку данных, сохранение и представление.
• Предпочитайте существующие хуки, хранилища и паттерны компонентов новым абстракциям.
• Разделяйте слишком крупные компоненты только тогда, когда это снижает связанность или проясняет тесты.
• Не вводите широкое глобальное состояние для локальных взаимодействий панелей.

• Не меняйте публичное поведение как побочный эффект разделения файлов.
• Сохраняйте поведение доступности для меню, диалогов, вкладок и клавиатурной навигации.
• Проверьте, что состояния загрузки, пустого результата, ошибки и оптимистичные состояния по-прежнему рендерятся.

​

Фаза 4: производительность и надежность

• Измерьте затраты запуска, переходов между маршрутами, больших списков и стенограммы чата.
• Заменяйте повторяющиеся дорогие производные данные мемоизированными селекторами или кэшированными хелперами там, где профилирование доказывает пользу.
• Сократите устранимые сетевые или файловые сканирования на горячих путях.
• Сохраняйте детерминированный порядок для prompt, реестра, файлов, плагинов и сетевых входных данных перед построением payload для модели.
• Добавьте легкие регрессионные тесты для горячих хелперов и границ контрактов.

• Каждое изменение производительности фиксирует базовую линию, ожидаемый эффект, фактический эффект и оставшийся разрыв.
• Ни один perf-патч не попадает в проект только на интуиции, когда доступно дешевое измерение.

​

Фаза 5: укрепление типов, контрактов и тестов

• Заменяйте свободные runtime-строки дискриминированными объединениями или закрытыми списками кодов.
• Валидируйте внешние входные данные существующими schema-хелперами или zod.
• Добавьте контрактные тесты вокруг манифестов плагинов, каталогов провайдеров, сообщений gateway protocol и поведения миграции конфигурации.
• Держите пути совместимости в doctor или repair-потоках вместо скрытых миграций во время запуска.
• Избегайте тестовой привязки к внутренностям плагинов; используйте SDK-фасады и задокументированные barrel-файлы.

• pnpm check:changed
• Целевые тесты для каждой измененной границы.
• pnpm build, когда меняются lazy-границы, упаковка или опубликованные поверхности.

​

Фаза 6: документация и готовность к релизу

• Обновляйте документацию при изменениях поведения, API, конфигурации, онбординга или плагинов.
• Добавляйте записи changelog только для видимых пользователю изменений.
• Сохраняйте терминологию плагинов пользовательской; используйте внутренние имена пакетов только там, где это нужно контрибьюторам.
• Подтвердите, что инструкции по релизу и установке по-прежнему соответствуют текущей поверхности команд.

• Релевантная документация обновлена в той же ветке, что и изменения поведения.
• Проверки сгенерированной документации или дрейфа API проходят, если эти поверхности были затронуты.
• В handoff названа любая пропущенная валидация и причина пропуска.

​

Рекомендуемая первая часть

• Проведите аудит поверхностей первой настройки, готовности аутентификации провайдера, статуса gateway и настройки плагинов.
• Удалите неработающие действия и проясните состояния отказа.
• Добавьте или обновите сфокусированные тесты для вывода статуса и сохранения конфигурации.
• Запустите pnpm check:changed.

​

Обновление frontend-навыка

# Frontend Delivery Standards

Use this skill when implementing or reviewing user-facing React, Next.js,
desktop webview, or app UI work.

## Operating rules

- Start from the existing product workflow and code conventions.
- Prefer the smallest correct patch that improves the current user path.
- Separate required fixes from optional polish in the handoff.
- Do not build marketing pages when the request is for an application surface.
- Keep actions visible and usable across supported viewport sizes.
- Remove dead affordances instead of leaving controls that cannot act.
- Preserve loading, empty, error, success, and permission states.
- Use existing design-system components, hooks, stores, and icons before adding
  new primitives.

## Implementation checklist

1. Identify the primary user task and the component or route that owns it.
2. Read the local component patterns before editing.
3. Patch the narrowest surface that solves the issue.
4. Add responsive constraints for fixed-format controls, toolbars, grids, and
   counters so text and hover states cannot resize the layout unexpectedly.
5. Keep data loading, state derivation, and rendering responsibilities clear.
6. Add tests when logic, persistence, routing, permissions, or shared helpers
   change.
7. Verify the main happy path and the most relevant edge case.

## Visual quality gates

- Text must fit inside its container on mobile and desktop.
- Toolbars may wrap, but controls must remain reachable.
- Buttons should use familiar icons when the icon is clearer than text.
- Cards should be used for repeated items, modals, and framed tools, not for
  every page section.
- Avoid one-note color palettes and decorative backgrounds that compete with
  operational content.
- Dense product surfaces should optimize for scanning, comparison, and repeated
  use.

## Handoff format

Report:

- What changed.
- What user behavior changed.
- Required validation that passed.
- Any validation skipped and the concrete reason.
- Optional follow-up work, clearly separated from required fixes.