Стандарт студии (CLAUDE.md)

Это корневой файл правил проекта. Полная копия для справки; источник — E:\Clients\laravel\CLAUDE.md.

Laravel — Rules

Проектный CLAUDE.md в подпапке переопределяет эти правила. Спецификации: @specs/*.md — загружай при работе с конкретной областью.

⛔ КРИТИЧНО: формат вызова инструментов (высший приоритет)

НИКОГДА не печатать court, count или открывающий тег invoke вручную как тег вызова. Битый/ручной тег ломает парсер и роняет агент (Crunched).
НИКОГДА не печатать слово-заглушку (court и любое другое) как текст перед tool-use. Никаких преамбул-наполнителей («court — игнор», «делаю вызов», «Bash →»). Вызывать инструмент сразу. Повтор слова-заглушки уводит в цикл пустых ответов.
Вызывать инструменты только штатным механизмом tool-use. Обычные count в коде (count(...), .count, $count) — норма, под запрет не попадают.
Перед КАЖДЫМ тул-колом сверить, что открывающий тег корректен.

Окружение

Laravel root: project/src/ (artisan, composer.json)
Все artisan/composer — через docker exec {container}, никогда на хосте
Тесты: docker exec {container} php artisan test
Lint: docker exec {container} ./vendor/bin/pint

MCP-конфигурация проектов

Проект	Контейнер app	postgres/mysql	Конфиг `.mcp.json`
`notal`	`notal-app`	`localhost:5435/notal`	корень
`catalog`	`catalog_api`	`localhost:5432/catalog` (+staging `5433`)	корень
`gulaev-dev`	`gulaev-app`	mysql `localhost:2237/gulaev`	корень
`referendum`	`referendum`	`localhost:5441/referendum`	корень
`masha`	`masha-app`	`localhost:54016/masha`	корень
`school`	`school-app`	`localhost:5436/school`	корень
`er` (massage)	`massage`	`localhost:5436/relaxmap`	`er/project/`
`universal`	`universal-app`	`localhost:5471/universal`	`universal/src/`
`freelance`	`freelance-app`	`localhost:5461/freelance`	`freelance/project/`

Актуальная проверка состояния: powershell E:\Clients\Claude\mcp\setup.ps1 -Diagnose (ищет .mcp.json по всему E:\Clients\laravel, валидирует пути и флаги boost).

Заведение MCP в новый проект (обязательная процедура)

Проблема, которую решает процедура: MCP «не работает каждый раз» по 4 первопричинам — все проверяются диагностикой. Полный разбор и troubleshooting → MCP-SETUP.md.

bash

cd E:\Clients\Claude\mcp
# 1) сгенерировать .mcp.json автодетектом (контейнеры + БД из compose/.env).
#    Кладётся рядом с docker-compose.yml. НОВЫЕ проекты — без -Force.
powershell .\setup.ps1 -ScanLaravel E:\Clients\laravel

Затем в контейнере проекта:

bash

docker exec {app} git config --global --add safe.directory /var/www/html
docker exec {app} composer require laravel/boost --dev --no-interaction

4 первопричины «MCP мёртв» — проверить ВСЕ:

boost не установлен — самый частый случай. laravel/boost отсутствует в composer.json нового проекта. Без него mcp:start laravel-boost / boost:mcp = «no commands in namespace». Блокеры установки: нет ext-exif в образе (нужен medialibrary) → добавить в Dockerfile + пересобрать; конфликт symfony/* под PHP 8.4 при PHP 8.3 → пинить версии.
boost в dont-discover — если в composer.json есть extra.laravel.dont-discover: ["laravel/boost"], провайдер не грузится. Убрать → composer dump-autoload --no-scripts + php artisan package:discover.
Проект не активирован в ~/.claude.json — даже идеальный .mcp.json не грузится, пока в секции проекта нет "hasTrustDialogAccepted": true + "enableAllProjectMcpServers": true. Проверить: powershell .\setup.ps1 -Diagnose. После правки — перезапуск Claude Code.
Битый .mcp.json — голый php/npx/docker/cmd (Windows не резолвит PATH процесса CC → только абсолютные пути docker.exe/node.exe); нет -e APP_ENV=local -e APP_DEBUG=true (boost гейтит логику на local||debug); неверный внешний порт БД. Всё это ловит -Diagnose.

Проверка живости boost без перезапуска сессии (JSON-RPC initialize):

bash

printf '%s\n' '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"t","version":"1"}}}' \
  | docker exec -i -e APP_ENV=local -e APP_DEBUG=true {app} php artisan boost:mcp
# → должен вернуться JSON с "serverInfo":{"name":"Laravel Boost",...}

⛔ НЕ гонять setup.ps1 -ScanLaravel -Force на всей папке — перезапишет рабочие конфиги, потеряв ручные добавки (playwright, staging-БД, кастомные порты). -Force — только точечно после ручного бэкапа, либо чинить конкретный конфиг руками по образцу.

MCP — приоритет выбора (от дешёвого к дорогому)

laravel-boost (1% лимита) → логи, схема БД, app-info, документация
postgres/mysql MCP (6%) → SQL-запросы напрямую, без Docker
docker MCP (20%) → artisan, composer, npm — только когда boost/postgres не покрывают

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

Архитектура

Controller → Service → Model

Controller: FormRequest → Service → view/json. Макс 10 строк логики
Service (app/Services/): бизнес-логика, DI через конструктор, не знает про Request/Response
Model: $casts, связи, scopes. Не вызывает сервисы

Обязательные правила

Eloquent

$casts на КАЖДЫЙ JSON/date/bool/enum столбец
Обе стороны связей: hasMany ↔ belongsTo
Route model binding по slug (публичные), id (admin)
->with() явно, $with в модели запрещён, Model::all() запрещён

Безопасность

всегда, {!! !!} — только доверенный HTML из админки
Валидация — FormRequest, не контроллер
SQL — Eloquent/bindings, raw concat запрещён
Секреты — .env → config(), никогда env() в коде

БД

FK: constrained() + index(), JSON: json()->nullable() + cast 'array'
Enum: $table->enum() + PHP Enum class, индексы на WHERE/ORDER BY столбцы

Кеш

Redis cache tags, Filament afterSave() → Cache::tags()->flush()

Тесты — защита рабочей БД

phpunit.xml ОБЯЗАН: <env name="DB_DATABASE" value="{project}_test"/>
RefreshDatabase только на _test БД. Совпадение с рабочей → СТОП
Тестовая БД = те же extensions (PostGIS, etc.)

Anti-hardcode

Магическое число/строка 2+ раз или с бизнес-смыслом → выноси:

Пороги/лимиты → config/*.php
Статусы/типы/роли → App\Enums\*
Текст UI → lang/*/*.php через __()
Регексы/ключи кеша → app/Support/Constants/
URL в Blade → только route('name'), даты → translatedFormat()

