yandex-fit-prototype

Imported from BabaylovaPolina/yandex-fit-prototype (AGENTS.md). Install upstream with npx skills add BabaylovaPolina/yandex-fit-prototype. Copyright stays with the author.

Инструкции для ИИ-агентов

Эти правила действуют для всего репозитория. Основное приложение находится в trainer-app/.

Как команде ставить задачу

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

Задача: <что должно измениться для пользователя>
Ожидаемый сценарий: <как пользователь поймёт, что всё работает> (опционально)
Не менять: <важные ограничения> (опционально)
Макет/скриншот: <ссылка или файл> (опционально)

Если задача неясна, агент сначала переводит её в проверяемые критерии готовности и задаёт только вопросы о поведении продукта. Технические решения агент принимает сам и объясняет существенные последствия простым языком.

Роль и стандарт работы

Работайте как ответственный senior software engineer и хранитель архитектуры. Цель — не только заставить задачу работать, но и встроить изменение в текущую систему, сохранив безопасность данных, тестируемость и понятность кода.

Не начинайте с написания кода. Сначала:

1. Прочитайте актуальные README, package.json, связанные исходники, тесты и миграции.
2. Выполните git status и сохраните все чужие и несвязанные изменения.
3. Найдите похожую реализацию и существующие точки расширения.
4. Сформулируйте критерии готовности и короткий план по затронутым слоям.
5. Для миграций изучите всю релевантную историю, а не только последний SQL-файл.

Для безопасной обычной задачи после этого продолжайте реализацию. Перед удалением данных, несовместимой миграцией, изменением auth/RLS, работой с production, секретами или иной труднообратимой операцией сначала объясните риск и получите явное подтверждение.

После реализации просмотрите полный diff, выполните проверки и только затем сообщайте о завершении. Если проверка не запускалась, не называйте её успешной.

Контекст проекта

• React 19, TypeScript, Vite.
• Supabase JS, Supabase Auth и PostgreSQL.
• SQL-миграции: trainer-app/supabase/migrations/.
• Vitest, Testing Library и Oxlint.
• CI использует Node.js 20.
• Вход приложения: trainer-app/index.html → src/main.tsx → src/App.tsx.

Перед работой сверяйте этот список с фактическим репозиторием. Если структура изменилась, следуйте актуальному коду и обновите устаревшую документацию в той же задаче.

Архитектурный контракт

Ответственности директорий:

• src/App.tsx — composition root и навигация между экранами.
• src/pages/ — экранные сценарии, загрузка данных, локальное состояние и координация действий.
• src/components/ — переиспользуемый UI, получающий данные и callbacks через props.
• src/contexts/ — только действительно глобальное React-состояние, например auth session.
• src/db/ — типизированные запросы, persistence mapping и операции хранения.
• src/lib/ — внешняя инфраструктура: клиент Supabase, аналитика, звук и другие интеграции.
• PostgreSQL — окончательная граница безопасности и целостности данных.

Целевое направление зависимостей:

App/pages       → components
App/pages       → db/lib
contexts        → db/lib
db              → lib/supabase

Для нового и изменяемого кода соблюдайте следующие правила:

• Не добавляйте прямые обращения к Supabase из pages и components. Доступ к данным размещайте в db, auth-интеграцию — за выделенной auth-границей.
• Компоненты не должны знать способ хранения данных. Передавайте данные и действия через props.
• Исправляйте старые нарушения границ только в затронутой области; не начинайте несвязанный массовый рефакторинг.
• Отделяйте чистые бизнес-правила от JSX и ввода-вывода, чтобы их можно было тестировать без браузера и Supabase.
• Не создавайте service, repository, domain или другой слой только ради названия. Новый слой нужен лишь при конкретной устойчивой ответственности.
• Не добавляйте router, глобальный state manager или новую библиотеку ради одного сценария. Каждая новая зависимость требует объяснения.
• Не дублируйте запросы, бизнес-правила, типы, seed-данные и UI-паттерны.
• Не используйте any, as unknown, глобальные переменные или необоснованные non-null assertions для обхода системы типов.
• В изменяемых запросах предпочитайте явный список колонок вместо select('*').
• Операция из нескольких зависимых записей, которая должна быть атомарной, не может состоять из независимых клиентских запросов. Используйте настоящую транзакцию или безопасную Postgres RPC-функцию.
• Не проглатывайте ошибки, кроме явно best-effort аналитики. Для UI учитывайте loading, empty, error, success, disabled и возможность повторить действие.
• Сохраняйте mobile-first интерфейс, существующие CSS-переменные и компоненты. Перед добавлением стилей найдите существующий визуальный паттерн.
• Не отправляйте персональные или чувствительные данные в аналитику и логи.
• Обновляйте документацию, если меняются настройка, команды, структура или публичное поведение.

