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

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

---

Laravel — Rules

Эти правила — глобальные для всех Laravel-проектов студии. Частная специфика (контейнеры, порты, БД, стек, домены) живёт в CLAUDE.md конкретного проекта и переопределяет этот файл. Здесь конкретных проектов нет — только стандарт. Вся документация студии живёт в docs-site/docs/ (specs, best, blueprints, opensource, guide, frontend, optimization, cms-v2). Спеки лежат в двух уровнях внутри specs/: — базовый specs/*.md — универсальные, версионно-независимые правила (архитектура Controller→Service→Model, anti-hardcode, качество, безопасность); — версионированный specs/laravel_{11,12,13}/*.md — контент, различающийся по мажору Laravel; при расхождении версионная спека главнее базовой. Роутер выбора версии: docs-site/docs/specs/README.md. Совместимость мажоров Laravel с Filament/Livewire/Tailwind/React/Vite: docs-site/docs/specs/versions-matrix.md.

⚠️ Выбор версии спеки (обязательно перед работой).

1. Определи мажор Laravel проекта: CLAUDE.md проекта → реестр docs-site/docs/list.md (constraint из composer.json + факт из composer.lock) → сам: composer.json → laravel/framework (Grep) → laravel-boost__application-info.
2. Открывай спеки из docs-site/docs/specs/laravel_<мажор>/.
3. Мажор не 11/12/13 — бери ближайшую младшую подпапку и сверяйся с laravel.com/docs/<мажор>.x (boost/context7).
4. Новый проект → laravel_13/ (L12 теряет багфиксы 13.08.2026 — стартовать на нём анти-паттерн; см. specs/README.md и versions-matrix.md). Полный алгоритм и карта парка — в docs-site/docs/specs/README.md. Файлы specs/laravel_{11,12}/_L{11,12}-VALIDATION.md фиксируют сверку спек с официальными доками соответствующей версии.

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

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

Параллельная разработка субагентами (стандарт студии, 14.07.2026)

На объёмных задачах (волна ТЗ, модуль, пачка тестов) не писать всё последовательно одним контекстом — разбивать на независимые куски и запускать до 5 параллельных Sonnet-субагентов (Agent tool, model: sonnet), каждый пишет свои файлы.

Правила разбиения (иначе параллельность приносит конфликты, а не скорость):

• Общие файлы — только у основного агента: провайдеры, роуты, конфиги, lang, composer.json, миграции с пересекающимися таблицами. Субагентам — только непересекающиеся новые файлы или точечные правки «ровно этих файлов».
• Каждому субагенту в промпт: путь проекта, ссылка на CLAUDE.md проекта, точный контракт (роуты, имена классов, форматы ответов), список файлов «создай ровно эти», запрет трогать остальное.
• Тесты субагенты не запускают (параллельный Pest бьёт по одной cms_test — RefreshDatabase дерётся); только php -l. Полный гейт — основной агент после сборки всех результатов.
• Субагентам запрещён artisan tinker с записью (фабрики, create, update): tinker работает по .env = рабочая БД, не тестовая. Инцидент 14.07.2026 — фабричные страницы утекли в рабочую cms полигона. Проверять гипотезы о поведении кода — чтением кода, не исполнением с записью.
• Основной агент после завершения: свести, прогнать гейт (Pest + phpstan + pint), починить стыки, закоммитить.

Окружение

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

Проектный CLAUDE.md (обязателен в каждом проекте)

Вся специфика проекта — в его CLAUDE.md рядом с docker-compose.yml. Минимум:

• шапка наследования: ~/.claude/CLAUDE.md → CLAUDE.md (сервер) → laravel/CLAUDE.md → этот файл;
• что это за проект (1–2 строки);
• окружение: Laravel root, имя app-контейнера, БД (тип, база, внешний порт), вспомогательные контейнеры (queue, scheduler, reverb, …);
• где .mcp.json и какие в нём серверы;
• мажор Laravel → какая подпапка спек (laravel_11/12/13).

Реестр проектов и версий — docs-site/docs/list.md; реестр портов и статус переноса на этот сервер — Server/MIGRATION.md. Новый порт — только после сверки с реестром и записью туда же.

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

.mcp.json кладётся рядом с docker-compose.yml: скопировать из соседнего проекта с тем же типом БД, поправить имя контейнера и внешний порт БД. (Windows-генератор setup.ps1 на Ubuntu не перенесён — конфиги правятся руками.)

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

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

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

1. 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 → пинить версии.
2. boost в dont-discover — если в composer.json есть extra.laravel.dont-discover: ["laravel/boost"], провайдер не грузится. Убрать → composer dump-autoload --no-scripts + php artisan package:discover.
3. Проект не активирован в ~/.claude.json — даже идеальный .mcp.json не грузится, пока в секции проекта нет "hasTrustDialogAccepted": true + "enableAllProjectMcpServers": true. Проверить секцию проекта в ~/.claude.json вручную. После правки — перезапуск Claude Code.
4. Битый .mcp.json — нет -e APP_ENV=local -e APP_DEBUG=true (boost гейтит логику на local||debug); неверный внешний порт БД; невалидный JSON. (Пункт про абсолютные пути docker.exe/node.exe был актуален на Windows — на Ubuntu команды docker/node в PATH.)

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

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",...}
# (в части проектов команда называется `mcp:start laravel-boost` — см. .mcp.json проекта)

⛔ НЕ перегенерировать .mcp.json массово — перезапишешь рабочие конфиги, потеряв ручные добавки (playwright, chrome-devtools, кастомные порты). Чинить конкретный конфиг руками по образцу соседнего проекта, перед правкой — бэкап.

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

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

Bash docker exec — только TTY/interactive. Хуки блокируют неоптимальные вызовы автоматически. Подробный разбор экономии лимитов: docs-site/docs/optimization/limits.md.

Архитектура

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; }

Пакетный стек студии

Обязательно в каждом проекте:

• laravel/pint (require-dev) — форматирование; pint --dirty перед коммитом.
• Model::preventLazyLoading(!app()->isProduction()) в AppServiceProvider::boot() — каждый ленивый запрос в dev падает с исключением. N+1 ловится при разработке, не в проде.
• Кеши прода при деплое: config:cache, route:cache, view:cache, event:cache (или optimize). ⚠️ Проекты на пакетных fluent-роутах — см. оговорку про refreshNameLookups в best/performance.md.
• spatie/laravel-backup — если бэкапы БД/файлов не делаются на уровне сервера. Проверить и зафиксировать, где именно, — «нигде» не вариант.

По типу проекта (ставить при потребности, не «на всякий случай»):

• spatie/laravel-query-builder — публичный API с фильтрами/сортировками из query-string (whitelist вместо ручного разбора $request->query()).
• spatie/laravel-data — сложный домен: типизированные DTO вместо голых массивов между слоями. На простых сайтах-визитках не нужен.
• spatie/laravel-activitylog — есть админы и требование аудита «кто что менял».
• spatie/laravel-sluggable, spatie/laravel-settings — по blueprints (blueprints/blog.md, blueprints/settings.md).

Dev-наблюдаемость:

• barryvdh/laravel-debugbar (require-dev) — стандарт профилирования запроса в dev. Ставить при первом подъёме проекта для работы, дальше он сам гейтится по APP_DEBUG (страховка в prod .env: DEBUGBAR_ENABLED=false).
• Telescope — не стандарт, ставить точечно и только в проекты с очередями/событиями/почтой: его уникальная ценность — история джобов/событий/mail между запросами, остальное дублируют Debugbar и boost MCP. Обязательно вместе с установкой: telescope:prune --hours=48 в scheduler (иначе telescope_entries раздувается) и регистрация провайдера только в local + Gate — иначе дыра в проде.
• Pulse — на проекты с реальной prod-нагрузкой.

Подробности и команды — guide/tooling.md.

Rector — не в require-dev каждого проекта, а пакетный инструмент при апгрейдах мажора Laravel/PHP: поставил, прогнал --dry-run, применил, убрал.

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 перед коммитом

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

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

Пути ниже — относительно docs-site/docs/. Для проекта известного мажора бери версию: <ver> = laravel_11 | laravel_12 | laravel_13 (см. правило выбора в шапке и list.md). Если версия неясна — тот же файл без <ver>/ (specs/models.md и т.д.) как дефолт ≈ L12.

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

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

Где лежат исходники. Единственный источник документации — docs-site/docs/ (VitePress-сайт laravel.rosveb.ru). Отдельной папки laravel/specs/ больше нет — спеки переехали в docs-site/docs/specs/laravel_XX/. Правь .md в docs-site/docs/ как обычно. ⚠️ pnpm run build (через scripts/sync-docs.mjs) перезаписывает docs/standard.md из этого CLAUDE.md — правила студии править только здесь. Пересборка: cd docs-site && pnpm run build. Публикация: pnpm run publish-site пока не адаптирован под Ubuntu (scripts/publish.mjs указывает на старый путь ../../Windows/proxy; актуальный прокси — projects/servers/proxy-nix) — выкладка вручную: скопировать docs/.vitepress/dist/ в servers/proxy-nix/sites-static/laravel/ (Caddy уже раздаёт laravel.rosveb.ru из этой папки). Мёртвые внутренние ссылки валят сборку; новые страницы добавлять в sidebar docs/.vitepress/config.mjs.

CMS v2 (своё ядро). Проектирование универсальной блочной CMS студии — docs-site/docs/cms-v2/: видение и решения, спеки контрактов фазы 0, стандарт модуля + ТЗ ядра и всех ~115 модулей (cms-v2/modules/), порядок разработки. Точка входа: cms-v2/README.md (раздел «Порядок чтения»).