CLAUDE.md for Laravel: a copyable template for Laravel 13 apps

What should a CLAUDE.md for Laravel include?

A CLAUDE.md for Laravel should give Claude Code the exact commands to set up, run, test and format the app, a short map of where controllers, form requests, models and migrations live, and your rules for validation, mass assignment, env() and queues. Keep it under 200 lines, as Anthropic's memory docs recommend, and add the gotchas Claude cannot see in the code.

Laravel already helps agents more than most frameworks. The AI assisted development page makes the point that predictable file locations and naming mean an agent "knows exactly where to place" a new controller. What the framework cannot tell Claude is your choices: Pest or PHPUnit, Livewire or Inertia, which database runs locally, and which commands are off limits.

The template below targets Laravel 13, which the release notes say requires PHP 8.3 or newer. The commands come from the Laravel docs and the laravel/laravel skeleton's Composer scripts. Choices such as Pest, thin controllers and the eager loading rule are common conventions, not requirements, so swap them for yours. For the file format in general, see what a CLAUDE.md file is.

The Laravel CLAUDE.md template

Save this as CLAUDE.md at the root of your app, replace the angle-bracket placeholders, and delete lines that do not match your project.

# <App name>

<One sentence: what this app does and who uses it.>
Stack: Laravel 13, PHP 8.3+, <SQLite locally, PostgreSQL in production>,
<Blade + Livewire | Inertia + Vue>, Pest, Vite.

