Claude Code for Laravel: A Practitioner's Workflow

After 14 years of PHP and Laravel development, I have integrated Claude Code into my daily workflow for everything from rapid prototyping to maintaining complex enterprise applications. The combination of Laravel's opinionated conventions and Claude Code's code understanding capabilities creates a uniquely productive development experience---but only when you know how to leverage both effectively.

This guide shares the specific workflows I use for common Laravel development tasks: generating migrations, writing tests, debugging Eloquent queries, scaffolding APIs, and refactoring legacy code. These are not theoretical patterns but battle-tested approaches refined through real client projects.

For developers concerned about usage limits and token consumption while following these workflows, see my guide on Claude Code token management strategies to maximize productivity within subscription constraints.

Setting Up Claude Code for Laravel Projects

Before diving into workflows, proper setup makes everything that follows more effective. Laravel's recent AI tooling ecosystem provides excellent foundations.

Installing Laravel Boost

Laravel Boost is Laravel's official MCP (Model Context Protocol) server that transforms Claude Code from a general-purpose assistant into a Laravel expert that understands your specific application. Install it as a development dependency:

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

During installation, select Claude Code as your editor. Boost provides over 15 specialized tools including:

Database schema inspection: Claude can query your actual table structures
Route inspection: Understanding your application's routing with middleware
Artisan command discovery: Knowledge of available commands
Documentation search: 17,000+ pieces of indexed Laravel documentation
Tinker integration: Execute PHP directly to test assumptions

Connecting Boost to Claude Code

After installation, add the MCP server to Claude Code:

claude mcp add laravel-boost -- php artisan boost:mcp

Verify the connection by asking Claude about your application:

What Laravel version is this project running? List the installed first-party packages.

Claude should respond with accurate information pulled directly from your application.

Creating an Effective CLAUDE.md

While Boost provides automatic context, a well-crafted CLAUDE.md file adds project-specific knowledge that no automated tool can infer. For Laravel projects, I use this structure:

# Project Context

## Application Overview
- **Framework**: Laravel 11.x with PHP 8.3
- **Frontend**: Livewire 3 with Tailwind CSS 4
- **Testing**: Pest PHP with parallel execution
- **Code Style**: Laravel Pint with preset laravel

## Conventions
- Use Form Requests for validation (not inline $request->validate())
- Repository pattern for complex data access, direct Eloquent for simple queries
- API resources for all JSON responses
- Feature tests for HTTP endpoints, unit tests for services

## Commands
```bash
php artisan test --parallel          # Run full test suite
php artisan test --filter=ClassName  # Run specific test
./vendor/bin/pint --dirty            # Format changed files
php artisan migrate:fresh --seed     # Reset database (dev only)

Do Not Modify

app/Services/PaymentGateway.php (PCI audited)
config/services.php credentials (use .env)
database/migrations/ existing files (create new migrations)

Project-Specific Patterns

Money stored as integers (cents), use Money value object
Dates use Carbon, display in user's timezone from settings
Soft deletes on all models with user data


Run `/init` to bootstrap an initial file, but always curate it manually. The auto-generated content is a starting point, not a final product. For comprehensive strategies on creating effective CLAUDE.md files, especially in complex scenarios, see my [SEO optimization case study](/blog/claude-code-seo-optimization-case-study) which demonstrates advanced agent configuration.

## Workflow: Generating Migrations and Models

Migration generation is where Claude Code saves the most time for routine work. The key is providing complete context upfront.

### The Complete Context Prompt

Instead of asking Claude to create a migration piecemeal, provide full business context:

Create a migration and model for a Project entity with these requirements:

Projects belong to a User (creator) and a Team
Projects have: name (required, max 255), description (nullable text), status (enum: draft, active, completed, archived), budget (money as cents), start_date and end_date (nullable dates)
Projects can have many Tasks (future migration)
Include soft deletes and timestamps
Add appropriate indexes for common queries

Follow our project conventions in CLAUDE.md.


Claude generates the migration with proper foreign keys, indexes, and the enum handling Laravel expects:

```php
<?php

use Illuminate\Database\Migrations\Migration;
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\Schema;

