leek/laravel-agent-rules

Directory-scoped agent rules for Laravel projects. Each CLAUDE.md lives next to the code it governs and mirrors the laravel/laravel skeleton. The root rules direct agents to shared conventions and any guidance outside the edited file's directory.
Requirements
- **Laravel 12 or 13** (bootstrap withMiddleware / withExceptions, attribute model wiring, casts() method, schedule in routes/console.php). Laravel 12 requires PHP 8.2+; Laravel 13 requires PHP 8.3+. Version-specific examples are labeled; check the project's installed version before copying them. See Laravel release notes.
- **Pest** for new tests (tests/CLAUDE.md). PHPUnit-style assertions still work under Pest.
- **Optional package dirs** — install rules only matter when the package is present:
- app/Livewire/ — Livewire 4
- app/Features/ — laravel/pennant (skip banner in file)
- app/States/ — spatie/laravel-model-states (skip banner in file)
- Companion rulesets (not in this repo): Filament → filament-agent-rules.
Install
Use apply-agent-rules to drop the rules into a Laravel project:
Supported agents: claude, codex, gemini, cursor, windsurf, cline.
How install works
Every CLAUDE.md in this repo is the canonical source. The installer walks the tree and, for each CLAUDE.md it finds, writes one file per selected agent into the **same directory** under that agent's expected filename:
| Agent | Filename written |
| --------- | ------------------------- |
| claude | CLAUDE.md |
| codex | AGENTS.md |
| gemini | GEMINI.md |
| cursor | .cursorrules |
| windsurf| .windsurfrules |
| cline | .clinerules |
So picking --agents claude,codex against this repo produces, for example:
Subdirectory rules ship as separate files, not concatenated into the root. The root rule file instructs agents to read the cross-cutting app/ rules for every project directory, and resolves canonical CLAUDE.md references to the selected agent's filename. The installer copies content unchanged; it does not rewrite references.
Claude, Codex, and Gemini support hierarchical context files, subject to their context-loading settings. Do not assume every supported output filename has the same discovery behavior. The installer currently emits legacy .cursorrules, .windsurfrules, and .clinerules files rather than native glob-scoped rules. Verify the root loader is active and explicitly reads the relevant nested files. For automatic scoping, configure native rules using Cursor project rules, Windsurf rules or AGENTS.md, or Cline conditional rules. Merely writing a legacy rule file into each subdirectory does not guarantee it is loaded.
Laravel's optional directories need setup independently of installing agent rules: php artisan install:api creates API routing, php artisan install:broadcasting configures broadcasting, and php artisan lang:publish publishes language files. Install only the features the project needs.
What you get
| Path | Covers |
| --------------------------------- | --------------------------------------------------------- |
| app/CLAUDE.md | Cross-cutting naming, code style (one-thing methods, no DocBlocks, short syntax, standard tools, prefer final), IoC/DI, constants & i18n, security bullets, domain sub-namespacing, class-type → directory index |
| app/Models/ | Eloquent: casts, relationships, scopes, eager loading, transactions |
| app/Models/Scopes/ / app/Models/Builders/ | Global scope classes and custom Eloquent builders |
| app/Queries/ | Reusable query objects |
| bootstrap/ | Routing, middleware, exception hooks, and provider registration |