Laravel 12 + React + Inertia の開発を劇的に改善する Cursor Rules

はじめに

Laravel 12 + React + Inertia で開発していると、Cursor がとんでもないコードを生成してしまうことがありませんか？

特に、複数の技術スタック（Laravel + React + Inertia）が組み合わさったプロジェクトでは、AIが何のプロジェクトなのか理解できずに迷走 してしまいがちです。

よく遭遇する問題

Laravel 12 + React + Inertia のプロジェクトで Cursor を使っていて、こんな困った経験はありませんか？

Next.js と勘違いしている

React コンポーネント（.tsx ファイル）を触っていると、Cursor が勝手に Next.js プロジェクトだと勘違いして、以下のようなコードを生成してくることがあります。

• pages/api/ ディレクトリを作ろうとする
• Next.js の router.push() を使ったコードを生成する
• _app.tsx や _document.tsx の作成を提案してくる

いや、これ Laravel の Inertia プロジェクト なんですけど... 😅

古い Laravel の構造で提案してくる

Laravel についても、あたらしい構造を理解していないようです。

• routes/api.php を作成しようとする
• app/Http/Kernel.php にミドルウェアを登録しようとする（Laravel 11以降は bootstrap/app.php）
• 不要な新しいサービスプロバイダーを作成しようとする

最新の Laravel 構造を理解していない みたいですね...

Inertia の機能を無視する

Inertia の機能もスルーされがちです。

• 内部リンクに <a> タグを使おうとする（Inertia の <Link> を使うべき）
• axios で API 呼び出しをしようとする（Inertia のフォーム機能を使うべき）
• React Router を導入しようとする（Laravel のルーティングを使うべき）

「Inertia って何？」 状態です。

Cursor Rules を使って解決

Cursor Rules を使うことで、プロジェクトの特性を明確に AI に伝えることができます。

https://docs.cursor.com/context/rules

Cursor Rules を作成

Cursor Rules は以下の手順で作成します。

1. プロジェクトルートに .cursor ディレクトリを作成
2. その中に rules ディレクトリを作成
3. laravel-inertia.mdc ファイルを作成

.cursor/
└── rules/
    └── laravel-inertia.mdc

ファイルを作成後、以下の内容をコピー＆ペーストしてください。

.cursor/rules/laravel-inertia.mdc

---
description:
globs:
alwaysApply: true
---
## PHP/Laravel
- PHP 8.2 以降の機能を使用し、古いまたは非推奨のPHP機能は使用しないこと。
- Laravel に標準で備わっている機能やヘルパーを可能な限り使用すること。
- ファイル構成は Laravel 12.x 以降のディレクトリ構造と命名規則に従うこと。
- 新しいファイルを追加する前にディレクトリを確認し、既存のファイルや機能の重複を避けること。
- 適切なエラーハンドリングとログ出力を実装すること。
    - Laravel の例外処理・ログ出力機能を活用する。
    - 想定される例外には try-catch を使用する。
- フォームやリクエストのバリデーションには Laravel のバリデーション機能を使用する。
- リクエストのフィルタリングや加工にはミドルウェアを利用する。
- データベースとのやり取りには Laravel の Eloquent ORM を使用する。
- 複雑なクエリには Laravel のクエリビルダを活用する。
- 適切なマイグレーション・シーダーを実装する。
- CSRF対策とセキュリティ対策を適切に行うこと。

## Laravel サービスプロバイダー
- `AppServiceProvider` 以外のサービスプロバイダーは原則作成しないこと。それでも必要な場合は、`config/app.php` ではなく `bootstrap/providers.php` に登録すること。

## Laravel コンソールスケジューラ
- スケジュールされたコマンドは `app/Console/Kernel.php` ではなく `routes/console.php` に記述する。Laravel 12 では `Kernel.php` は存在しない。

## Laravel ミドルウェア
- ミドルウェアは `app/Http/Kernel.php` ではなく `bootstrap/app.php` に登録する。

## Laravel ルーティングと `web.php`
- Laravel 12 では `routes` ディレクトリに標準で `web.php` と `console.php` が搭載されている。API 機能はオプション扱いとなっているため、必要な場合のみ `routes/api.php` を生成して有効にすること。
- InertiaベースのUI（クッキー、セッション、CSRF保護を使うもの）はすべて `web.php` に配置する。
- TypeScript/JavaScript/React ディレクトリ内にルーティングを定義しないこと。

## Laravel + React + Inertia
- Laravel バックエンドと React/Inertia フロントエンドの接続を意識して実装すること。
- React ページでは Bootstrap ではなく Tailwind を使用すること。
- Inertia フォームロジックを render 関数の中に直接書かない。
- API 呼び出し、Inertia アクション、副作用はカスタムフックやユーティリティに分離する。
- データ取得は `useEffect` よりも Laravel コントローラー + `Inertia::render()` を優先する。ただし、WebSocket、ライブ更新、頻繁なポーリングなどの場合は `useEffect` を使用可。
- React によるルーティングは避け、Laravel 側で定義し Inertia 経由で渡すこと。
- フォーム状態管理には `@inertiajs/react` の `useForm()` を使う。
- コンポーネント内で axios/fetch を使わず、非Inertia系処理に限定する。
- 内部リンクには `<a>` ではなく `<Link>`（@inertiajs/react）を使うこと。
- Inertia 経由でフロントに渡すデータに機密情報を含めないよう注意。
- コンポーネントやフックは `.ts` ではなく `.tsx` で作成すること。

## コードベース構造
- Laravel Controller: `/app/Http/Controllers/*`
- Laravel Middleware: `/app/Http/Middleware/*`
- Laravel Model: `/app/Models/*`
- Laravel Policy: `/app/Policies/*`
- Laravel AppServiceProvider: `/app/Providers/AppServiceProvider.php`
- Laravel Database Migration: `/database/migrations/*`
- React 関連（Hooks、lib、レイアウト、ページ、コンポーネント等）
    - `/resources/js/*` | `/resources/js/components/*` | `/resources/js/pages/*` | `/resources/js/layouts/*` | `/resources/js/hooks/*`
- TypeScript 型定義: `/resources/js/types/*`
- ルート定義: `/routes/*`
- `/resources/js/` 配下にルーティングは存在しない。ルーティングは Laravel アプリケーションとして `/routes/*` に存在する。

Cursor Rules を適用

ファイル作成後、Cursor を再起動してください。

設定反映の確認

正しく設定されていれば、Cursor がプロジェクトについて以下のように理解するようになります。

• ✅ Next.js ではなく Laravel + Inertia プロジェクトとして認識
• ✅ Laravel 12 の最新構造に基づいたコード生成
• ✅ Inertia の機能を考慮したコード提案

まとめ

Laravel 12 + React + Inertia のような複数の技術スタックが組み合わさったプロジェクトでは、AIが思った通りにコードを生成してくれないことが多いです。

しかし、適切なプロジェクトルールを設定することで、このような効果が期待できます。

• ✅ Next.js と勘違いすることなく、Laravel + Inertia プロジェクトとして認識される
• ✅ Laravel 12 の最新構造に従ったコードが生成される
• ✅ Inertia 機能を適切に活用したコードが提案される

みなさんも自分のプロジェクトに合わせたルールを作成して、楽しく開発しましょう！✨

プロジェクトルールは定期的に見直し、新しい機能や変更に合わせて更新することをお勧めします。特に Laravel のメジャーアップデート時は要チェック！

参考

https://josephchancey.medium.com/my-laravel-12-project-rule-to-stop-hallucinations-in-cursor-inertia-react-72af36e252a0