Как использовать Laravel Boost и Cursor IDE

Современная разработка на Laravel всё чаще включает использование AI-ассистентов для ускорения workflow. Два ключевых инструмента в этом процессе — Cursor IDE с его мощной AI-интеграцией и Laravel Boost — официальный пакет от Laravel для предоставления AI контекста вашего приложения. В этом руководстве я подробно разберу, как правильно настроить их совместную работу, особенно если ваш проект запущен в Docker-окружении, с учетом последних обновлений и лучших практик.

Установка и базовая настройка Laravel Boost

Первым шагом необходимо установить Laravel Boost в ваш проект:

composer require laravel/boost --dev
php artisan boost:install

Во время установки обязательно выберите Cursor как ваш основной редактор. Это автоматически создаст или обновит файл ~/.cursor/mcp.json, который отвечает за интеграцию между Cursor и Boost.

Важное обновление: Начиная с версии v1.1.4, Laravel Boost включает исправления для стабильной работы под Windows и улучшенную обработку изменений в .env файлах.

Критически важная настройка для Docker-окружений

Если ваш Laravel проект запущен в Docker-контейнере (что является стандартной практикой), стандартная конфигурация не будет работать. Cursor, запущенный на хостовой машине, не сможет напрямую выполнить команду php artisan boost:mcp, так как она должна выполняться внутри контейнера.

Решение: Настройка MCP через Docker Exec

Замените содержимое вашего ~/.cursor/mcp.json на следующую конфигурацию:

{
  "mcpServers": {
    "laravel-boost": {
      "command": "docker",
      "args": [
        "exec",
        "-i",
        "your_container_name",
        "php",
        "artisan",
        "boost:mcp"
      ]
    }
  }
}

Где your_container_name — имя вашего основного PHP-контейнера (например, talasus_app из docker-compose).

Альтернатива: Использование Docker Compose

Если вы используете docker-compose, более предпочтительной будет следующая конфигурация:

{
  "mcpServers": {
    "laravel-boost": {
      "command": "docker-compose",
      "args": [
        "exec",
        "-T",
        "app",
        "php",
        "artisan",
        "boost:mcp"
      ],
      "cwd": "/absolute/path/to/your/project"
    }
  }
}

Ключевые моменты:

Флаг -T отключает псевдо-TTY, что критически важно для работы MCP
Параметр cwd должен содержать абсолютный путь к вашему проекту на хостовой машине
app — имя сервиса в вашем docker-compose.yml

Работа с Boost AI Guidelines: переопределение и кастомные правила

Как работает система правил

Важное уточнение: По умолчанию Laravel Boost автоматически сканирует и использует правила из .cursor/rules/*.mdc. Однако вы можете переопределять встроенные guidelines Boost, создавая собственные файлы с соответствующими путями в директории .ai/guidelines/.

Переопределение встроенных guidelines

Чтобы переопределить встроенные guidelines Boost, создайте собственные файлы с соответствующими путями:

# Пример переопределения guidelines для Inertia React v2 Forms
mkdir -p .ai/guidelines/inertia-react/2
touch .ai/guidelines/inertia-react/2/forms.blade.php

Синтаксис для Boost AI Guidelines

Файлы в .ai/guidelines/ используют специальный синтаксис на основе Blade:

{{-- .ai/guidelines/inertia-react/2/forms.blade.php --}}
{{--
@title Custom Form Guidelines for Inertia React v2
@description Our custom form handling approach for Inertia React
--}}

@component('guideline')
## Кастомные правила для форм в Inertia React v2

### Общие принципы
- Все формы должны использовать useForm хуки из @inertiajs/react
- Валидация происходит на сервере, используйте Laravel Form Requests
- Для обработки ошибок используйте наш кастомный hook `useToast`

### Пример реализации
```jsx
import { useForm } from '@inertiajs/react'
import useToast from '@/Hooks/useToast'

export default function CreateForm() {
  const { toast } = useToast()
  
  const { data, setData, post, processing, errors } = useForm({
    title: '',
    content: ''
  })

  const submit = (e) => {
    e.preventDefault()
    post(route('posts.store'), {
      onSuccess: () => toast.success('Post created!'),
      onError: () => toast.error('Validation failed')
    })
  }

  return (
    <form onSubmit={submit}>
      {/* ... */}
    </form>
  )
}

Особенности нашего проекта

Все формы должны быть обернуты в компонент FormContainer
Используйте кастомные инпуты из @/Components/Forms
Состояния загрузки должны показывать наш лоадер Spinner
@endcomponent


### Структура кастомных guidelines

