Laravel 11/12 App Guidelines

Overview

Apply a consistent workflow for Laravel 11/12 apps with optional frontend stacks, Dockerized commands, and Laravel Boost tooling.

Quick Start

• Read repository instructions first:

  AGENTS.md

  . If

  docs/

  exists, read

  docs/README.md

  and relevant module docs before decisions.
• Detect the stack and command locations; do not guess.
• Use Laravel Boost

  search-docs

  for Laravel ecosystem guidance; use Context7 only if Boost docs are unavailable.
• Follow repo conventions for naming, UI language, docs-first policies, and existing component patterns.

Stack Detection

• Check

  composer.json

  ,

  package.json

  ,

  docker-compose.*

  , and

  config/*

  to confirm:
  • Docker Compose/Sail vs host commands
  • API-only vs full-stack
  • Frontend framework (Inertia/React, Livewire, Vue, Blade)
  • Auth (Fortify, Sanctum, Passport, custom)

Laravel 11/12 Core Conventions

• Use the Laravel 11/12 structure: configure middleware, exceptions, and routes in

  bootstrap/app.php

  ; service providers in

  bootstrap/providers.php

  ; console configuration in

  routes/console.php

  .
• Use Eloquent models and relationships first; avoid raw queries and

  DB::

  unless truly necessary.
• Create Form Request classes for validation instead of inline validation.
• Prefer named routes and

  route()

  for URL generation.
• When altering columns, include all existing attributes in the migration to avoid dropping them.
• Ask before destructive database operations (e.g., reset/rollback/fresh).

API-Only Mode

• Use

  routes/api.php

  ; avoid Inertia and frontend assumptions.
• Prefer API Resources and versioning if the repo already uses them.
• Follow the repo's auth stack (Sanctum/Passport/custom) and response format conventions.
• Do not require Vite/Tailwind/NPM unless the repo already includes them.

Inertia + React + Wayfinder (if present)

• Use

  Inertia::render()

  for server-side routing; place pages under

  resources/js/Pages

  unless the repo says otherwise.
• Use

  <Form>

  or

  useForm

  for Inertia forms; add skeleton/empty states for deferred props.
• Use

  <Link>

  or

  router.visit()

  for navigation.
• Use Wayfinder named imports for tree-shaking; avoid default imports; regenerate routes after changes if required.

Livewire / Vue / Blade (if present)

• Follow existing component patterns and conventions; do not mix frameworks unless the repo already does.
• Keep UI strings in the repo's expected language.

Tailwind CSS v4 (if present)

• Use

  @import "tailwindcss";

  and

  @theme

  for tokens.
• Avoid deprecated utilities; use replacements (e.g.,

  shrink-*

  ,

  grow-*

  ,

  text-ellipsis

  ).
• Use

  gap-*

  for spacing between items; follow existing dark mode conventions if present.

Testing and Formatting

• Use PHPUnit; generate tests with

  php artisan make:test --phpunit

  and prefer feature tests.
• Run the minimal relevant tests (

  php artisan test <file>

  or

  --filter=

  ).
• Run

  vendor/bin/pint --dirty

  before finalizing code changes.
• After minimal tests pass, offer to run the full test suite.

Laravel Boost MCP Tools (when available)

• search-docs

  before changing behavior or using framework features.

• list-artisan-commands

  to confirm Artisan options.

• list-routes

  to inspect routing changes.

• tinker

  for PHP debugging and

  database-query

  for read-only DB checks.

• browser-logs

  to inspect frontend errors.

• get-absolute-url

  for sharing project URLs.
• See

  references/boost-tools.md

  for query patterns and tool usage tips.

Output Expectations

• Preserve existing architecture, structure, and dependencies unless the user explicitly requests changes.
• Reuse existing components and follow local patterns.
• Ask concise clarifying questions when repo guidance is missing or ambiguous.