# Правила взаимодействия с Агентом

## Основные принципы

1. **Изменения в коде возможны только с явного разрешения пользователя**
    - Перед внесением любых изменений в файлы ассистент должен получить подтверждение от пользователя
    - Все изменения должны быть предварительно объяснены пользователю
    - Перед решением конкретной задачи всегда составлять план
    - После внесения изменений в код - проводить проверку - только после этого приступать к дальнейшему решению задачи
    - **НЕ производить сборку проекта (`bun run build`) без явного разрешения пользователя**

2. **Прозрачность действий**
    - Ассистент должен объяснить, какие изменения планируется внести
    - Необходимо указать, в какие файлы будут внесены изменения
    - Следует объяснить последствия предполагаемых изменений
    - Внимательно читай промпт и не выходи за рамки описанных в нем измнений 

3. **Безопасность кода**
    - Все изменения должны проходить проверку на безопасность
    - Не должны вноситься изменения, которые могут повредить функциональность приложения
    - Рекомендуется создание резервных копий при значительных изменениях

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

5. **Работа с разными типами проектов**
    - Уважать существующую архитектуру и стиль кода проекта
    - Следовать установленным в проекте принципам и паттернам

6. **Использование Bun**
    - Все команды должны выполняться с использованием Bun (bun install, bun dev, bun build и т.д.)
    - При создании скриптов в package.json, они должны быть совместимы с Bun

7. **Язык общения**
    - Всё общение с пользователем происходит на русском языке

8  **Проверка типов данных**
    - Проверять проект на ошибки типизации через команду `bun run tsc --noEmit -p frontend/tsconfig.json`
    - НЕ производить сборку проекта (`bun run build`) без явного разрешения пользователя
    - В проекте не должно быть типов any
    - Все интерфейсы компонентов прописывать в файле globalInterfaces.ts
    - При работе с PocketBase использовать актуальные сигнатуры методов из файла `D:\Verstka\production\astro_minivan\frontend\node_modules\pocketbase\dist\pocketbase.es.d.ts`

9  **Плагин  @astrojs/sitemap**
    - Обязательно к установке в проект пакета @astrojs/sitemap
    - Обязательно к созданию в проекте файл .nvmrc


## Технические правила (Astro)

1. **Structure проекта**
   - Использовать рекомендуемую структуру Astro: src/components/, src/layouts/, src/pages/, src/styles/
   - Файлы конфигурации: astro.config.mjs

2. **Разработка компонентов**
   - Создавать .astro файлы для компонентов
   - Использовать framework-specific компоненты (React, Vue, Svelte) при необходимости
   - Использовать props для передачи данных
   - Использовать встроенные компоненты Astro (<Markdown /> и т.д.)

3. **Роутинг и страницы**
   - Использовать file-based routing в src/pages/
   - Реализовывать динамические маршруты через [...slug].astro синтаксис
   - Использовать getStaticPaths() для генерации статических страниц
   - Создать страницу 404.astro для обработки ошибок

4. **Контент**
   - Использовать Markdown (.md) или MDX (.mdx) для контентных страниц
   - Использовать frontmatter в Markdown файлах
   - Использовать content collections для организации контента

5. **Стилизация**
   - Использовать scoped styling с <style> тегами в .astro файлах
   - Использовать Tailwind CSS с интеграцией @astrojs/tailwind
   - Использовать Tailwind утилитарные классы
   - Использовать responsive дизайн (sm:, md:, lg: и т.д.)
   - НИКОГДА не использовать директиву @apply

6. **Оптимизация производительности**
   - Минимизировать client-side JavaScript
   - Использовать client:* директивы для partial hydration:
     - client:load для immediately needed interactivity
     - client:idle для non-critical interactivity
     - client:visible для components that should hydrate when visible
   - Использовать lazy loading для изображений
   - Использовать Astro Image component

7. **Data Fetching**
   - Использовать Astro.props для передачи данных
   - Использовать getStaticPaths() для fetching данных на этапе сборки
   - Использовать Astro.glob() для работы с локальными файлами

8. **SEO и Meta теги**
   - Использовать <head> тег для добавления meta информации
   - Реализовать canonical URLs
   - Использовать <SEO> компонент для reusable SEO

9. **Accessibility**
   - Использовать семантический HTML
   - Использовать ARIA атрибуты где необходимо
   - Обеспечить keyboard navigation поддержку

10. **Тестирование**
    - Реализовать unit тесты для utility функций
    - Использовать end-to-end тестирование (Cypress)
    - Реализовать visual regression тестирование если применимо

11. **Метрики производительности**
    - Приоритизировать Core Web Vitals (LCP, FID, CLS)
    - Использовать Lighthouse и WebPageTest для аудита производительности
    - Реализовать performance budgets

## SEO рекомендации

### Оптимальное количество страниц
- **50-100 страниц** — хороший объём для тематики "автоюрист"
- Минимум 30-50 страниц с уникальным контентом

### Структура страниц
- Услуги (12 шт) — уже есть
- Кейсы — минимум 20-30 реальных примеров
- Блог — минимум 30-50 статей
- FAQ — 20-30 вопросов
- Городские страницы ("юрист в Сургуте", "возврат прав Сургут" и пр.)

### Требования к контенту
- Каждая страница с уникальным текстом (не шаблон)
- Длинные статьи в блог (3000-5000 слов)
- Реальные кейсы с описанием проблемы и решения

### Внутренние ссылки
- Связывать страницы между собой (услуги → кейсы → блог)
- Использовать sitemap для всех публичных страниц


## Ccылки на документацию
- URL документации Astro: https://docs.astro.build/en/getting-started/
- URL документации PocketBase: https://pocketbase.io/docs/
- URL документации SolidJS: https://docs.solidjs.com/solid-start/getting-started
- URL документации astro-icons: https://www.astroicon.dev/getting-started/


## Переменные окружения для Production (Coolify)

### PocketBase
```
PB_POCKETBASE_URL=https://avt-back.ru
PB_ADMIN_EMAIL=redibedi2019@gmail.com
PB_ADMIN_PASSWORD=Stalin4444
```
PB_POCKETBASE_URL=https://avt-back.ru
PB_ADMIN_EMAIL=redibedi2019@gmail.com
PB_ADMIN_PASSWORD=Stalin4444
```

### SMTP (Resend)
```
SMTP_HOST=smtp.resend.com
SMTP_PORT=465
SMTP_AUTH_USER=resend
SMTP_AUTH_PASS=re_bAXEq3JU_3ezUi6XvBci7Biz48eAavW4M
FROM_EMAIL=onboarding@resend.onlinemail.me
FROM_NAME=Автоюрист Сургут
```

### Site
```
SITE_URL=https://avtourist-surgut.ru
```

### Флаг production
```
PROD=true
```

### Как добавить в Coolify

1. Откройте Coolify → ваш проект
2. Перейдите App Settings → Environment Variables
3. Добавьте каждую переменную
4. Перезапустите контейнер


### SKILLS FOR AI
1. C:\Users\Serg\.config\opencode\skills - общие скилы для всех проектов
2. project/.opencode/skills/avtourist - скилы для конкретного проекта
3. answer-unit-optimization - скилы для AI SEO