return new class extends Migration
{
    public function up(): void
    {
        Schema::create('projects', function (Blueprint $table) {
            $table->id();
            $table->foreignId('user_id')->constrained()->cascadeOnDelete();
            $table->foreignId('team_id')->constrained()->cascadeOnDelete();
            $table->string('name');
            $table->text('description')->nullable();
            $table->enum('status', ['draft', 'active', 'completed', 'archived'])
                ->default('draft');
            $table->unsignedBigInteger('budget')->default(0);
            $table->date('start_date')->nullable();
            $table->date('end_date')->nullable();
            $table->timestamps();
            $table->softDeletes();

            // Indexes for common query patterns
            $table->index(['team_id', 'status']);
            $table->index(['user_id', 'created_at']);
        });
    }

    public function down(): void
    {
        Schema::dropIfExists('projects');
    }
};

The Follow-Up Model Request

After the migration, request the complete model with relationships and casts:

Now create the Project model with:
- Proper relationships to User (creator), Team, and Tasks (hasMany)
- Casts for status enum, dates, and money fields
- Scopes for common filters (active, byTeam, overBudget)
- Follow our money convention (stored as cents, accessor returns dollars)

Claude generates a model aligned with your conventions:

<?php

namespace App\Models;

use App\Enums\ProjectStatus;
use Illuminate\Database\Eloquent\Builder;
use Illuminate\Database\Eloquent\Factories\HasFactory;
use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\Relations\BelongsTo;
use Illuminate\Database\Eloquent\Relations\HasMany;
use Illuminate\Database\Eloquent\SoftDeletes;

class Project extends Model
{
    use HasFactory, SoftDeletes;

    protected $fillable = [
        'user_id',
        'team_id',
        'name',
        'description',
        'status',
        'budget',
        'start_date',
        'end_date',
    ];

    protected function casts(): array
    {
        return [
            'status' => ProjectStatus::class,
            'budget' => 'integer',
            'start_date' => 'date',
            'end_date' => 'date',
        ];
    }

    // Relationships

    public function creator(): BelongsTo
    {
        return $this->belongsTo(User::class, 'user_id');
    }

    public function team(): BelongsTo
    {
        return $this->belongsTo(Team::class);
    }

    public function tasks(): HasMany
    {
        return $this->hasMany(Task::class);
    }

    // Accessors

    public function getBudgetInDollarsAttribute(): float
    {
        return $this->budget / 100;
    }

    // Scopes

    public function scopeActive(Builder $query): Builder
    {
        return $query->where('status', ProjectStatus::Active);
    }

    public function scopeByTeam(Builder $query, int $teamId): Builder
    {
        return $query->where('team_id', $teamId);
    }

    public function scopeOverBudget(Builder $query): Builder
    {
        return $query->whereHas('tasks', function ($q) {
            $q->selectRaw('SUM(actual_cost) as total_cost')
                ->havingRaw('total_cost > projects.budget');
        });
    }
}

When to Verify Manually

Always verify:

Foreign key constraints: Claude sometimes suggests cascade behaviors that do not match your data integrity requirements
Index placement: Composite indexes should match your actual query patterns
Enum values: Ensure the enum definition matches existing application constants
Money handling: Verify the conversion logic matches your precision requirements

Run the migration on a test database before committing:

php artisan migrate:fresh --seed --env=testing

Workflow: Writing Feature and Unit Tests

Testing is where Claude Code's ability to understand existing code patterns shines. The workflow differs for new features versus existing code.

Testing New Features

When you have just created a feature, ask Claude to generate comprehensive tests:

Write Pest feature tests for the ProjectController covering:
- Index: listing projects filtered by team, pagination
- Store: validation, authorization (user must belong to team)
- Show: authorization, 404 handling
- Update: partial updates, status transitions
- Delete: soft delete, authorization

Use our project's testing conventions. Check tests/ directory for examples.

Claude reads your existing test patterns and generates consistent tests:

<?php

use App\Models\Project;
use App\Models\Team;
use App\Models\User;
use App\Enums\ProjectStatus;

beforeEach(function () {
    $this->team = Team::factory()->create();
    $this->user = User::factory()->create();
    $this->user->teams()->attach($this->team);
});