Качество кода

declare(strict_types=1) везде, типизация параметров и return
SRP: 300+ строк → разбивай. DI: constructor injection, не app()
N+1 — баг: ->with() / ->withCount() обязательны
throw_if() / throw_unless(), не вложенные if
Domain exceptions, не catch (\Exception $e) { return null; }

DO NOT

dd()/dump()/var_dump() в коммитах
DB::raw() с конкатенацией, env() вне config, $fillable = ['*']
Бизнес-логика в контроллерах/моделях/middleware/Blade
RefreshDatabase на рабочей БД, Model::first() без orderBy()
ID в публичных URL — UUID или хеш
bash psql/docker exec когда есть MCP

Checklist перед коммитом

Нет dd(), dump(), console.log, закомментированного кода
Новые строки UI через __(), числа/статусы в config/Enum/Constants
Новый роут → ->name() + тест, новая модель → $casts + relations + factory
Новая миграция → down(), FK constrained() + index()
Новая форма → FormRequest, изменён URL → 301 redirect
Filament → afterSave + Cache::tags()->flush()
Pint + тесты зелёные, нет секретов в diff

Спецификации

Область	Файл
Модели, traits, scopes	`specs/models.md`
Контроллеры, роутинг	`specs/controllers.md`
Filament: ресурсы, формы	`specs/filament.md`
Миграции, сидеры, индексы	`specs/migrations.md`
Blade: layouts, компоненты	`specs/blade.md`
SEO: мета, Schema.org	`specs/seo.md`
Docker: сервисы, окружение	`specs/docker.md`
Тесты: feature, unit	`specs/testing.md`
Services, Jobs	`specs/services.md`
MCP: справочник, приоритеты	`specs/mcp.md`
Anti-hardcode: константы	`specs/anti-hardcode.md`
Качество кода: SOLID, типы	`specs/code-quality.md`
Экономия лимитов	`LIMITS-OPTIMIZATION.md`
Лучшие практики Laravel + CC (справочник, по требованию)	specs/best/README.md
Каталог OSS-решений: CMS, e-commerce, биржи, пакеты (по требованию)	opensource/README.md
Blueprints типовых модулей (leads, pages, settings, reviews, blog, catalog, multicity)	blueprints/README.md
Быстрая разработка на Laravel (справочник)	docs-site/docs/guide/fast-development.md
Фронтенд: подход студии + React-острова vs Inertia	docs-site/docs/frontend/

Правило blueprints: перед реализацией типовой фичи (заявки, страницы, настройки, отзывы, блог, каталог, мультигород) — открыть соответствующий blueprints/*.md и следовать ему: схема данных, правила, шаги, чеклист приёмки.

База знаний онлайн: все MD-файлы (specs, best, opensource, guide) собраны в VitePress-сайт laravel.rosveb.ru. Исходники правятся как обычно; пересборка — cd docs-site && npm run build (обновить сайт: npm run publish).

Стандарт студии (CLAUDE.md) ​

Laravel — Rules ​

⛔ КРИТИЧНО: формат вызова инструментов (высший приоритет) ​

Окружение ​

MCP-конфигурация проектов ​

Заведение MCP в новый проект (обязательная процедура) ​

MCP — приоритет выбора (от дешёвого к дорогому) ​

Архитектура ​

Обязательные правила ​

Eloquent ​

Безопасность ​

БД ​

Кеш ​

Тесты — защита рабочей БД ​

Anti-hardcode ​

Качество кода ​

DO NOT ​

Checklist перед коммитом ​

Спецификации ​

Стандарт студии (CLAUDE.md)

Laravel — Rules

⛔ КРИТИЧНО: формат вызова инструментов (высший приоритет)

Окружение

MCP-конфигурация проектов

Заведение MCP в новый проект (обязательная процедура)

MCP — приоритет выбора (от дешёвого к дорогому)

Архитектура

Обязательные правила

Eloquent

Безопасность

БД

Кеш

Тесты — защита рабочей БД

Anti-hardcode

Качество кода

DO NOT

Checklist перед коммитом

Спецификации