```bash
.ai/
└── guidelines/
    ├── inertia-react/
    │   └── 2/
    │       ├── forms.blade.php
    │       └── authentication.blade.php
    ├── laravel/
    │   └── 11/
    │       ├── validation.blade.php
    │       └── api-responses.blade.php
    └── project-specific/
        ├── business-rules.blade.php
        └── database-schema.blade.php

Детальное разделение правил: философия и практика

Что должно находиться в .ai/guidelines/ (для Boost)

Проектно-специфичные данные и кастомные правила:

Tech Stack & Dependencies (tech-stack.blade.php)

{{--
@title Project Technology Stack
@description Versions and important dependencies
--}}

@component('guideline')
## Технологический стек проекта

### Версии
- Laravel: 11.44.0
- PHP: 8.3.12  
- Livewire: 3.4.11
- Filament: 4.24.1

### Важные зависимости
- `spatie/laravel-permission` - для RBAC
- `predis/predis` - для Redis-драйвера
- `guzzlehttp/guzzle` - для работы с API провайдера X

### Конфигурационные особенности
- Время жизни кэша: 3600 секунд
- Дефолтная локаль: ru_RU
- Используется база данных PostgreSQL 16
@endcomponent

Business Logic & Domain Terms (business-rules.blade.php)

{{--
@title Business Rules and Domain Terms
@description Key business logic and terminology
--}}

@component('guideline')
## Бизнес-логика и терминология

### Ключевые доменные термины
- **Товар (Product)**: Основная сущность каталога, имеет SKU
- **Заказ (Order)**: Совокупность товаров от одного клиента  
- **CRM-лид (Lead)**: Потенциальный клиент из входящих заявок

### Бизнес-правила
- Цена товара: базовая_цена * коэффициент_наценки
- Статусы заказа: pending, processing, shipped, delivered, cancelled
- Лид считается горячим если создан менее 24 часов назад
@endcomponent

Что должно остаться в .cursor/rules/ (для Cursor)

Общие принципы разработки и стиля:

Code Style & Architecture (php-development.mdc)

# Стандарты PHP-разработки

## Стиль кода
- Следуем PSR-12 без исключений
- Используем strict types declaration
- Все классы - final если не предполагается наследование
- Типизированные свойства везде где возможно

## Архитектурные паттерны
- Контроллеры только для маршрутинга, логика - в сервисы
- Используем Form Request для валидации
- Data Transfer Objects для сложных данных
- Repository pattern для доступа к данным

Framework-Specific Rules (laravel-specific.mdc)

# Laravel-специфичные правила

## Работа с БД
- Используем Eloquent, но избегаем N+1 проблем
- Чанкование для больших datasets
- Явное указание полей в select()

## Кэширование  
- Кэшируем тяжёлые запросы на 1 час
- Тегируем кэш для возможности сброса
- Используем `remember()` для удобства

Практические примеры организации

Процесс миграции и рефакторинга правил

Аудит существующих правил

# Анализ текущей структуры правил
find .cursor/rules -name "*.mdc" -exec echo "Файл: {} | Строк: $(wc -l < {})" \;

Постепенная миграция правил

Начинайте с самых контекстно-зависимых правил
Переносите по одному файлу за итерацию
Тестируйте работу AI после каждого изменения

Скрипт для анализа правил

// analyze-rules.php
<?php

$rulesDirectory = __DIR__ . '/.cursor/rules';
$boostCandidates = [];

foreach (glob("$rulesDirectory/*.mdc") as $file) {
    $content = file_get_contents($file);
    
    // Поиск проектно-специфичной информации
    if (preg_match_all('/\b(project|business|domain|database|schema)\b/i', $content, $matches)) {
        $boostCandidates[basename($file)] = [
            'path' => $file,
            'matches' => array_count_values($matches[0]),
            'content_sample' => substr($content, 0, 200) . '...'
        ];
    }
}

file_put_contents('boost-migration-plan.json', 
    json_encode($boostCandidates, JSON_PRETTY_PRINT | JSON_UNESCAPED_UNICODE));

Проверка эффективности разделения

Признаки правильной настройки

AI перестаёт задавать уточняющие вопросы о версиях пакетов и структуре проекта
Код-генерация становится более точной и релевантной контексту проекта
Уменьшается количество итераций на одну задачу
AI начинает предлагать решения, учитывающие бизнес-контекст и доменные правила

Метрики для отслеживания

Время на выполнение типовых задач (до/после реорганизации правил)
Количество промптов для решения средней задачи
Качество сгенерированного кода (процент принятия без правок)
Скорость адаптации новых разработчиков с помощью AI-ассистента

Заключение

Правильная настройка Laravel Boost и Cursor IDE — это не просто техническое упражнение, а стратегическое инвестирование в эффективность вашей разработки. Ключевые принципы:

Используйте Docker-конфигурацию для MCP-сервера при работе с контейнерами
Разделяйте ответственность: контекст — Boost’у, стиль — Cursor’у
Переопределяйте встроенные guidelines через .ai/guidelines/ для кастомных правил
Используйте Blade-синтаксис для создания сложных guidelines с примерами кода
Постепенно мигрируйте правила, отслеживая эффективность изменений

Помните: Laravel Boost обеспечивает контекстную осведомленность, а Cursor обеспечивает стилистическое единообразие. Правильно настроенная система будет годами приносить дивиденды в виде скорости разработки и качества кода.

Ключевой вывод: Не пытайтесь заставить Cursor знать всё о вашем проекте. Доверьте контекст Boost’у, а стиль — Cursor’у. Это разделение ответственности — залог успешной AI-ассистированной разработки в современных Laravel-проектах.

Полное руководство по настройке Laravel Boost и Cursor IDE для эффективной разработки