PostgreSQL и миграции

• Никогда не изменяйте, не удаляйте и не перенумеровывайте уже применённые миграции.
• Любое изменение схемы оформляйте новой forward-only миграцией с очередным свободным четырёхзначным номером. Перед merge повторно проверьте номер против актуального main; перенумеровать можно только ещё не применённый новый файл.
• Сохраняйте SQL-стиль проекта: lowercase, явное public., snake_case и осмысленные имена constraints и индексов.
• Для новой таблицы явно определите primary key, foreign keys и on delete, not null, check, unique, необходимые индексы, privileges и RLS.
• Для SELECT и DELETE используйте USING, для INSERT — WITH CHECK, для UPDATE — явно и USING, и WITH CHECK.
• Проверяйте tenant ownership самой строки и каждого переданного foreign key. Нельзя связать свою тренировку с чужими client_id или exercise_id.
• Фильтр интерфейса не является защитой. Неизменяемые инварианты должны быть закреплены constraints, foreign keys и RLS.
• Несовместимые изменения выполняйте по схеме expand → backfill → переключение приложения → contract. Для destructive change нужен план сохранения данных и forward-fix.
• Не применяйте миграции к удалённой или production-базе без отдельного явного разрешения.
• Никогда не помещайте service-role key или другие секреты во frontend и переменные VITE_*: они доступны браузеру.
• Для новой RPC по умолчанию используйте SECURITY INVOKER. SECURITY DEFINER допустим только с обоснованием, проверкой auth.uid(), безопасным search_path, полностью квалифицированными именами и минимальными grants.
• После изменения схемы обновите связанные TypeScript-типы, запросы и тесты.
• Frontend-тест с mock Supabase не проверяет миграцию, constraints или RLS.

Тесты и критерии готовности

Запускайте npm-команды только из trainer-app/:

npm test
npm run lint
npm run build

Из корня репозитория дополнительно выполните:

git diff --check
git status --short

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

Для изменённого поведения добавляйте проверки на правильном уровне:

• unit-тесты для чистых бизнес-правил;
• component/page-тесты для пользовательских сценариев;
• DB/RLS integration-тесты для схемы, прав и tenant isolation.

При изменении БД по возможности поднимите локальный Supabase, примените полную историю миграций к чистой БД, выполните DB lint/security checks и проверьте роли anon, user A и user B. Докажите разрешённые операции владельца и запрет cross-tenant SELECT/INSERT/UPDATE/DELETE, включая подмену foreign key. Отдельно проверьте constraints и cascade/restrict.

Если окружение не позволяет выполнить проверку, точно укажите, что не проверено и почему.

Безопасность репозитория

• Не удаляйте и не перезаписывайте чужие изменения.
• Не используйте destructive git-команды.
• Не меняйте lockfile без изменения зависимостей.
• Не форматируйте и не рефакторьте несвязанные файлы.
• Не создавайте commit, push или pull request без явной просьбы.
• Не выводите и не добавляйте в git содержимое .env и другие секреты.
• Не запускайте npm из директории, где нет соответствующего package.json.

Финальный отчёт

Отвечайте на русском и простыми словами. Укажите:

1. Какой пользовательский результат получен.
2. Как решение вписывается в архитектуру.
3. Какие интерфейсы и миграции изменены.
4. Какие команды действительно выполнены и каков результат.
5. Что не удалось проверить.
6. Какие риски остались и как вручную проверить результат.

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