Claude Code for Laravel & PHP: CLAUDE.md, Laravel Boost, and the .ai/rules System (2026)

Laravel is one of the most widely deployed backend frameworks in the world, and until recently there wasn’t a first-party answer to “how do I configure Claude Code for this.” That changed when Laravel shipped Boost — an official Composer package that installs an MCP server and generates CLAUDE.md/AGENTS.md files for you. Most existing guides either predate Boost and hand-roll a CLAUDE.md, or mention Boost in passing without explaining the three-layer system it actually uses (guidelines, skills, and project rules) — and that gap is where most Laravel + Claude Code setups go wrong.

We read Laravel’s official Boost documentation, cross-checked it against real CLAUDE.md files from Laravel maintainers, and pulled apart what Boost automates versus what you still have to write by hand. This guide covers both paths: a manual template for projects that don’t use Boost, and a full breakdown of Boost’s MCP tools, guideline layers, and the gitignore trap that catches teams who install it without reading the docs.

Browse real-world CLAUDE.md and AGENTS.md examples — including a Laravel/PHP file from a Spatie maintainer — in our gallery.

Why a Generic PHP CLAUDE.md Falls Short

Laravel is opinionated in ways plain PHP isn’t, and a CLAUDE.md written for “PHP” instead of “Laravel” misses all of it. Without Laravel-specific rules, Claude Code tends to:

• Write raw SQL or query builder chains where an Eloquent relationship already exists
• Put business logic in controllers instead of actions, services, or form requests
• Skip FormRequest validation classes and validate inline in the controller
• Generate migrations that don’t match the project’s existing column-naming conventions
• Miss that a Livewire component or Filament resource already handles the exact CRUD flow it’s about to hand-write
• Use env() calls outside of config files, which breaks config caching in production

None of these are PHP mistakes — they’re Laravel convention mistakes, and Laravel’s conventions are exactly the kind of implicit knowledge Claude Code can’t infer from the code alone if the project is small or inconsistent.

Two Paths: Manual CLAUDE.md or Laravel Boost

There are two legitimate ways to configure Claude Code for a Laravel project, and which one fits depends on the project’s age and size.

Manual CLAUDE.md — write it yourself, commit it, done. This is what most Laravel developers did before Boost existed, and it’s still the right call for small projects, packages, or teams who want full control over exactly what loads into context.

Laravel Boost — an official Composer package (laravel/boost) that installs an MCP server giving Claude Code direct access to your app (routes, Eloquent models, database schema, logs) and auto-generates guideline files scoped to the packages you actually have installed. This is the better default for any Laravel 10+ project using Livewire, Filament, Inertia, or Pest, because Boost’s guidelines are versioned per-package (e.g., Livewire 3.x vs 4.x) — something a hand-written file won’t track as your dependencies update.

They aren’t mutually exclusive. Boost generates the framework-level context; you still add your own application-specific conventions on top, either by hand or through Boost’s project rules system (more on that below).

The Minimal Manual Approach

If you’re not using Boost, the highest-leverage CLAUDE.md isn’t the longest one. Here’s a real example from a Spatie/Laravel maintainer, pulled from our gallery — 10 lines, no framework boilerplate, and it’s been cited by Anthropic’s own team as a model of what a CLAUDE.md should look like:

## General

Do not tell me I am right all the time. Be critical. We're equals. Try to be neutral and objective.

Do not excessively use emojis.

Prefer using browser agent skill over using playwright directly.

## Coding Standards
When working with Laravel/PHP projects, always use the php-guidelines-from-spatie skill

## Using GitHub
For questions about GitHub, use the gh tool
Never mention Claude Code in PR descriptions, PR comments, or issue comments
Do not include a "Test plan" section in PR descriptions

Notice what’s missing: no Eloquent conventions, no directory structure, no testing rules. This file lives in the user’s global ~/.claude/CLAUDE.md, not the project. It sets tone and delegates the actual Laravel/PHP knowledge to a separate skill (php-guidelines-from-spatie) instead of dumping everything into one file. That’s a pattern worth copying even if you don’t adopt Boost: keep global preferences short, and put framework-specific detail somewhere that loads on demand rather than every session.

Laravel Boost: Installation and What It Generates

Boost installs via Composer and registers itself in one command:

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

boost:install walks you through selecting your AI agent (Claude Code, Cursor, Codex, Gemini CLI, GitHub Copilot, Junie) and then generates:

