AI in the Laravel Development Workflow

Reading Time: 6 minutes

Series: Every Laravel Project Should Have These Building Blocks 
Part: 26 of 35 Level: Intermediate Prerequisites: None

---

What You’ll Learn

• How to structure your codebase so AI coding tools actually help
• What CLAUDE.md / .cursorrules / .windsurfrules are and why they matter
• The .ai/ skill directory pattern for project-specific instructions
• Laravel Boost — the MCP server built specifically for Laravel
• How these tools combine to give AI consistent, accurate, project-aware assistance

---

The Problem: AI That Doesn’t Know Your Project

By default, AI coding assistants know Laravel as of their training cutoff. They don’t know:

• Which packages and versions you’re using
• Your architectural decisions (do you use Actions, or Services only?)
• Your naming conventions
• Your folder structure
• Whether you use Pest or PHPUnit
• The actual current documentation for your specific versions

Every time you start a new session, you re-explain all of this. The AI gives generic answers, suggests patterns that don’t match your codebase, and confidently uses features from the wrong package version.

The solution: encode your project’s context into files that AI tools read automatically.

---

CLAUDE.md and Equivalent Files

Claude reads CLAUDE.md files automatically when they exist in the project root or in any directory it’s working in. Cursor reads .cursorrules. Windsurf reads .windsurfrules. GitHub Copilot uses .github/copilot-instructions.md.

The concept is the same across all tools: a file that tells the AI how your project works before it touches any code.

A minimal CLAUDE.md:

# Project: dp-sampling

## Stack
- PHP 8.4, Laravel 11
- Pest v3 for tests
- Inertia.js v3 + Vue 3 frontend
- Tailwind CSS v3

## Architecture
- Thin controllers: validate → authorize → delegate → respond
- Actions in `app/Actions/` for atomic operations (single `handle()` method)
- Services in `app/Services/` for multi-model business logic
- DTOs in `app/DTOs/` as `final readonly` classes

## Conventions
- All migrations: no `down()` method
- All PHP files: `declare(strict_types=1);` at the top
- API responses: `{"success": bool, "message": string, "data": {}}`
- Never return raw Eloquent models from APIs — always use Resources
- Array notation for validation rules, never pipe-delimited strings

## Testing
- Use Pest syntax (`it()`, `test()`, `expect()`)
- Feature tests for HTTP endpoints
- Unit tests for Services and Actions
- Never seed the database manually — use factories

A 20-line file saves you 5 minutes of re-explaining context at the start of every session.

---

The .ai/ Skill Directory

The projects in this series use a more structured approach: a .ai/ directory containing multiple rule files, organized by concern.

.ai/
├── 00-forbidden.md       # Things the AI must never do
├── 01-coding-standards.md # Code style and conventions
├── 02-architecture.md     # Folder structure and class types
├── 03-database.md         # Migration and Eloquent rules
├── 04-testing.md          # Test conventions
├── 05-security.md         # Security requirements
├── 06-performance.md      # Performance guidelines
├── 07-javascript.md       # Frontend conventions
└── 08-version-control.md  # Git and commit conventions

Each file is small and focused. The AI loads all of them together, giving it a complete picture of your standards without any one file becoming unmanageably long.

Example from 00-forbidden.md:

## Forbidden

- Do not put business logic inside Controllers or Blade templates.
- Never commit debug code (`dd()`, `dump()`, `ray()`, `console.log()`).
- Do not use `env()` outside of configuration files.
- Do not write `down()` methods in migrations.
- Do not use `else` when early returns are sufficient.
- Do not return raw Eloquent models from APIs; use API Resources.
- Generate strictly typed PHP with `declare(strict_types=1);`.

This is different from documentation. Documentation explains what the code does. These files tell the AI what it must and must not do when modifying the code.

---

Skills — Domain-Specific Instructions

Some tasks need more than general project context. The skill pattern (as used by tools like Matt Pocock’s skills system) goes further: each skill is a self-contained instruction set for a specific domain or type of work.

In the projects here, skills are stored in .ai/skills/ (or surfaced via the Laravel Boost MCP):

.ai/skills/
├── laravel-best-practices.md
├── inertia-vue-development.md
├── tailwindcss-development.md
├── pest-testing.md
└── debug-using-debugbar.md

Each skill file typically includes:

• When to activate — trigger conditions (e.g., “Use whenever writing a Vue page component”)
• Reference documentation — links to version-specific docs
• Code examples — the right patterns for this project
• Anti-patterns — common mistakes to avoid

The Claude agent activates the relevant skill automatically when the task matches the trigger. This is the equivalent of handing a specialist their checklist before they start work.

---

Laravel Boost — The MCP Server for Laravel

Laravel Boost is an MCP (Model Context Protocol) server that gives Claude live access to your running application. Instead of asking “what does the database schema look like?”, it just looks.

