188 lines
10 KiB
Markdown
188 lines
10 KiB
Markdown
|
# Правила взаимодействия с Агентом
|
|||
|
|
|
|||
|
|
## Основные принципы
|
|||
|
|
|
|||
|
|
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
|