Claude CodeでLaravel開発 — CLAUDE.md・Laravel Boost・Artisan権限の設定

Claude CodeでLaravelを開発するには、プロジェクトでClaude Codeを起動し、CLAUDE.mdに規約を書き、Laravel Boostを composer require laravel/boost --dev で入れてMCPを接続します。Laravelは規約に沿った構造を持つPHPフレームワークで、公式ドキュメントもAIコーディングツールとの相性を前面に出しています。仕上がりを左右するのは環境構築よりも、CLAUDE.mdの設計・Laravel Boostの接続・Artisanの権限ルールの3点です。この記事では、インストールから権限設計までを順に説明します。Vue系のNuxtはClaude CodeでのNuxt開発手順にまとめています。

Claude CodeとLaravelの開発フロー全体像

Laravel公式ドキュメントは、Laravelの意見の効いた規約と明確な構造を「AI活用開発に理想的なフレームワーク」と位置付けています。コントローラーを追加するよう指示すれば配置場所に迷わず、マイグレーションの命名規則とファイル位置も予測可能だと説明されています。

Claude Codeはコードベース全体を読み込み、ファイル編集やコマンド実行、開発ツールとの統合をこなすエージェント型のコーディングツールです。ターミナル、IDE拡張、デスクトップアプリ、ブラウザーなど複数の利用形態で動きます。

開発を始める前に必要な環境

Laravelアプリの作成には、PHP・Composer・Laravel installerが必要です。フロントエンド資産をビルドするため、NodeとNPM、またはBunも用意します。

PHPとComposerが未導入の環境では、公式が提供するインストールスクリプトでPHP・Composer・Laravel installerをまとめて導入できます。

/bin/bash -c "$(curl -fsSL https://php.new/install/mac/8.4)"

Windows PowerShellとLinuxにも同等のスクリプトが用意されており、URLの mac 部分を windows や linux に置き換えます。すでにPHPとComposerがある場合は、Composer経由でLaravel installerだけを追加できます。

composer global require laravel/installer

Claude Code本体は、ネイティブインストーラーで導入します。

curl -fsSL https://claude.ai/install.sh | bash

ネイティブインストールはバックグラウンドで自動更新されます。以降はターミナルで claude と入力するだけで起動できます。

Laravelアプリの作成と起動

環境が整ったら、Laravel installerで新規アプリを作成します。インストーラーはテストフレームワーク・データベース・スターターキットの選択を対話形式で尋ねます。

laravel new example-app
cd example-app
npm install && npm run build
composer run dev

composer run dev は、開発用サーバーとキューワーカー、Viteの開発サーバーをまとめて起動するComposerスクリプトです。起動後はhttp://localhost:8000でアプリにアクセスできます。

既定のデータベースはSQLiteです。アプリ作成時に database/database.sqlite が生成され、必要なマイグレーションも自動実行されます。MySQLやPostgreSQLを使う場合は、.env の DB_* 変数を書き換えたうえで php artisan migrate を実行します。

CLAUDE.mdにはLaravelの何を書くか

Claude Codeはセッション開始時にCLAUDE.mdを読み込み、そこに書かれた指示に沿って動きます。プロジェクトのCLAUDE.mdは ./CLAUDE.md か ./.claude/CLAUDE.md に置きます。バージョン管理を通じてチーム全体と共有される点が、個人用の CLAUDE.local.md との違いです。

ゼロから書く必要はありません。/init コマンドを実行すると、Claude Codeがコードベースを解析し、ビルドコマンドやテスト手順、発見した規約を含むCLAUDE.mdを自動生成します。すでにCLAUDE.mdがある場合は、上書きせず改善案を提示します。

Laravelで書く価値があるのは、artisan のコマンド一覧のような調べればわかる情報ではなく、そのプロジェクト固有の取り決めです。たとえば次のような内容です。

# CLAUDE.md
 
## コマンド
- テスト: `php artisan test`
- 整形: `vendor/bin/pint`
- 開発サーバー: `composer run dev`(起動済みなら再起動しない)
 
## 規約
- 検証はコントローラーに書かず、FormRequestクラスに切り出す
- マイグレーションは追加のみ。既存ファイルは編集しない
- `.env` は読まない。設定値は `config()` 経由で参照する