describe('Project Index', function () {
    it('lists projects for the authenticated user team', function () {
        $projects = Project::factory()
            ->count(3)
            ->for($this->team)
            ->for($this->user, 'creator')
            ->create();

        // Create project for different team (should not appear)
        Project::factory()->create();

        $response = $this->actingAs($this->user)
            ->getJson("/api/teams/{$this->team->id}/projects");

        $response
            ->assertOk()
            ->assertJsonCount(3, 'data')
            ->assertJsonStructure([
                'data' => [
                    '*' => ['id', 'name', 'status', 'budget', 'created_at'],
                ],
                'meta' => ['current_page', 'total'],
            ]);
    });

    it('filters projects by status', function () {
        Project::factory()
            ->for($this->team)
            ->for($this->user, 'creator')
            ->create(['status' => ProjectStatus::Active]);

        Project::factory()
            ->for($this->team)
            ->for($this->user, 'creator')
            ->create(['status' => ProjectStatus::Draft]);

        $response = $this->actingAs($this->user)
            ->getJson("/api/teams/{$this->team->id}/projects?status=active");

        $response
            ->assertOk()
            ->assertJsonCount(1, 'data');
    });
});

describe('Project Store', function () {
    it('creates a project with valid data', function () {
        $projectData = [
            'name' => 'New Project',
            'description' => 'Project description',
            'status' => 'draft',
            'budget' => 10000, // $100.00
            'start_date' => now()->addDay()->format('Y-m-d'),
        ];

        $response = $this->actingAs($this->user)
            ->postJson("/api/teams/{$this->team->id}/projects", $projectData);

        $response
            ->assertCreated()
            ->assertJsonPath('data.name', 'New Project')
            ->assertJsonPath('data.status', 'draft');

        $this->assertDatabaseHas('projects', [
            'team_id' => $this->team->id,
            'user_id' => $this->user->id,
            'name' => 'New Project',
        ]);
    });

    it('validates required fields', function () {
        $response = $this->actingAs($this->user)
            ->postJson("/api/teams/{$this->team->id}/projects", []);

        $response
            ->assertUnprocessable()
            ->assertJsonValidationErrors(['name']);
    });

    it('prevents non-team-members from creating projects', function () {
        $outsider = User::factory()->create();

        $response = $this->actingAs($outsider)
            ->postJson("/api/teams/{$this->team->id}/projects", [
                'name' => 'Unauthorized Project',
            ]);

        $response->assertForbidden();
    });
});

describe('Project Update', function () {
    it('updates project with partial data', function () {
        $project = Project::factory()
            ->for($this->team)
            ->for($this->user, 'creator')
            ->create(['name' => 'Original Name']);

        $response = $this->actingAs($this->user)
            ->patchJson("/api/projects/{$project->id}", [
                'name' => 'Updated Name',
            ]);

        $response
            ->assertOk()
            ->assertJsonPath('data.name', 'Updated Name');
    });

    it('validates status transitions', function () {
        $project = Project::factory()
            ->for($this->team)
            ->for($this->user, 'creator')
            ->create(['status' => ProjectStatus::Completed]);

        // Cannot transition from completed back to draft
        $response = $this->actingAs($this->user)
            ->patchJson("/api/projects/{$project->id}", [
                'status' => 'draft',
            ]);

        $response->assertUnprocessable();
    });
});

describe('Project Delete', function () {
    it('soft deletes the project', function () {
        $project = Project::factory()
            ->for($this->team)
            ->for($this->user, 'creator')
            ->create();

        $response = $this->actingAs($this->user)
            ->deleteJson("/api/projects/{$project->id}");

        $response->assertNoContent();

        $this->assertSoftDeleted('projects', ['id' => $project->id]);
    });
});

Characterization Tests for Existing Code

When working with existing code that lacks tests, ask Claude to generate characterization tests that document current behavior:

Read app/Services/InvoiceCalculator.php and generate characterization tests.
Focus on documenting current behavior, not what it should do.
Use the test fixtures in tests/fixtures/invoices.json if available.

This approach creates a safety net before refactoring. For comprehensive guidance on working with legacy Laravel codebases, including detailed characterization testing workflows, see my legacy codebase practitioner's guide.

Testing Complex Scenarios

For complex business logic, describe the scenario in detail:

Write a test for the invoice payment workflow:
1. User creates invoice for client
2. Invoice is sent (status changes, email triggered)
3. Client pays partial amount
4. Invoice status becomes 'partial'
5. Client pays remaining amount
6. Invoice status becomes 'paid', payment_completed_at is set

Mock the email sending. Test the complete flow and intermediate states.

Claude generates tests that cover the entire workflow while properly isolating external dependencies.

Workflow: Debugging Complex Eloquent Queries

Eloquent query debugging is one of Claude Code's strongest capabilities, especially when combined with Laravel Boost's database introspection.

The Debugging Prompt Pattern

When a query returns unexpected results, provide full context:

This query should return active projects with their task counts,
filtered to the current team, but it is returning projects from all teams:

```php
$projects = Project::query()
    ->withCount('tasks')
    ->where('status', 'active')
    ->whereHas('team.users', fn($q) => $q->where('id', auth()->id()))
    ->paginate();

Our team relationship: User belongsToMany Teams, Project belongsTo Team. What is wrong with this query?


Claude analyzes the relationship chain and identifies issues:

The issue is in your whereHas clause. You're checking if the project's team has the authenticated user, but you're not filtering to a specific team.

The query currently returns: "All active projects where the project's team contains the authenticated user" - which is ALL teams the user belongs to.

If you want projects from a SPECIFIC team, use:

$projects = Project::query()
    ->withCount('tasks')
    ->where('status', 'active')
    ->where('team_id', $currentTeamId)
    ->paginate();

Or if you want projects from all teams the user belongs to (which your current query should do), the whereHas looks correct. Check that:

The 'status' column contains 'active' (not an enum mismatch)
The team_users pivot table has the correct relationships
You're not caching the query results

To debug, add ->toSql() and ->getBindings() to see the generated SQL.


### N+1 Query Detection

Ask Claude to analyze controller methods for N+1 issues:

Analyze the ProjectController@index method for N+1 query problems. Check what relationships are accessed in the view/resource and whether they're being eager loaded.


Claude reads the controller, the resource class, and identifies missing eager loads:

Found N+1 issues in ProjectController@index:

ProjectResource accesses $project->creator->name but creator isn't loaded
ProjectResource accesses $project->tasks->count() - should use withCount
The team relationship is loaded but team.subscription is accessed in the authorization check without eager loading

Optimized query:

$projects = Project::query()
    ->with(['creator:id,name', 'team.subscription'])
    ->withCount('tasks')
    ->where('team_id', $teamId)
    ->latest()
    ->paginate(25);

This reduces queries from ~52 (25 projects * 2 relationships + base) to 4.


### Query Performance Analysis

For slow queries, ask Claude to suggest optimizations:

This query takes 3+ seconds on 50k projects:

$overdueProjects = Project::query()
    ->where('status', 'active')
    ->where('end_date', '<', now())
    ->whereDoesntHave('invoices', fn($q) => $q->where('status', 'paid'))
    ->get();

Our indexes: projects(status), projects(end_date), invoices(project_id, status). How can we optimize this?


Claude suggests specific optimizations:

The whereDoesntHave is causing a correlated subquery for each row. Consider these optimizations:

Add composite index (most impactful):

$table->index(['status', 'end_date']);

Rewrite with LEFT JOIN (avoids correlated subquery):

$overdueProjects = Project::query()
    ->leftJoin('invoices', function ($join) {
        $join->on('projects.id', '=', 'invoices.project_id')
            ->where('invoices.status', '=', 'paid');
    })
    ->whereNull('invoices.id')
    ->where('projects.status', 'active')
    ->where('projects.end_date', '<', now())
    ->select('projects.*')
    ->get();

Use chunk for large datasets:

Project::query()
    ->where('status', 'active')
    ->where('end_date', '<', now())
    ->whereDoesntHave('invoices', fn($q) => $q->where('status', 'paid'))
    ->chunk(1000, function ($projects) {
        // Process batch
    });

For the best results, add the composite index and consider whether you can cache this query result (it only needs to update daily).


## Workflow: Scaffolding API Endpoints

API scaffolding is where Claude Code accelerates development most dramatically. The key is providing complete specifications upfront.

### The Complete API Specification Prompt

Create a complete API resource for Projects with these requirements:

Routes:

GET /api/v1/teams/{team}/projects (index, paginated)
POST /api/v1/teams/{team}/projects (store)
GET /api/v1/projects/{project} (show)
PATCH /api/v1/projects/{project} (update)
DELETE /api/v1/projects/{project} (destroy)

Authorization:

Users can only access projects in teams they belong to
Only team admins can delete projects
Project creator or team admin can update

Validation:

name: required, max 255
description: nullable, max 5000
status: enum (draft, active, completed, archived)
budget: integer (cents), min 0
start_date/end_date: dates, end must be after start

Generate: routes, controller, form requests, resource, policy. Follow our API conventions from CLAUDE.md.


Claude generates all components following your conventions. Here is the controller as an example:

```php
<?php

