FlutterでClaude Codeを使う手順 — プラグイン・CLAUDE.md・hooksの設定

FlutterでClaude Codeを使うなら、Flutter公式のdart-flutterプラグインを入れるのが近道です。claude plugin marketplace add flutter/agent-pluginsの後にclaude plugin install dart-flutter@dart-flutterを実行すると、Dart and Flutter MCPサーバーとFlutter向けスキルが使えます。Claude Code自体はFlutter専用のモードを持たない汎用のコーディングエージェントなので、プラグインなしでも動きます。この記事では、プロジェクト作成からCLAUDE.mdの書き方、プラグインとMCPサーバー、hot reload、hooksによるフォーマット自動化、テストの頼み方までを手を動かす順に示します。

Claude CodeでFlutter開発を始める手順

Claude CodeとFlutter SDKは、それぞれ独立にインストールします。Flutter側の導入手順はFlutter公式のInstall Flutterにあり、「Quick start」と「Custom setup」の2通りが用意されています。

Claude Codeのインストールコマンドは次のとおりです。

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

プロジェクトの作成はFlutter側のコマンドで行います。プロジェクト名はlowercase_with_underscoresの命名規則に従う必要があります。

flutter create my_app
cd my_app
claude

最小構成のmain.dartだけで始めたいときはflutter create --empty、指定できるオプションはflutter create --helpで見られます。

CLAUDE.mdに書くFlutterプロジェクトの情報

ビルドコマンド、テストコマンド、命名規則のように「毎回説明し直すことになる情報」はCLAUDE.mdに置きます。1ファイルあたりの長さは200行未満が目安で、長いほどコンテキストを消費して指示の守られ方が下がるとされています。

# CLAUDE.md
 
## セットアップ
- 依存関係の取得: `flutter pub get`
- 環境の確認: `flutter doctor`
 
## テスト
- 全テスト実行: `flutter test`
- 特定ファイルのみ: `flutter test test/widget_test.dart`
 
## コーディング規約
- ファイル名は`lowercase_with_underscores`
- 状態管理は既存のProvider実装に合わせる(lib/providers/ を参照)

「状態管理は既存のProvider実装に合わせる」のように、プロジェクトの流儀を1行書いておくと、方針が指示として届きます。参照してほしいディレクトリを添えておくと、読む場所も伝わります。

Cursor・Clineなど複数のAIコーディングツールを併用しているチームは、共通指示をAGENTS.mdに集約してCLAUDE.mdからインポートする運用も選べます。二層構成の具体例はAGENTS.mdとCLAUDE.mdで設定を統合する運用パターンにあります。

Flutter公式プラグインとMCPサーバーでDartのツールを足す

Flutterのドキュメントには、AIコーディングアシスタントごとの導入手順を並べた「Get started developing with AI」のページがあり、Claude Code向けの項目があります。「agent plugin」は、スキル(Flutter・Dart固有の手順書)、ルール、Dart and Flutter MCPサーバー、専用エージェントの4つをまとめたものです。MCPサーバーはDart SDKにつながり、アナライザーの診断、シンボル解決、テスト実行、実行時の状態の検査をClaude Codeから呼べるようにします。

Claude Code向けの導入コマンドは2本で、3本目は確認用です。

claude plugin marketplace add flutter/agent-plugins
claude plugin install dart-flutter@dart-flutter
claude plugin marketplace list

claude plugin marketplace addは既定でユーザースコープに登録し、--scope projectでプロジェクト単位にも宣言できます。v2.1.287のclaude plugin marketplace add --helpには、--scope <scope>がuser (default), project, or localと書かれています。チームで同じ構成を使いたいなら、プロジェクトスコープが候補になります。

ここに1点、落とし穴があります。Flutterのドキュメントによると、Claude CodeのプラグインはスキルとMCPサーバーを自動で拾いますが、プラグインのルールは自動では読み込みません。ルールを効かせるには、flutter/agent-pluginsリポジトリのrulesディレクトリから必要なものを選び、プロジェクトのCLAUDE.mdに書き写します。上のCLAUDE.mdの例にルールを足していく形です。入るスキル25本の一覧はDart and Flutterプラグインのスキル解説にあります。

hot reloadをClaude Codeの編集後に反映させる方法

hot reloadは、実行中のアプリにコードの変更を読み込ませてWidgetツリーを再構築する機能です。Flutterのドキュメントは、デバッグモードで動かしているアプリだけがhot reloadとhot restartの対象だと書いています。反映のさせ方は、手動か、AI側の仕組みかの2系統です。

VS Codeで保存時hot reloadを有効にする場合は、.vscode/settings.jsonに次の2行を足します。

{
  "files.autoSave": "afterDelay",
  "dart.flutterHotReloadOnSave": "all"
}

