#claude-code-laravel-starter

A small, opinionated documentation skeleton for Laravel projects driven with Claude Code.

The idea in one line: CLAUDE.md is RAM, .claude/rules/ is demand-paged RAM, skills are installed programs, and docs/ is disk. CLAUDE.md is loaded on every turn, so it stays lean. Rules load only for the files they're scoped to. Skills load only when invoked, then stay resident for the rest of the session. Everything else lives in docs/ and loads only when something points to it.

#Structure

claude-code-laravel-starter/
├── CLAUDE.md                    # the lean anchor, auto-loaded every session
├── README.md                    # this file (for humans, not Claude)
├── .claude/
│   ├── rules/
│   │   └── domain.md            # path-scoped: app/Domains/**/*.php only
│   └── skills/
│       └── README.md            # where project skills get installed
├── docs/
│   ├── DESIGN.md                 # domain model, aggregates, events
│   ├── PLAN.md                   # phased, plan-first implementation
│   └── DECISIONS.md              # lightweight ADR log
└── app/
    └── Domains/                  # your domain layer; see .claude/rules/domain.md
        └── .gitkeep

#How to use it

1. Start from a fresh Laravel app, then copy these files into its root. laravel new / composer create-project need an empty directory, so install Laravel first and overlay the skeleton, not the other way round. The domain lives in app/Domains (namespace App\Domains\...), so it autoloads with no composer.json changes.
2. Fill in CLAUDE.md with your real stack, versions and commands.
3. Replace the example aggregate in docs/DESIGN.md with your own domain.
4. Adjust the glob in .claude/rules/domain.md if your domain layer doesn't live at app/Domains.
5. Keep CLAUDE.md tight. When you catch yourself adding detail Claude needs only occasionally, ask whether it's scoped to some files (.claude/rules/), a procedure (.claude/skills/), or neither (docs/).

#Why not just one big CLAUDE.md?

Because every line of it stays resident in your context for the whole session, and a 300-line file makes the session worse, not better. Splitting it by how certainly and how often each piece of content is needed, not just into two piles, is the full idea behind this repo. It's covered across two posts:

• CLAUDE.md Is RAM, Not Disk: the original two-tier model.
• CLAUDE.md Is RAM, Skills Are Not Disk: why skills needed their own tier, and the correction to the nested CLAUDE.md trick from the first post.

#The four rules

1. If Claude needs it every time, it goes in CLAUDE.md. If it only applies to files matching a pattern, it goes in .claude/rules/. If it's a procedure, it goes in a skill. Otherwise, it goes in docs/.
2. Start small (CLAUDE.md, DESIGN.md, PLAN.md). Add a rule, a skill, or a doc only when a real need shows up.
3. A .claude/rules/*.md file with a paths: glob beats a nested CLAUDE.md: same on-demand loading, scoped by pattern instead of by folder, reviewable in one place.
4. A skill is not disk. It's executable and probabilistic to trigger, so invariants stay out of it; procedures are what belong there.

#📬 Stay updated

Occasional emails on Claude Code and AI-assisted Laravel development: new releases, packages, and write-ups. No spam, unsubscribe anytime.

Subscribe to the newsletter →

#License

MIT.