• .mcp.json — registers the Boost MCP server for your agent
• CLAUDE.md / AGENTS.md — guideline files scoped to your installed packages
• boost.json — Boost’s own configuration

For Claude Code specifically, MCP support is typically enabled automatically once these files exist. If it isn’t, register it manually:

claude mcp add -s local -t stdio laravel-boost php artisan boost:mcp

The MCP Tools Boost Gives Claude Code

This is the part most articles skip — Boost isn’t just a file generator, it’s a live connection into your running application:

The practical effect: Claude Code can check your actual users table schema instead of guessing from a migration file that might be stale, and it can look up version-correct Livewire 4.x syntax instead of hallucinating Livewire 2.x patterns from its training data.

Guidelines vs. Skills vs. Project Rules

Boost’s documentation draws a three-way distinction that almost no third-party guide explains clearly, and getting it wrong is why some teams end up with either a bloated context window or a Claude Code that keeps forgetting the same correction.

Guidelines teach Claude Code how to write Laravel. Project rules teach it how to write your Laravel app — the tenant-scoping base controller everyone forgets to extend, the fact that money is stored as integer cents, the reason a certain package was pinned to an older version. You don’t hand-write these; you tell Claude Code to remember them and it calls Boost’s record-rule MCP tool:

Remember that all money values are stored as integer cents, never as floats.