## Commands
- First setup: `composer run setup` (install, .env, app key, migrate, npm build)
- Dev: `composer run dev` (server, queue worker and Vite; http://localhost:8000)
- Tests: `php artisan test`. One file: `php artisan test tests/Feature/OrderTest.php`
- Filter by name: `php artisan test --filter="creates an order"`
- Stop on first failure: `php artisan test --stop-on-failure`
- Format: `./vendor/bin/pint --dirty`. Check only: `./vendor/bin/pint --test`
- Routes: `php artisan route:list`. Command help: `php artisan help <command>`
- New migration: `php artisan make:migration add_status_to_orders_table`
- Migrate: `php artisan migrate`. Status: `php artisan migrate:status`
- Preview migration SQL: `php artisan migrate --pretend`
- Done means: `./vendor/bin/pint --test` and `php artisan test` both pass

## Project structure
- `app/Http/Controllers/`: controllers. `app/Http/Requests/`: form requests
- `app/Models/`: Eloquent models. `app/Jobs/`: queued jobs. `app/Policies/`: authorization
- `routes/web.php`: browser routes. `routes/api.php`: stateless API routes
- `routes/console.php`: closure commands and the schedule
- `bootstrap/app.php`: middleware, exception handling and route registration
- `database/migrations/`, `database/factories/`, `database/seeders/`
- `resources/views/`: Blade. `resources/js/`: frontend entry for Vite
- `tests/Feature/`: most tests. `tests/Unit/`: tests that do not boot the app

## Conventions
- Create classes with `php artisan make:*` so names and folders line up
- Validate in form requests (`php artisan make:request StoreOrderRequest`)
- Save with `$request->validated()`, never `$request->all()`
- Every model lists its mass-assignable fields with `#[Fillable([...])]`; no `#[Unguarded]`
- Call `env()` only inside `config/` files; app code reads `config('...')`
- Eager load relationships used in lists with `with()`; no N+1 queries
- Slow or external work goes in a job that implements `ShouldQueue`
- Controllers stay thin: validate, call a model or action class, return a response

## Migrations
- Never edit a migration that has run anywhere but your machine; write a new one
- Never run `migrate:fresh` or `migrate --force` unless I ask
- Every migration has a working `down()` method

## Testing
- Pest. New feature test: `php artisan make:test OrderTest`; unit: add `--unit`
- Prefer feature tests that hit routes over unit tests of internals
- Use factories for test data; no hand-written inserts
- Every bug fix comes with a test that failed before the fix

## Secrets
- `.env` is never committed, printed or logged. Add new keys to `.env.example`
- Test-only values go in `phpunit.xml` or `.env.testing`

## Do not
- Do not add a Composer or npm package without asking
- Do not edit anything in `vendor/`
- Do not run `php artisan config:cache` locally
- Do not disable CSRF protection or mass assignment protection

## Gotchas
- Queue workers keep old code in memory. Restart them after changing a job
- After editing `phpunit.xml` env values, run `php artisan config:clear`
- Public uploads need `php artisan storage:link` once per machine
- <Your app's own surprises: tenants, feature flags, seed data, third-party sandboxes>

How does this template work with Laravel Boost?

Laravel Boost is Laravel's official package for coding agents. You install it with composer require laravel/boost --dev and run php artisan boost:install, which generates guideline and skill files for the agents you select and registers an MCP server. The Boost docs say Claude Code support "is typically enabled automatically"; if not, they give claude mcp add -s local -t stdio laravel-boost php artisan boost:mcp.

The part that matters for this template is how Boost writes CLAUDE.md. Per the docs, if CLAUDE.md or AGENTS.md already exists, Boost "only replaces the content inside its <laravel-boost-guidelines> block", so anything you wrote outside that block survives boost:install and boost:update. You can paste the template above or below the block and keep both.

There is one decision to make. The Boost docs also say you may add generated files like CLAUDE.md, AGENTS.md and .mcp.json to .gitignore, since Boost regenerates them. That works for Boost's own content, but a gitignored CLAUDE.md means your hand-written rules never reach teammates. Pick one setup:

Boost also has project rules in .ai/rules/, files with a paths frontmatter field that Boost lists in an index for agents to consult. Claude Code has its own path-scoped rules in .claude/rules/, which it loads automatically when it touches a matching file. Use one system for a given rule, not both, so the same instruction does not drift into two versions.

What does each part of the template do?

Header and stack line. Naming Laravel 13 and your frontend stack stops Claude from writing Livewire in an Inertia app or using APIs from older versions.

Commands. composer run setup, composer run dev and the test script are defined in the laravel/laravel skeleton's composer.json, and the installation guide says composer run dev starts the server, queue worker and Vite together. The testing guide says any argument you can pass to Pest or PHPUnit can be passed to php artisan test, which is why the file path and --filter lines work. The Pint flags come from the Pint docs: --dirty formats only files with uncommitted changes, and --test reports problems with a non-zero exit code without changing files, which makes it a good done-check.

Project structure. This follows the directory structure page, including that routes/api.php only exists after php artisan install:api. The middleware docs register global middleware and middleware groups in bootstrap/app.php, so the template points Claude there instead of letting it search for another place.

Conventions. The validation docs describe form requests as classes that hold their own validation and authorization logic. The Eloquent docs explain why mass assignment matters: a user could send an unexpected field like is_admin. The Laravel 13 docs declare the allowed fields with the Fillable attribute, and the docs ask for special care with Unguarded models. The env() rule comes from the configuration docs: once config is cached, .env is not loaded, so env() calls outside config files stop returning your values.

Migrations. The migrations docs warn that migrate:fresh drops every table regardless of prefix and that destructive commands prompt for confirmation in production unless you pass --force. Never editing a migration that already ran elsewhere is a team convention, not a Laravel rule, but it prevents schema drift between machines.

Testing. New apps include support for both Pest and PHPUnit, and the testing guide says "most of your tests should be feature tests". Unit tests in tests/Unit do not boot the application, so they cannot touch the database. Swap Pest for PHPUnit if that is what your suite uses.

Gotchas. The queues docs note that workers are long-lived and "will not notice changes in your code" until restarted. The testing guide says to clear the config cache after changing test environment values in phpunit.xml.

Which agent mistakes does the template prevent?

When you add rules, name the mistake first and write the shortest line that prevents it.

How do you adapt it to your project?

• PHPUnit instead of Pest: change the testing section. php artisan test runs either.
• Sail: write commands the Sail way, such as ./vendor/bin/sail artisan test and ./vendor/bin/sail composer require, so Claude runs them inside the container. The Sail docs list the equivalents.
• API-only app: drop resources/views/ and Vite, and add your API resource and authentication conventions.
• Inertia or Livewire: add two or three lines on where pages or components live. If you use Boost, its Inertia and Livewire skills cover the framework detail.
• Rules for one area: create .claude/rules/controllers.md with paths: ["app/Http/Controllers/**"] in the frontmatter. Claude Code loads it only when it reads or edits a controller.

After saving, run /context in a Claude Code session and check that CLAUDE.md is listed under Memory files. In an existing app without a CLAUDE.md, /init generates a draft from your code that you can merge with these sections.

Should you write an AGENTS.md version too?

If your team also uses Codex, Cursor or Copilot, put the shared content in AGENTS.md and keep CLAUDE.md short. Boost can generate AGENTS.md too, with the same block behavior. Claude Code reads AGENTS.md on its own only when there is no CLAUDE.md or CLAUDE.local.md, and only from v2.1.277, so an import keeps both working:

@AGENTS.md

## Claude Code only
- Use plan mode before touching billing or any migration
- Run `/doctor prompt-audit` after editing AGENTS.md or this file

Claude reads the imported file first, then the lines below it. The AGENTS.md guide covers which tools read the file, and CLAUDE.md vs AGENTS.md explains the trade-offs.

How do you keep a Laravel CLAUDE.md useful?

Add a line when Claude makes the same mistake twice, and delete lines it follows without being told. After a Laravel major upgrade, update the version and recheck every command. If you use Boost, run php artisan boost:update so its guidelines match your installed packages. /doctor prompt-audit (Claude Code v2.1.283 or later) reports outdated or conflicting instructions with proposed edits and changes nothing until you ask. CLAUDE.md guides Claude but does not enforce anything, so for a hard rule such as never running migrate:fresh, use a hook.

If you start Laravel apps often, keep the template where you can reuse it. Kipt stores prompts and Agent Skills as Markdown in a private GitHub repo you own, so you could save this template as a prompt with blanks like {{frontend:Livewire}} and fill them per project. The Laravel prompts collection has task prompts to pair with it, and templates for other stacks include Rails, Django and Vue.