指示の書き方も仕上がりに影響します。公式ドキュメントは「コードを適切にフォーマットする」のような曖昧な指示より、「2スペースインデントを使う」のように検証可能な具体的指示を推奨しています。ファイルサイズは200行が目安です。大きくなる場合は、パス限定ルール(.claude/rules/)に分割します。静的解析のlevelやbaselineの取り決めを書く例は、Claude CodeでPHPStan(Larastan)の型エラーを減らす手順にあります。

こうした規約をコードに落とす前に仕様を固める開発スタイルは、cc-sddによる仕様駆動開発とも相性が良い考え方です。

Laravel Boostでアプリの中身を読ませる

Laravel Boostは、AIコーディングエージェントにLaravel固有のガイドライン・スキル・MCPサーバーを渡すComposerパッケージです。Laravelエコシステムの1万7千件以上の情報を意味検索で引けるドキュメントAPIも備えています。

composer require laravel/boost --dev
php artisan boost:install

boost:install は対話形式で、使うコーディングエージェントを選ばせます。選んだエージェント向けに、MCPの設定ファイル(.mcp.json)、ガイドライン(CLAUDE.md や AGENTS.md)、スキルのファイルが生成されます。これらは boost:install と boost:update のたびに再生成されるため、Boostのドキュメントは .gitignore に入れてよいと説明しています。

MCPが渡す読み取り手段

Boostの boost:mcp コマンドは、エージェントがアプリの状態を調べるためのMCPツールを提供します。13.x版のドキュメントに載っているのは次の10種類です。

• Application Info:PHPとLaravelのバージョン、DBエンジン、導入済みパッケージ、Eloquentモデルの一覧
• Database Connections・Database Schema・Database Query:接続先の一覧、スキーマの読み取り、クエリの実行
• Browser Logs・Last Error・Read Log Entries:ブラウザーのログ、直近のエラー、アプリログの末尾N件
• Search Docs:導入済みパッケージに合わせたLaravelドキュメントの検索
• Get Absolute URL:相対パスを絶対URLに変換
• Record Rule:継続して守らせたい規則を .ai/rules に記録

12.x版のドキュメントの一覧は9種類で、Record Ruleがありません。12.x版と13.x版のドキュメントで一覧が違うので、使っているLaravelの版に合うドキュメントを見ます。

自動登録されないときの手動接続

Claude Codeへの登録は通常、自動で済みます。されていない場合、Boostのドキュメントはプロジェクトのディレクトリで次を実行するよう案内しています。

claude mcp add -s local -t stdio laravel-boost php artisan boost:mcp

この -s が接続の共有範囲を決めます。Claude Code v2.1.289の claude mcp add --help では、-s, --scope に local・user・project が並び、既定は local です。書き込み先は次のように分かれます。

-s project で生成される .mcp.json は次のような形です。

{
  "mcpServers": {
    "laravel-boost": {
      "type": "stdio",
      "command": "php",
      "args": ["artisan", "boost:mcp"],
      "env": {}
    }
  }
}

公式ドキュメントによると、.mcp.json に書かれたプロジェクトスコープのサーバーは、利用者が承認するまで有効になりません。クローンした直後は承認待ちの状態で、claude を対話モードで起動して承認します。

ガイドラインとスキルの使い分け

Boostは知識を2つの形で渡します。常時読み込むか、必要なときだけ読み込むかが違います。

Boostが生成する CLAUDE.md と、自分で書く CLAUDE.md は同じファイルを取り合います。Boostのドキュメントによると、これらのファイルは boost:install や boost:update の実行で自動的に再生成されます。Boostと無関係な手書きの規約は、置き場所を分けると再生成の影響を受けにくくなります。13.xのドキュメントでは、Record Ruleの書き込み先である .ai/rules ディレクトリは、ルールをチームで共有するためソース管理にコミットするものとされています。

• Boostに組み込ませたい規約は .ai/guidelines/ に置く
• Boostと無関係な規約は .claude/rules/ か CLAUDE.local.md に置く

パッケージの更新後は php artisan boost:update でガイドラインとスキルを最新にします。Composerの post-update-cmd に @php artisan boost:update --ansi を足すと、composer update のたびに実行されます。

