claude-code-laravel-starter — Laravel Documentation Template

SHA-256: f00227c49961a6720711f1a7fa2d9ef04d071d26bcec5ca4151af4a6c27b63a3

2026-10-03T15:22:09.436Z

# claude-code-laravel-starter

A small, opinionated documentation skeleton for Laravel projects driven with
[Claude Code](https://www.anthropic.com/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](https://albertoarena.it/posts/claude-md-is-ram-not-disk/):
  the original two-tier model.
- [CLAUDE.md Is RAM, Skills Are Not Disk](https://albertoarena.it/posts/claude-md-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 →](https://albertoarena.it/subscribe/?utm_source=github&utm_medium=readme&utm_campaign=newsletter&utm_content=claude-code-laravel-starter)**

## License

MIT.