Разработка Laravel через Claude Code — лучшие практики

Дополняет ../mcp.md (справочник MCP) и ../../LIMITS-OPTIMIZATION.md (экономия лимитов). Здесь — как эффективно вести Laravel-разработку через Claude Code (CC).

Laravel Boost — официальный MCP для AI-агентов

Laravel позиционируется как «clean stack for Artisans and agents». Boost — first-party MCP-сервер, дающий агенту структурный доступ к приложению.

docker exec {app-container} composer require laravel/boost --dev
docker exec {app-container} php artisan boost:install

Ставит MCP-сервер + кураторские AI-guidelines (видны в referendum/CLAUDE.md как <laravel-boost-guidelines>).

Инструмент Boost	Заменяет	Экономия
application-info	php artisan about	версии, пакеты компактно
database-schema	psql \d	структура таблиц/индексов
database-query	psql -c	SELECT + EXPLAIN, JSON-вывод
last-error	tail storage/logs	последняя ошибка структурно
read-log-entries	cat/grep log	фильтрованные записи
search-docs	WebFetch laravel.com	версионная дока Laravel/Filament/Livewire
get-absolute-url	—	корректные URL для тестов
browser-logs	Playwright вручную	JS-console из Telescope/Pail

Иерархия выбора MCP (дёшево → дорого)

1. laravel-boost (~1% лимита) — первый выбор для Laravel-задач
2. postgres/mysql MCP (~6%) — SQL напрямую, минуя Docker, JSON-вывод
3. docker MCP (~20%) — artisan/composer/npm/test — fallback
4. playwright (~19%) — визуально; но claude-in-chrome (~2%) предпочтительнее

Ошибка Laravel    → laravel-boost__last-error
Схема БД          → laravel-boost__database-schema
SQL-запрос        → postgres/mysql MCP
Документация      → laravel-boost__search-docs / context7
artisan/composer  → docker__docker_exec (цепочкой: cmd1 && cmd2)
Визуальная проверка → claude-in-chrome (не playwright)
Поиск по коду     → Grep/Glob (бесплатно)

Bash docker exec — только TTY/interactive. Хуки проекта блокируют неоптимальные вызовы.

Иерархия CLAUDE.md (наследование)

CC автоматически подгружает цепочку снизу вверх:

~/.claude/CLAUDE.md          глобальные правила разработчика
  → E:\Clients\CLAUDE.md      сервер, Docker, Caddy, порты
    → laravel/CLAUDE.md        Laravel-стандарт + specs/* (15 @-импортов)
      → {project}/CLAUDE.md    специфика проекта (override)

• Корневые правила и общие specs/* уже в контексте проекта — не дублировать.
• @import (specs/x.md) резолвится относительно своего файла → из проекта указывает на {project}/specs/, НЕ на корневые. Общие specs приходят через наследуемый laravel/CLAUDE.md.
• Каждый проект → блок «Наследование правил» + навигатор по docs/.
• См. детали в памяти CC: docs-inheritance-structure.

Что писать в CLAUDE.md проекта

• Имена контейнеров (app/db/redis), Laravel root путь.
• Override-правила (что отличается от laravel/CLAUDE.md).
• Навигатор: таблица «область → файл доки».
• НЕ копировать общие правила — они наследуются.

Субагенты (Task tool)

Делегировать субагенту	Делать самому (в главной сессии)
code review по чеклисту	архитектурные решения
генерация тестов	security review
рефакторинг по правилу	анализ ТЗ
grep-поиски по большой кодбазе	задачи где субагент дал неуверенный результат
документация, бойлерплейт	финальные решения

• Всегда model:sonnet для субагентов (дешевле Opus, лимит Max X5).
• Не более 4 параллельно (лимит). При остатке <20% — не более 2.
• Конкретные промпты — точная задача завершается быстрее.
• Не запускать субагент на правку одного файла / простой grep (overhead).

TDD-цикл через Claude Code

1. Написать падающий тест (Pest/PHPUnit) — docker exec {c} php artisan test --filter=X
2. Убедиться, что падает (FAIL) — реально запустить, не предполагать
3. Минимальная реализация
4. Запустить — PASS
5. Рефакторинг при зелёных тестах
6. Pint + larastan + полный прогон → коммит (по явной просьбе)

verification-before-completion: не заявлять «готово/работает», пока команда верификации не показала результат. Evidence before assertions.

Экономия контекста (длинные сессии)

• /compact после серии MCP-вызовов и после отладки.
• /clear при смене задачи/проекта.
• .claudeignore исключает vendor/, node_modules/, storage/logs/, .playwright-mcp/, *.png — экономия 5-30k токенов.
• Selective reading: читать строки offset+limit, не файл целиком на 2000 строк.
• Scratchpad для задач 30+ мин: прогресс в scratchpad.md, после /clear — «прочитай и продолжи».
• docker_container_logs всегда с tail: 20.

Модели CC под задачу

Задача	Модель
Рутина: CRUD, CSS, деплой, переименования	Sonnet (дефолт)
Архитектура, security review, сложная бизнес-логика	Opus
Массовое переименование, форматирование	Haiku (быстро, отдельный лимит)

Память CC (memory MCP / файловая)

• Начало сессии: проверить активные задачи и контекст проекта.
• Сохранять: решения с неочевидной мотивацией, конфиги (URL/пути/контейнеры), договорённости.
• НЕ сохранять: то что в коде/git, временный контекст сессии, общеизвестные паттерны.

Хуки проекта (автоматизация)

Хук	Момент	Действие
docker-mcp-guard	PreToolUse Bash	блокирует bash docker → MCP
laravel-mcp-guard	PreToolUse Bash	автоопределение контейнера
mcp-cost-optimizer	PreToolUse docker	перенаправляет docker→boost/postgres
playwright-cost-optimizer	PreToolUse playwright	→ claude-in-chrome (10x дешевле)
prompt-classifier	UserPromptSubmit	подсказывает нужный MCP по типу задачи

Anti-patterns (работа через CC)

Паттерн	Проблема	Решение
docker exec + tail log	дорого (~20%)	laravel-boost__last-error (~1%)
psql -c через docker	дорого	postgres MCP / boost database-query
Дублировать общие правила в каждом CLAUDE.md	раздувание, рассинхрон	наследование + override
Субагент на правку 1 файла	overhead	сделать напрямую
Opus для CRUD/CSS	расход лимита	Sonnet/Haiku
Одна сессия часами без /compact	растущий контекст = дороже	/compact каждые 15-20 мин
«покажи весь файл» на 2000 строк	тысячи токенов	offset+limit нужный метод
Заявить «работает» без запуска теста	ложное завершение	verification-before-completion