hot reloadで反映されない変更もあります。Flutterのドキュメントによると、hot reloadで再実行されるのはWidgetの再構築に関わるコードだけで、main()とinitState()は再実行されません。Claude CodeにinitState()の中身を直させたのに画面が変わらないときは、バグではなく仕様です。hot restart(アプリ状態は失われます)を使うか、コンパイルエラーが出ているなら先にそちらを直します。

PostToolUse hookでdart formatを自動化する

フォーマットはhot reloadと違い、hooksで自動化できます。PostToolUseは「ツール呼び出しが成功した直後」に走るイベントで、matcherにEdit|Writeを指定すれば、ファイルを書き換えるたびにコマンドを実行できます。

最も短い書き方はdart format .をそのまま登録する形です。

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": "dart format ." }
        ]
      }
    ]
  }
}

この形はプロジェクト全体が対象になるため、Claude Codeが触っていないファイルまで整形されることがあります。編集されたファイルだけを整形したいときは、hookに渡されるJSONのtool_input.file_pathを使います。hookの入力はJSONで標準入力に渡され、jqで取り出せます。

.claude/hooks/dart-format.shを次の内容で作り、実行権限を付けます。

#!/bin/bash
file=$(jq -r '.tool_input.file_path // empty')
case "$file" in
  *.dart) dart format "$file" ;;
esac

.claude/settings.jsonからは、${CLAUDE_PROJECT_DIR}を使って指します。

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/dart-format.sh"
          }
        ]
      }
    ]
  }
}

jq -r '.tool_input.file_path'は、{"tool_name":"Edit","tool_input":{"file_path":"/work/my_app/lib/main.dart"}}のようなJSONから、パスだけを取り出します。.dart以外のファイルではcaseに当たらず、何も実行されません。jqが入っていない環境では、先にjqを導入してください。

flutter・dartコマンドを毎回の許可確認なしに実行したいときは、settings.jsonのpermissions.allowにBashルールを足します。

{
  "permissions": {
    "allow": [
      "Bash(flutter test *)",
      "Bash(flutter pub get)",
      "Bash(dart format *)"
    ]
  }
}

ルールの末尾の*の前には半角スペースを置きます。Bash(flutter test *)はflutter test単体にもflutter test test/widget_test.dartにも当たりますが、スペースを抜いたBash(flutter test*)はflutter testingのような別コマンドにも当たります。

HTTPエンドポイントに検証結果を送るような、より複雑なhooksはClaude CodeのHooksをHTTPエンドポイントで受けるで扱っています。

Flutterのテスト自動化をClaude Codeに頼む

Claude Codeのテスト追加フローは、未カバーのコードを見つけ、テストの骨格を作り、エッジケースを足し、実行して失敗を直すという4段階です。Flutterのテストはunit・widget・integrationの3種類あり、次のトレードオフが示されています。

「テストを書いて」とだけ頼むと、どの種類かが決まりません。unit testは関数・メソッド・クラス単体を確かめ、外部依存はモックに置き換えるのが基本です。widget testは単一Widgetの見た目と操作への反応を確かめます。integration testは通常、実機かエミュレーターで動かします。

integration testには、Flutter SDK同梱のintegration_testパッケージが使えます。ただしこのパッケージは、権限ダイアログ・通知・プラットフォームビューのようなネイティブUIを操作できません。そうした操作が必要なアプリ向けには、オープンソースのpatrolパッケージが紹介されています。依頼文には、どの種類を、どのファイルに書いてほしいかまで含めます。

依存パッケージの追加はpubspec.yamlを編集させたうえでflutter pub getを実行させる流れになります。メジャーバージョンをまたぐ更新は、差分を見てから反映するという選択肢があります。解決が失敗したときの切り分けはFlutterのpub依存衝突の直し方にあります。

仕様を固めてから実装に入りたい場合は、仕様駆動開発のワークフローも組み合わせられます。手順はcc-sddでClaude Codeの仕様駆動開発を実践するにあります。

つまずきやすい点と切り分け

症状ごとの見直し先を並べると、次のようになります。

ビルドが通らないときは、まずflutter doctorの出力を確かめます。

Flutter WebとしてブラウザーでUIを動かす場合は、DesktopアプリのプレビューでWebアプリを検証する方法があります。手順はClaude Code DesktopアプリプレビューでWebアプリを検証するにまとめています。

まとめ

素のClaude Codeで始めるなら、CLAUDE.mdにコマンドと流儀を書き、フォーマットはファイル単位のPostToolUse hookに任せるところまでで十分に回ります。hot reloadを任せたい、Dartの診断やテスト実行をツール経由で扱いたいという段階になったら、Flutterのプラグインとルールの取り込みが次の選択肢です。