Most CLAUDE.md files we see fall into one of two failure modes. Some are nearly empty. Claude starts every session knowing nothing about the project. Others are a sprawling wall of text, so long that half the rules in it get ignored anyway. Getting a CLAUDE.md Laravel codebase setup right sits between those two extremes. It matters more on multi-tenant projects than almost anywhere else.
This is the fifth piece in our series on how our team actually works day to day with Claude Code. Multi-tenancy raises the stakes for this file specifically. A single missed rule about tenant isolation doesn’t just produce ugly code. It can produce a security bug, and security bugs in a shared-tenant system tend to affect more than one customer at once. Here’s exactly how we structure ours, and why.
What a CLAUDE.md File Actually Does
CLAUDE.md is a plain markdown file. Claude Code reads it automatically at the start of every session. Think of it as an onboarding document for a new hire who’s brilliant but knows nothing about your specific project yet. Without it, Claude can still write correct code. It just won’t know your naming conventions, your deployment pipeline, or which legacy table nobody’s allowed to touch anymore.
The file has a real cost, though. Every line in it consumes context tokens on every single session, whether that content ends up relevant to the current task or not. That’s why the common advice among teams using this well is to keep a project’s core CLAUDE.md under roughly 200 lines. Treat every line as something that has to earn its place. If removing a line wouldn’t cause a mistake, it probably shouldn’t be there in the first place.
Why Multi-Tenant Laravel Needs a Different Structure
A typical single-tenant Laravel CLAUDE.md can get away with being fairly general. Stack, conventions, commands, done. Multi-tenancy changes that calculus. The single most expensive mistake Claude can make on this kind of project isn’t a style violation. It’s writing a query that leaks data across tenant boundaries.
That means tenant-isolation rules can’t just be one line buried in a longer list. They need to sit near the top of the file, stated plainly, in language that leaves no room for a reasonable-sounding shortcut. We’ve found that vague phrasing invites exactly the kind of “this edge case seems fine” reasoning. That reasoning causes real problems later, usually discovered by a customer instead of a code reviewer.
The Sections We Actually Include in a CLAUDE.md Laravel Setup
Here’s roughly how our core CLAUDE.md is organized for a multi-tenant Laravel project. This isn’t a universal template to copy exactly. It’s a starting shape worth adapting to a specific project’s own risks.
# [Project Name] — Multi-Tenant Laravel Application
## Overview
Multi-tenant SaaS platform. Tenants are isolated by [tenant_id column /
separate schema — state which one]. Laravel 11, PHP 8.3, MySQL, Redis queues.
## Tenant Isolation Rules — READ FIRST
- YOU MUST scope every Eloquent query through the tenant-aware global scope.
Never query a tenant-scoped model without it, including in seeders,
console commands, and queued jobs.
- YOU MUST NOT use `withoutGlobalScope()` on tenant-scoped models unless
explicitly instructed for a specific admin-only context.
- New migrations touching tenant data require a `tenant_id` foreign key
and a corresponding index. No exceptions.
## Stack and Conventions
- Laravel 11, PHP 8.3, Livewire for [specific modules], React for [others]
- Form Requests for all validation, never inline in controllers
- Repository pattern for [specific domains], direct Eloquent elsewhere
## Commands
- Tests: `php artisan test --parallel`
- Tenant-aware seeder: `php artisan tenants:seed`
- Local multi-tenant setup: see `@docs/local-tenant-setup.md`
## Do Not Touch
- `app/Legacy/BillingBridge.php` — undocumented dependency on a
third-party invoicing system. Ask before modifying.
## Deeper Context
- Full tenant architecture: `@docs/architecture/multi-tenancy.md`
- API conventions: `@docs/api-conventions.md`
That structure keeps the highest-stakes rule, tenant isolation, impossible to miss at the top. Everything else follows a predictable order. Stack, conventions, commands, hazards, then pointers to deeper documentation instead of the documentation itself, spelled out in full.
Progressive Disclosure: What We Push Out of the Core File
The @docs/... references in that example aren’t decorative. Claude Code supports importing other files directly with an @path/to/file syntax. Those imports can nest several levels deep. That’s the mechanism that keeps the core file lean. Detailed architecture explanations, a full API reference, or a step-by-step local environment setup guide don’t need to load into every single session. They only need to load when a task actually touches that specific area of the codebase.
We treat the core CLAUDE.md the way you’d treat working memory rather than long-term storage. Anything situational gets pushed into a file that loads on demand instead of sitting in the always-loaded core. There’s a simple test for whether something belongs in the top-level file. Would nearly every task on this project need to know this? If the answer is no, it probably belongs one level deeper, referenced rather than repeated.
We also keep a CLAUDE.local.md file, gitignored, for anything specific to one engineer’s personal setup rather than a shared team convention. A local port number or a personal editor preference doesn’t belong in a file every teammate inherits automatically.
Common Mistakes We See
The over-stuffed file is the most common failure. A memory file with 600 lines of instructions doesn’t make Claude follow 600 rules more carefully. It makes Claude effectively ignore a good portion of them, because attention across a long context has limits like anything else does. Pruning ruthlessly beats padding generously, every single time we’ve tested it.
The second mistake is vague phrasing on the rules that matter most. “Be careful with tenant data” is not a rule. “Every tenant-scoped Eloquent query must pass through the tenant global scope, with no exceptions in seeders or queued jobs” is a rule. The gap between those two sentences is the gap between a guideline that gets interpreted loosely and one that doesn’t leave room for interpretation at all.
The third mistake is letting the file go stale. A CLAUDE.md written during a project’s first month, and never touched again, drifts further from reality every sprint after that. We treat updating it as part of any pull request that changes a convention it describes, the same way we’d update a README when an endpoint changes.
How We Know a CLAUDE.md Is Actually Working
We don’t just write this file once and assume it’s doing its job. A good signal that a multi-tenant CLAUDE.md is working well is the kind of question that stops coming up in code review. Early on a project, a reviewer might catch a query missing its tenant scope every few pull requests. Once the file’s isolation rules are specific enough, that category of mistake mostly disappears, because the rule was clear enough the first time Claude read it.
When that mistake does resurface, it’s usually a sign the rule needs rewording rather than repeating. If a specific phrasing keeps getting misread the same way twice, we treat that as a bug in the file itself, not a one-off slip to just correct manually again. Getting a CLAUDE.md Laravel codebase setup to that point usually takes a few weeks of small adjustments, not a single perfect first draft.
How This Fits Into Our Broader Workflow
This file sits right at the start of the Plan stage we described in the first article of this series. A well-structured CLAUDE.md is a big part of why that planning stage catches edge cases early, rather than after a feature ships to real tenants. It’s also part of why our software development services can onboard into an unfamiliar client codebase quickly on outsourcing engagements. Every engineer doesn’t need to relearn the same tenant-isolation rules from scratch through trial and error.
If you’re curious what this looks like applied to a real production codebase, our portfolio includes multi-tenant SaaS and admin-panel work built on exactly this kind of Laravel foundation. You can also read more about how our team operates day to day before deciding whether this approach fits your own project.
The Honest Takeaway
A CLAUDE.md Laravel codebase setup isn’t a one-time task you finish and forget about. It’s a living document that earns its keep by staying short, specific, and honest about what actually matters on that particular project. On a multi-tenant system, getting the isolation rules right at the top of that file matters most. It’s worth more than almost any other single change you can make to how Claude works inside your codebase.
If you’re building a multi-tenant platform and want a second opinion on your architecture before problems show up in production, request a free quote. We’ll walk through it with you directly, including how our own CLAUDE.md Laravel setup would apply to your specific tenant model.