Artisanコマンドの実行権限をどう設計するか

Claude Codeの権限システムは、ツール呼び出しをallow・ask・denyの3種類のルールで制御します。評価順はdeny、ask、allowの順で、最初に一致したルールで結果が決まります。広いdenyルールを、より狭いallowルールで打ち消すことはできません。

Bashコマンドのルールはコマンド全体の文字列と照合され、* で可変部分を表します。* の前の語は書かれたとおりに一致を求められるので、コマンド名の粒度は具体的に保ちます。

この3段階を .claude/settings.json に書くと次のようになります。

{
  "permissions": {
    "allow": [
      "Bash(php artisan make:model *)",
      "Bash(php artisan make:controller *)",
      "Bash(php artisan test *)"
    ],
    "ask": [
      "Bash(php artisan migrate *)",
      "Bash(composer require *)"
    ],
    "deny": [
      "Bash(php artisan migrate:fresh *)",
      "Bash(php artisan db:wipe *)"
    ]
  }
}

要点は * の前の空白です。公式ドキュメントによると、ルール末尾の * の空白は規則の一部で、Bash(ls *) は ls に一致し lsof には一致しません。同じ理屈で Bash(php artisan migrate *) は php artisan migrate と php artisan migrate --force に一致しますが、php artisan migrate:fresh には一致しません。migrate の直後がコロンで、空白ではないためです。migrate:fresh を止めるには、denyに個別に書きます。

一方、allowに Bash(composer *) だけを置くと、依存追加を伴う composer require まで通ります。askに Bash(composer require *) を併記すれば、こちらは確認が入ります。キューの失敗調査で queue:flush を止める書き方はClaude CodeでLaravelのキュー失敗を調べる手順にあります。

権限プロンプトで「Yes, and don't ask again」を選ぶと、Claude Codeはそのルールを .claude/settings.local.json に保存します。このファイルはソース管理に含めない前提です。チームで共有したい許可ルールは .claude/settings.json 側に書きます。そこにある allow ルールは、利用者がワークスペースの信頼ダイアログを承認してから有効になります。

Claude Codeはシェル演算子を認識します。&& や ; でつないだ複合コマンドは、各サブコマンドが個別にルールと照合されます。いずれかのサブコマンドがaskに一致すれば確認が入り、denyに一致すれば実行されません。cd /tmp && php artisan migrate もaskになります。起動時点からコマンドを絞りたい場合は、allowedTools/disallowedToolsによる絞り込みと組み合わせます。

よくあるつまずきと対処

CLAUDE.mdが肥大化して指示が効かなくなる。200行を超えるCLAUDE.mdは読み込むコンテキストが増え、指示への追従率が下がります。ディレクトリ構成や依存関係の一覧のようにコードベースから導出できる内容は削り、パス限定ルールへの分割を検討します。

.env を誤ってコミットしてしまう。Laravel公式も明記しているとおり、環境ごとに異なる設定を含む .env はGit管理の対象外にします。アプリ作成直後に .gitignore への追加を確認すると安心です。

migrate をaskにしたのに、migrate:fresh が確認なしで止まる。migrate:fresh は migrate * に一致しないため、askの対象外です。denyは常にaskとallowより先に評価されるので、止めたいコマンドはdenyに個別に書きます。

まとめ

CLAUDE.mdにはプロジェクト固有の取り決めだけを書き、アプリの状態を読む役目はBoostのMCPに任せる分担が基本です。権限は、migrate はask、migrate:fresh はdenyのように、コマンドの破壊力と * の空白の有無まで見て組みます。生成コマンドとテストを軸にした同様の組み方はClaude CodeでNestJSアプリを開発する手順にあります。

アプリが動くようになったら、次はデプロイの検討です。既存のPHPUnitテストをPestへ移す場合はClaude CodeでPHPUnitからPestへ移行する手順で進め方を扱っています。Herokuへのデプロイ手順はHeroku MCPサーバーでClaude Codeからアプリをデプロイ・スケーリングするで扱っています。Claude Codeを他の開発ツールと組み合わせた事例はClaude Code開発ツール導入事例でも比較しています。