How I Set Up Claude Code So It Writes My Laravel

Plausible Is Not the Same as Right

Ask an AI agent to add a feature to a Laravel app and you'll get code that works. It'll also look like it came from a tutorial written three versions ago. A scopePublished() method when your app uses the #[Scope] attribute. Inline $request->validate() when every other controller uses a Form Request. A magic string where you'd have used an enum.

None of that is wrong, exactly. It's just not your Laravel. And every time you fix it by hand, you're doing the part of the job the agent was supposed to save you.

It usually shows up on something small. I ask for a status filter on an admin table, and back comes a scopeActive() method, a where('status', 'published') with the string typed right there, and validation stuffed into the controller. It works. The tests pass. Then I spend the next twenty minutes rewriting it to match every other file in the project.

I spent a while trying to fix this with better prompts. It doesn't work. You can't type your whole architecture into a chat box every morning. What works is putting the context in the repository, where the agent reads it every time, and letting your tooling decide whether the result is good enough.

Here's how that looks on the codebase behind this site.

Three Layers of Instructions

I keep instructions in three places, from most personal to most specific.

My personal ~/.claude/CLAUDE.md. This file follows me into every project. It holds the conventions I'd enforce in any code review: PHP enums over magic strings, early returns instead of else, match over switch, Form Requests for validation, Pest for every test, #[ObservedBy] instead of registering observers in a service provider. It also holds my workflow, which I'll get to in a minute.

The repo's AGENTS.md. This is the project's rulebook, checked into git, so it applies to anyone (or anything) working on the code. Mine covers branch naming, the develop and main flow, Conventional Commits, and how releases work. Claude Code reads it, and so do other agents, which means I write the rules once.

## Git and pull requests

- Use `develop` as the integration branch for
  routine work. Create focused working branches
  from an up-to-date `develop`; do not commit
  feature work directly to `develop` or `main`.
- Squash merge reviewed working branches into
  `develop` through pull requests with required
  CI. Do not rebase-merge pull requests.

Path-scoped rules in .ai/rules. This is the layer that made the biggest difference. Instead of one giant file, each area of the app gets its own short rule file, and an index maps file paths to rules:

| Applies to              | Rule file                |
| ----------------------- | ------------------------ |
| app/Actions/**          | .ai/rules/actions.md     |
| app/Http/Controllers/** | .ai/rules/controllers.md |
| app/Models/**           | .ai/rules/models.md      |
| tests/**                | .ai/rules/tests.md       |

Before the agent touches a model, it reads the model rules. Before it touches a test, it reads the test rules. Each rule is a settled decision with a one-line reason, like this one from models.md:

## Keep HTTP concerns out of models
Keep Eloquent models focused on persistence
and domain behavior. Do not generate routes,
signed URLs, redirects, or other
HTTP/presentation output in models.

The trick is keeping these short. A rule file is not documentation. It's the stuff I'd otherwise leave as a review comment for the third time.

Laravel Boost Does the Heavy Lifting

Laravel Boost is the piece that makes an agent Laravel-aware out of the box. Run php artisan boost:install, pick your agents, and it does two things.

First, it writes Laravel's official guidelines into your agent instructions, matched to the packages you actually have installed. That's where rules like "run Pint on dirty files before finishing" and "use php artisan make: commands" come from.

Second, it runs an MCP server that gives the agent tools inside your app. The ones I lean on most:

• search-docs searches the Laravel ecosystem docs for the versions in your composer.lock. This is the big one. It stops the agent from confidently using an API from two major versions ago.
• database-schema lets it check columns, defaults, and nullability before writing a migration or a factory.
• get-absolute-url gives it the real local URL (Herd, in my case) instead of guessing localhost:8000.
• record-rule writes a new entry into .ai/rules when I tell it a decision is settled.

That last one matters more than it looks. When I catch the agent making the same mistake twice, I have it record a rule. The next session starts smarter, and so does the next person who clones the repo.

Plan First, Then Code

The workflow part of my CLAUDE.md is short, and it's the part I'd keep if I had to delete everything else:

1. Read the relevant code and write a plan to tasks/todo.md.
2. Check in with me before starting.
3. Work through the plan, checking items off and explaining each change.
4. Keep every change as small as possible.
5. Finish with a review section in the same file.

The check-in is the whole point. Reading a ten-line plan takes a minute. Reviewing a 400-line diff that went the wrong direction takes an afternoon, and then you throw it away. Most of my corrections happen at the plan stage now, before any code exists.

For bugs, the rule is stricter: don't start by fixing it. Write a Pest test that reproduces the bug, watch it fail, then fix it. I picked that habit up from Adam Wathan's TDD course years ago, and it turns out to be exactly the right leash for an agent. A failing test is a spec it can't argue with.

Let the Tooling Be the Judge

I don't want to review an agent's code for formatting, types, or style. I want a machine to do that, so my review can focus on whether the change is the right change.

This project has one command that runs every gate in the same order CI does:

composer check

Behind it: Pint for formatting, PHPStan for types, Rector for modernization, Pest for tests (including browser tests), filacheck for the Filament admin, dependency audits, and a production asset build. The agent runs the narrowest tests for what it changed while it works. CI runs everything on the pull request.

If the gates pass and the plan was approved, most of my review is reading for intent. Is this the change I asked for? Did it stay small? That's a much better use of my attention than counting blank lines.

Guardrails for the Stuff That Can Hurt

Agents are fast, which is great right up until they're fast at the wrong thing. So the dangerous operations have explicit rules:

• Feature work never lands directly on develop or main. It goes through a branch and a pull request with required CI.
• Every commit and PR title follows Conventional Commits, so the history stays readable no matter who wrote the code.
• Releases have their own documented process, and a merged PR never counts as permission to deploy to production. Production is a separate manual step that needs my explicit approval.

None of this is special to AI. It's the same process I'd want from any new teammate. The difference is that an agent will actually read the whole document on its first day.

What I Don't Hand Off

A few things stay with me:

Product decisions. The agent can list options. It doesn't know which tradeoff fits this site, so the instructions tell it to check with me when a structural decision is questionable instead of picking one.

Anything I can't verify. If it makes a claim about a package, I want to see the doc it came from. That's why search-docs matters so much.

My writing. Drafts, sure. But the voice has to be mine, which is why this repo now has a voice guide for public copy too.

And the tradeoff is real: this setup is work. The rules drift if you don't prune them, and a stale rule is worse than no rule because the agent follows it faithfully. I treat .ai/rules like code. When a decision changes, the rule changes in the same pull request.

Where to Start

You don't need all of this on day one. If I were starting over:

1. Install Laravel Boost and pick your agents.
2. Write the five conventions you correct most often into your CLAUDE.md.
3. Make "plan first, check in before coding" the first line of your workflow.
4. Add a single composer script that runs your quality gates, and tell the agent to run it.
5. Every time you leave the same review comment twice, turn it into a rule.

That last habit is how the rest of the setup grows. I'd love to hear what's in your rules files. Hit me up on social media and tell me the one rule you'd never give up.