laravel-11-12-app-guidelines

Laravel 11/12 アプリのガイドライン

リポジトリに実際にインストールされているものを基準に作業してください。Laravel 11 および 12 のアプリケーションは、スケルトン、フロントエンド、認証、コマンドランナーが大きく異なるため、プロジェクトで採用されていない新規アプリケーションのデフォルトを前提にすることが、ほとんどのミスの原因になります。

委任

デフォルトではメインの会話内で作業してください。委任によって利用量が増える場合があります。サブエージェントを使う前に、予定するエージェント数と作業範囲について明示的な承認を得てください。承認された範囲内ではその承認を再利用し、承認済みの数や範囲を拡大する前に、あらためて確認してください。

判断の前に確認する

リポジトリの指示と関連ドキュメントの管理者を確認し、composer.json、composer.lock、package.json、フロントエンドのロックファイル、bootstrap/app.php、Compose ファイル、config/ から、次の点を確認してください。

• コマンドの実行方法：ホストの PHP、Sail、Docker Compose、またはリポジトリのラッパーのいずれかを選び、一貫して使用します。
• API 専用かフルスタックか、およびフロントエンド：React、Vue、Svelte のいずれかを使う Inertia、Livewire、または Blade。
• 認証スタック（Fortify、Sanctum、Passport、または独自実装）とテストランナー（Pest または PHPUnit）。

バージョン依存の動作については、Boost が利用可能な場合、インストール済みのバージョンに基づいて絞り込めるため、Laravel Boost の search-docs を使ってください。利用できない場合は、インストール済みメジャーバージョンの公式ドキュメントを参照してください。boost-tools.md では、Boost の使い方とデータ安全性に関する制限を説明しています。

リポジトリのアーキテクチャ、命名規則、UI 言語、コンポーネントのパターンに従い、ユーザーから変更を依頼された場合を除き、依存関係は維持してください。

間違えやすいフレームワーク固有の仕様

• スケルトン。 最新のスケルトンでは、ミドルウェア、例外、ルーティングを bootstrap/app.php で設定し、プロバイダーを bootstrap/providers.php で登録し、クロージャー形式のコマンドとスケジュールを routes/console.php で定義します。Laravel 10 からアップグレードしたアプリケーションでは、app/Http/Kernel.php と app/Console/Kernel.php が引き続き使われている場合があります。この構成も引き続きサポートされているため、移行がタスクでない限り、そのまま維持してください。
• API ルート。 新規アプリケーションには routes/api.php は含まれていません。install:api を実行するとファイルが作成され、Sanctum がインストールされるため、両方が必要な場合にのみ実行してください。API 専用の作業では、Vite、Tailwind、Node を追加しないでください。
• カラムの変更。 change() は、再指定されていない修飾子をすべて削除します。現在のカラムを確認し、維持する修飾子を再指定してください。
• 破壊的なデータベースコマンド。 migrate:fresh、migrate:reset、ロールバック、db:wipe の実行には、対象とデータ損失を含む承認が必要です。すでに得ている許可を再利用してください。
• クエリ。 生の式をバインドしたクエリやクエリビルダーは、Eloquent より明確であれば問題ありません。信頼できない入力を SQL に直接埋め込まないでください。
• Inertia。 ページリゾルバーからページディレクトリと大文字・小文字の規則を確認してください。インストール済みの Inertia メジャーバージョンに対応したフォーム API とナビゲーション API を使用します。別のメジャーバージョンの例はそのまま適用できません。
• Wayfinder がインストールされている場合：出力をツリーシェイクできるよう、名前付きインポートを使用し、ルートやコントローラーを変更した後に再生成してください。
• Tailwind。 ロックファイルから v3 または v4 を確認してください。v4 は CSS（@import "tailwindcss"、@theme）で設定され、v3 で非推奨となったユーティリティが削除されています。移行を依頼されていない限り、動作している v3 の設定は v3 のまま維持してください。
• Livewire と Blade。 インストール済みの Livewire メジャーバージョンと、周辺のコードで使われているコンポーネント形式に合わせ、2 つ目のフロントエンドフレームワークを導入しないでください。

検証

リポジトリのテストランナーを維持し、php artisan help make:test でジェネレーターのフラグを確認してください。対象を絞った最小限のテスト（php artisan test <file> または --filter=）と、リポジトリで必要とされているチェックを実行し、重要な動作を守る回帰テストを追加してください。影響を受ける契約や未解決のリスクがある場合は、指定されたテストスイートの予算内で範囲を広げてください。

変更したコードには、設定済みのフォーマッターを実行してください。Pint がインストールされている場合は vendor/bin/pint --dirty が適しています。

変更した動作、実行したチェックとその結果、未解決の重要な前提があれば報告してください。