Claude tools from Laravel Boost:
├── database-query    — Run SELECT queries against the real database
├── database-schema   — Inspect table structure, columns, indexes, foreign keys
├── search-docs       — Version-aware documentation search
├── get-absolute-url  — Resolve the correct URL for the running dev server
└── browser-logs      — Read browser errors and exceptions

The difference this makes is concrete. Without Boost:

• “Add an index to the users table” → AI has to ask what columns exist, then you paste the schema
• “Why is this query slow?” → AI guesses based on code
• “Which Inertia v3 API do I use for deferred props?” → AI might give you the v1 or v2 answer

With Boost:

• AI calls database-schema('users') and sees the actual columns, indexes, and foreign keys
• AI calls search-docs('deferred props') and gets documentation for the exact Inertia v3 version installed
• AI can propose a migration with the correct column types based on what actually exists

This is meaningful for Laravel development because Eloquent models, migrations, and query builders all depend on the schema. The AI giving schema-aware advice instead of guessing is the difference between a useful suggestion and a correction loop.

---

The search-docs Workflow

The most important discipline when using AI for Laravel work: always search documentation first, then write code.

Laravel changes between versions. Inertia v3 removed Inertia::lazy(). Laravel 11 removed Http/Kernel.php. Pest v3 changed some assertion syntax.

With Laravel Boost’s search-docs, the AI searches version-aware documentation before making changes:

Bad workflow (AI working from training data):
→ "Add rate limiting to this route"
→ AI writes code using `throttle:60,1` syntax from Laravel 8
→ You have to explain that you're on Laravel 11 with named rate limiters

Good workflow (with Boost):
→ "Add rate limiting to this route"
→ AI calls search-docs(['rate limiting', 'throttle middleware'])
→ Gets the correct Laravel 11 documentation
→ Writes code using the `RateLimiter` facade in `AppServiceProvider::boot()`

The search query approach matters too. Good queries are topic-based, not feature-description-based:

• ['deferred props', 'lazy loading inertia'] — good: multiple angles
• ['how to load data lazily in inertia vue'] — less useful: too natural language

---

Putting It All Together

Here’s what the complete AI-assisted workflow looks like in a project with all these pieces in place:

1. Developer opens Claude in Cowork / Claude Code
2. Claude automatically reads CLAUDE.md — knows the stack, conventions, and architecture
3. Developer asks: “Add rate limiting to the API”
4. Claude activates laravel-best-practices skill (triggered by “Laravel” + “API”)
5. Claude calls search-docs(['rate limiting', 'api middleware']) via Laravel Boost
6. Gets version-specific docs for Laravel 13
7. Calls database-schema to check if there’s a relevant model or table involved
8. Writes the correct code: RateLimiter::for() in AppServiceProvider, ->middleware('throttle:api') on routes
9. Runs Pint to format
10. Runs the affected tests

At no point did the developer explain the stack, paste documentation, or correct a version mismatch.

---

Setting This Up in Your Project

Step 1: Create CLAUDE.md in your project root. Start simple — stack, conventions, forbidden patterns.

Step 2: Create .ai/ directory with the forbidden rules and coding standards. Copy the format from this series (the .ai/ files are in each project’s CLAUDE.md context).

Step 3: Install Laravel Boost. It’s a composer package that exposes an MCP server:

composer require laravel/boost --dev

Then configure it in your MCP-compatible editor.

Step 4: For skill directories, create .ai/skills/ and write instruction files for the domains your project works in most: Laravel backend, frontend framework, testing, deployments.

---

Key Takeaways

• CLAUDE.md / .cursorrules give AI tools automatic project context — stack, conventions, forbidden patterns — so you stop re-explaining at the start of every session.
• The .ai/ directory structures these instructions by concern, keeping each file focused and readable.
• Skills are domain-specific instruction sets that activate automatically for the right tasks — more targeted than general project rules.
• Laravel Boost’s MCP tools (database-schema, search-docs, database-query) give AI live access to your running app and version-specific documentation.
• The best AI coding workflow: read context → search docs → inspect schema → write code → test. This is what these tools make automatic.

---

Tips and Gotchas

⚠️ Warning: AI coding tools generate plausible-looking but incorrect code. A CLAUDE.md that lists your actual package versions, file naming conventions, and forbidden patterns dramatically reduces hallucinations. The more specific your constraints, the more accurate the output.

💡 Tip: The .ai/00-forbidden.md file is the highest-value investment in AI-assisted development. List patterns that look legitimate but are wrong for your project: “don’t use Eloquent models in API responses”, “don’t call env() outside config files”. These are the exact mistakes AI tools make without explicit instruction.

🔥 Expert Note: Treat CLAUDE.md as living documentation. Update it when you introduce a new pattern, add a new package, or discover a mistake the AI keeps making. A stale CLAUDE.md is worse than none — it confidently steers AI tools toward outdated patterns.

Further Reading

• Anthropic: Claude Docs
• Laravel Boost — Laravel’s official MCP server
• Model Context Protocol — the standard Claude uses to connect to tools

---

← Larastan, Rector, Pint | Next: Request Logger →