Boost files that under the right glob (e.g., app/Models/**), regenerates .ai/rules/index.md, and every future session — including ones from teammates who never had that conversation — picks it up automatically, because agents are instructed to check the index before editing a matched file.

The Gitignore Trap

This is the mistake we see repeated across setup threads: CLAUDE.md, AGENTS.md, .mcp.json, and boost.json are meant to be gitignored. They’re regenerated every time someone runs boost:install or boost:update, so committing them just creates merge noise and stale diffs.

.ai/rules/ is the opposite — it should be committed. It’s your team’s accumulated project knowledge, and it’s the one part of the system that Boost doesn’t regenerate; it only appends to it via record-rule.

Get this backwards — commit the generated files, gitignore the rules directory — and you’ll either lose your team’s conventions the first time someone reinstalls Boost, or bloat your git history with regenerated boilerplate every time a package updates its guidelines.

A Manual CLAUDE.md Template (If You’re Not Using Boost)

For projects that skip Boost — packages, legacy apps on Laravel <10, or teams who prefer full manual control — here’s a starting template covering the conventions Claude Code gets wrong most often:

# CLAUDE.md — Laravel Project

## Stack
- Laravel {version}, PHP {version}
- Database: {MySQL/PostgreSQL/SQLite}
- Frontend: {Livewire / Inertia+React / Inertia+Vue / Blade}
- Testing: Pest
- Admin: {Filament, if applicable}

## Architecture Rules
- Business logic goes in Action classes (`app/Actions/`) or Services (`app/Services/`), not controllers.
- Controllers stay thin: validate via FormRequest, call one Action/Service, return a response.
- Never call `env()` outside of `config/*.php` files — it breaks config caching in production.
- Use Eloquent relationships instead of manual joins or raw queries unless there's a documented performance reason.
- Form validation belongs in a `FormRequest` class, not inline in the controller.

## Naming Conventions
- Controllers: `{Resource}Controller`, one resource per controller.
- Actions: `{Verb}{Resource}Action`, e.g. `CreateInvoiceAction`.
- Form Requests: `{Verb}{Resource}Request`, e.g. `StoreInvoiceRequest`.
- Migrations: follow existing column naming — check `database/migrations/` before adding new columns.

## Database
- Every new migration needs a corresponding factory update if the model has a factory.
- Never run `migrate:fresh` or `migrate:reset` against anything but the local/test database.
- Soft deletes: check whether the model uses `SoftDeletes` before writing a hard-delete query.

## Testing (Pest)
- New features require a Feature test covering the happy path and at least one authorization/validation failure.
- Use model factories, not manually constructed arrays, for test data.
- Run `php artisan test` (or `./vendor/bin/pest`) before marking any task complete.

## Commands
- Lint: `./vendor/bin/pint`
- Static analysis: `./vendor/bin/phpstan analyse` (if configured)
- Tests: `php artisan test`
- Queue worker (local): `php artisan queue:listen`

Adjust the stack section to match your actual dependencies — the value of this file drops fast if it claims a frontend stack or test runner the project doesn’t use.

AGENTS.md for Multi-Domain Laravel Apps

Larger Laravel apps — an API, an admin panel built with Filament, and background queue workers — benefit from scoping agent instructions by directory, the same way you would in any monorepo-style codebase:

# AGENTS.md

## Global Rules
- Follow all rules in CLAUDE.md.
- Run `./vendor/bin/pint` and `php artisan test` before marking any task complete.
- Never edit `.env` directly; add new config through `config/*.php`.

## /app/Filament/
Agent scope: Admin panel resources and pages.
- Filament resources should use existing form/table schema patterns from `app/Filament/Resources/`.
- Authorization goes through Filament's Policy integration — don't hand-roll access checks in a resource.

## /app/Http/Controllers/Api/
Agent scope: Public API layer.
- All responses go through API Resource classes (`app/Http/Resources/`), never raw Eloquent models.
- Versioned routes live under `routes/api_v1.php` — don't add new endpoints to unversioned `routes/api.php`.

## /app/Jobs/
Agent scope: Queued jobs and background processing.
- Jobs must implement `ShouldQueue` and be idempotent — assume any job can run twice.
- Failed jobs are handled by the `failed()` method, not a try/catch swallowing the exception.

This matters more for Laravel than for many frameworks specifically because Filament, the API layer, and queue jobs often have different authorization models, and an agent working across all three without scoped rules tends to bleed patterns from one domain into another — for example, applying a Filament policy check inside an API controller that has its own auth middleware.

Common Mistakes to Watch For

Committing Boost’s generated files. Covered above, but worth repeating: CLAUDE.md, AGENTS.md, .mcp.json, and boost.json are regenerated artifacts when Boost is in use. Gitignore them; commit .ai/rules/ instead.

Writing rules by hand instead of using record-rule. If you’re on Boost, manually editing .ai/rules/*.md works until the next boost:update, which relies on index.md staying in sync with what’s actually in the directory. Manually added files won’t be indexed until the next regeneration. Ask Claude Code to remember the rule instead of editing the file yourself.

No FormRequest, validation inline. Without an explicit rule, Claude Code will happily validate in the controller with $request->validate([...]) because it’s shorter — even on a project where every other controller uses a FormRequest class.

Skipping Pest’s expressive syntax. Left unguided, some agents default to PHPUnit-style TestCase classes even in a Pest project, because that’s what shows up more often in training data. If you’re on Pest, say so explicitly.

Trusting stale migration files for schema. On a project with squashed or heavily modified migrations, the migration files don’t reflect the current schema. If you’re on Boost, this is exactly what the Database Schema MCP tool solves — Claude Code queries the real schema instead of reading migration history.

If you’re starting a new Laravel project in 2026, install Boost first and let it generate your baseline — then layer your own conventions on top through record-rule rather than hand-editing the generated files. If you’re on an older Laravel version or maintaining a package where Boost doesn’t fit, the manual template above covers the conventions that matter most.

Browse more real Laravel, PHP, and framework-specific CLAUDE.md/AGENTS.md examples in our gallery.

FAQ

Do I need Laravel Boost to use Claude Code with Laravel? No. Boost is the officially recommended path for Laravel 10+ projects because it keeps guidelines versioned to your installed packages and gives Claude Code live access to your database schema and logs, but a hand-written CLAUDE.md works fine for smaller projects or packages.

Should I commit the CLAUDE.md file that Laravel Boost generates? No — Boost’s generated CLAUDE.md, AGENTS.md, .mcp.json, and boost.json are meant to be gitignored since they’re regenerated on every boost:install or boost:update. Commit .ai/rules/ instead, since that’s where your team’s actual project-specific conventions live.

What’s the difference between Boost’s guidelines, skills, and project rules? Guidelines load upfront every session and cover framework conventions (Laravel core, Livewire, Pest). Skills load on-demand for specific tasks like writing a Filament resource. Project rules are your own application’s conventions, recorded via the record-rule MCP tool and matched to files by glob pattern through .ai/rules/index.md.

Does Laravel Boost work with Cursor and other AI tools, or just Claude Code? Boost supports Claude Code, Cursor, Codex, Gemini CLI, GitHub Copilot (VS Code), and Junie. The installer detects which agents you’re using and generates the appropriate guideline and MCP configuration files for each.

How do I add my own project conventions without Boost regenerating over them? Don’t edit the generated CLAUDE.md by hand — ask Claude Code to remember the convention (e.g., “Remember that all money values are stored as integer cents”) and it will call Boost’s record-rule tool, which stores it in .ai/rules/ where regeneration won’t touch it.