namespace App\Http\Controllers\Api\V1;

use App\Http\Controllers\Controller;
use App\Http\Requests\StoreProjectRequest;
use App\Http\Requests\UpdateProjectRequest;
use App\Http\Resources\ProjectResource;
use App\Http\Resources\ProjectCollection;
use App\Models\Project;
use App\Models\Team;
use Illuminate\Http\JsonResponse;
use Illuminate\Http\Response;

class ProjectController extends Controller
{
    public function __construct()
    {
        $this->authorizeResource(Project::class, 'project');
    }

    /**
     * List projects for a team
     */
    public function index(Team $team): ProjectCollection
    {
        $this->authorize('viewAny', [Project::class, $team]);

        $projects = $team->projects()
            ->with(['creator:id,name'])
            ->withCount('tasks')
            ->when(request('status'), fn($q, $status) => $q->where('status', $status))
            ->latest()
            ->paginate(request('per_page', 25));

        return new ProjectCollection($projects);
    }

    /**
     * Create a new project
     */
    public function store(StoreProjectRequest $request, Team $team): JsonResponse
    {
        $project = $team->projects()->create([
            ...$request->validated(),
            'user_id' => $request->user()->id,
        ]);

        return (new ProjectResource($project->load('creator')))
            ->response()
            ->setStatusCode(Response::HTTP_CREATED);
    }

    /**
     * Display a project
     */
    public function show(Project $project): ProjectResource
    {
        return new ProjectResource(
            $project->load(['creator:id,name', 'team:id,name', 'tasks'])
        );
    }

    /**
     * Update a project
     */
    public function update(UpdateProjectRequest $request, Project $project): ProjectResource
    {
        $project->update($request->validated());

        return new ProjectResource($project->fresh(['creator', 'team']));
    }

    /**
     * Delete a project
     */
    public function destroy(Project $project): Response
    {
        $project->delete();

        return response()->noContent();
    }
}

Incremental Endpoint Addition

When adding endpoints to existing resources, provide context about what exists:

Add these endpoints to the existing ProjectController:

POST   /api/v1/projects/{project}/archive (change status to archived)
POST   /api/v1/projects/{project}/duplicate (clone project with tasks)

The controller already has standard CRUD. Add these as additional actions.
Archive should validate the current status allows archiving.
Duplicate should copy all project data and tasks, resetting statuses to draft.

Claude generates only the new methods, maintaining consistency with existing code.

API Documentation Generation

After creating endpoints, ask Claude to generate API documentation:

Generate OpenAPI/Scribe annotations for the ProjectController methods.
Include example requests and responses based on the actual validation rules
and resource structure.

This creates documentation that stays synchronized with your actual implementation.

Workflow: Refactoring Legacy Laravel Code

Refactoring legacy code requires the most careful approach. I have written extensively about this in my guide to Claude Code for legacy codebases, but here are Laravel-specific patterns.

The Safe Refactoring Sequence

Always follow this sequence:

1. First, read app/Services/LegacyReportGenerator.php and explain what it does.
   Do not suggest any changes yet.

2. Now identify the responsibilities this class has. List them.

3. Generate characterization tests that document current behavior.
   Use existing test data if available.

4. After I verify the tests pass, suggest a refactoring plan.
   Keep changes incremental and reversible.

This sequence prevents Claude from making changes it cannot verify and creates safety nets at each step.

Controller to Service Extraction

A common legacy pattern is fat controllers. Ask Claude to extract service classes:

The InvoiceController@store method has 150 lines handling:
- Validation
- Invoice creation
- Line item calculations
- Tax calculations
- PDF generation
- Email sending
- Audit logging

Extract the business logic into appropriate service classes while keeping
the controller as a thin HTTP layer. Maintain backward compatibility
with existing tests.

Claude proposes a structure and generates incremental changes:

I'll extract this into focused services:

1. InvoiceCalculationService - line items, taxes, totals
2. InvoiceDocumentService - PDF generation
3. InvoiceNotificationService - email sending
4. AuditService - logging (may already exist?)

Let me generate these one at a time. After each, we'll verify tests pass
before proceeding.

Starting with InvoiceCalculationService...

Upgrading Laravel Versions

When upgrading Laravel versions, Claude can identify required changes:

We're upgrading from Laravel 9 to Laravel 11. Read the following files and
identify required changes:

- app/Http/Kernel.php
- app/Providers/RouteServiceProvider.php
- config/app.php
- All files in app/Rules/

Focus on breaking changes and deprecations. Do not make changes yet.

Claude audits the files and provides a migration checklist specific to your codebase.

Best Practices for Prompting Claude Code in Laravel

Be Specific About Laravel Conventions

Generic prompts produce generic code. Laravel-specific prompts produce idiomatic Laravel:

// Generic (produces inconsistent results)
"Create a class to handle user registration"

// Laravel-specific (produces idiomatic code)
"Create a Laravel Form Request for user registration with validation rules.
Use Laravel 11 conventions: invokable rules, typed properties, authorize method."

Reference Existing Code

Always point Claude to existing patterns:

"Create a new ProjectPolicy following the pattern in app/Policies/InvoicePolicy.php.
Use the same authorization checks and team membership verification."

Specify Error Handling Expectations

Laravel has specific error handling patterns:

"Handle validation failures with Laravel's ValidationException.
Use abort_if/abort_unless for authorization.
Throw custom exceptions for business rule violations that should return 422."

Request Code Reviews

After generating code, ask Claude to review it:

"Review the ProjectController I just created. Check for:
- N+1 query issues
- Missing authorization checks
- Validation gaps
- PSR-12 compliance
- Laravel best practices"

When to Trust the AI vs When to Verify Manually

After extensive use, I have developed clear guidelines for when Claude Code output can be trusted and when it requires careful verification.

Trust Claude For

Boilerplate generation: Migrations, models, resources, form requests
Test structure: Setting up test classes, arrange/act/assert patterns
Code explanations: Understanding existing code, documenting logic
Syntax and Laravel API usage: It knows Laravel's API thoroughly
Refactoring patterns: Extracting methods, organizing code

Always Verify

Authorization logic: Claude may miss edge cases in permission checks
Financial calculations: Any money handling needs manual verification
Data integrity constraints: Foreign keys, cascades, unique constraints
Security-sensitive code: Authentication, encryption, sensitive data handling
Complex query correctness: Run queries against real data to verify results
Business rule implementation: Claude does not know your domain

Red Flags to Watch For

Claude suggests removing code without understanding why it exists
Generated tests only cover happy paths
Overly complex solutions for simple problems
Suggestions to upgrade dependencies without migration path
Catch-all exception handling that hides errors

Key Takeaways

Claude Code transforms Laravel development when used with intentional workflows:

Set up Laravel Boost for deep application context that goes beyond static analysis
Craft a project-specific CLAUDE.md that documents your conventions, constraints, and patterns
Provide complete context in prompts---business requirements, existing patterns, constraints
Generate tests alongside features to create safety nets for future changes
Use Claude for query debugging by providing full relationship context
Follow the safe refactoring sequence: understand, test, then modify
Trust but verify: Claude excels at boilerplate but needs human oversight for business logic

The developers getting the most from Claude Code in Laravel projects treat it as a highly capable pair programmer who knows Laravel deeply but needs explicit context about your specific application. Provide that context consistently, and Claude becomes a force multiplier for your Laravel development.

Related Reading:

External Resources:

Laravel AI Assisted Development - Official Laravel Documentation
Laravel Boost Documentation - GitHub Repository
Claude Code Best Practices - Anthropic Engineering
10 Claude Code Tips for Laravel Developers - Jonathon Ringeisen