How we work with Claude Code on a Laravel project

The three files that decide whether Claude Code helps or gets in the way: CLAUDE.md, permissions in settings.json and a subagent that reviews before you commit.

JZ Jorge Zamarrón 10 Nov 2026 5 min read
How we work with Claude Code on a Laravel project

The site you are reading runs on Laravel 11 with Filament and Tailwind, and much of this year's work on it was done with Claude Code in the terminal: the service, industry and city pages, the English versions, llms.txt and the schema. Here is how I set it up, because whether Claude Code helps or gets in the way comes down almost entirely to three files.

1. CLAUDE.md: what a new developer would need to know

Claude Code reads the CLAUDE.md file at the project root at the start of every session. I write it like the welcome note for someone joining the team on Monday: how to run the project, where everything lives and what not to touch.

# Zygnus site

## Running it
- `php artisan serve --port=8088`
- Assets: `npx vite build` (local; the server does not compile)
- Tests: `php artisan test`

## Where content lives
- Service, industry and city pages: resources/content/landings.php (ES)
  and landings.en.php (EN), same keys.
- Portfolio and blog: database (Filament at /admin).
- Interface copy: lang/es and lang/en.

## Rules
- Do not invent figures, clients or testimonials. If data is missing, ask.
- Every new page ships in Spanish and English.
- Do not edit .env or anything under storage/.
- Cities only get their own page if there is an office or a real case.

The rule about not inventing figures looks obvious. I added it because a model writing sales copy tends to fill gaps with round numbers that sound good, and on a site that sells trust that is the last thing you want.

2. Permissions in .claude/settings.json

The second file defines what Claude Code can do without asking. It is worth keeping it in the repository so the whole team works with the same rules. An example for Laravel:

{
  "permissions": {
    "allow": [
      "Bash(php artisan test:*)",
      "Bash(php artisan route:list:*)",
      "Bash(npx vite build)",
      "Bash(git status)",
      "Bash(git diff:*)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Bash(rsync:*)",
      "Bash(php artisan migrate:fresh:*)"
    ]
  }
}

What goes in allow are commands I run twenty times a day that break nothing. What goes in deny is what I never want to happen from a Claude session: reading credentials, deploying or wiping the database. I do the deploys myself, on purpose.

3. A subagent to review before committing

Subagents live in .claude/agents/. Each one has its own context, tools and instructions, so they do not clutter the main conversation. Here is a reviewer for Blade views and controllers that you can copy and adjust:

---
name: laravel-reviewer
description: Reviews changes to controllers, routes and Blade views before a commit. Use it when you finish an edit.
tools: Read, Grep, Glob, Bash
---
Review the current diff (git diff) and look for:
- New routes without a name or without their version in the other language.
- Copy written directly in Blade that should live in lang/.
- Queries inside an @foreach (N+1).
- Unescaped {!! !!} output that comes from user input.
Report file and line. Do not edit anything.

That last line matters. A reviewer that also fixes things becomes another author, and then nobody reviewed anything.

What a normal session looks like

I start by asking for a plan before any edit, especially when the change touches several layers. For the bilingual pages, for example, the plan made it clear that content would live in one PHP file per language with the same keys, that a Landings class would load it and that English routes would 301-redirect if someone came in with the Spanish slug. Arguing about that in text saved me from undoing code.

Then I let it edit, run the tests and read the diff myself. Claude Code writes fast; responsibility for what reaches production is still mine, which is why deploying is not on its permission list.

What I always review myself

There are three things I do not delegate. The first is figures: the numbers on this site come from queries against the production databases, and when Claude Code proposes copy with a number in it, I check it against that query before accepting it. The second is public routes, because a slug that changes without a 301 redirect can lose Google rankings that took work to earn. The third is deploying, for the reason I gave above.

I also learned to ask for small changes. An instruction like "build the city pages" produces a lot of code at once and is hard to review carefully. "Add the Chihuahua page with these sections and do not touch the others" produces a diff I can read in full before accepting it.

If you already use Claude Code on a Laravel project, I would like to know what is in your CLAUDE.md that is not in mine. I always find a rule I was missing.

JZ

Written by

Jorge Zamarrón · Founder & CEO

Jorge Zamarrón founded Zygnus and has fifteen years of software and process consulting for companies. Jorge sits on the board of Alcis Corp, a holding of more than ten companies with combined sales above 12 billion pesos a year, and leads Innovation and Development at J. García López.

Newsletter

One email when we publish something new

No promotions. Just the articles.