Claude CodeでFlutterアプリを開発する手順 — CLAUDE.mdとhooksの設定例

Claude CodeはDartやFlutterのコードも、ほかの言語のプロジェクトと同じように読み書きできる汎用のコーディングエージェントです。専用モードは無いため、Flutter SDKを別途インストールし、CLAUDE.mdにビルド・テストコマンドを書き、hooksでフォーマットを自動化するのが実務上の基本形になります。この記事ではプロジェクト作成からhot reloadの扱い、hooksの設定例までを公式ドキュメントに基づいて示します。

Claude CodeでFlutter開発を始める前に

Claude Code自体にFlutter専用の機能は無く、DartファイルもFlutterプロジェクトの構造も「ファイルを読み書きできるエージェント」として扱われます。始める前に、Flutter SDKとClaude Codeをそれぞれ独立にインストールしておく必要があります。

Flutter SDKのインストールは、公式ドキュメントのInstall FlutterがmacOS・Linux・Windows・ChromeOS向けの手順を提供しています。VS CodeまたはAndroid Studioベースのエディタから導入する「Quick start」と、SDKを個別にダウンロードする「Custom setup」の2通りから選べます。

Claude Code側は、ターミナルへのネイティブインストールが公式に推奨されています。

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

インストール後、Flutterプロジェクトのルートディレクトリでclaudeを起動すればセットアップは完了です。VS CodeでFlutter開発をしている場合は、Flutter拡張機能とClaude CodeのVS Code拡張機能を両方入れておくと、エディタ内でhot reloadとClaude Codeの提案を行き来できます。

Flutterプロジェクトの作成とCLAUDE.mdの準備

新規プロジェクトはFlutter側のコマンドで作成し、Claude Code用の設定は後から追加します。ターミナルで作業する場合、公式ドキュメントは次の手順を示しています。

flutter create my_app
cd my_app

プロジェクト名はlowercase_with_underscoresの命名規則に従います。最小構成のmain.dartだけで始めたい場合はflutter create --empty、利用可能なオプションを確認したい場合はflutter create --helpを使います。

プロジェクトを作成したら、CLAUDE.mdをルートに置きます。Claude Codeの公式ドキュメントは、ビルドコマンド・テストコマンド・命名規則など「毎回説明し直すことになる情報」をCLAUDE.mdに書くよう推奨しており、1ファイルあたり200行程度を目安にするとしています。

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

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

Claude Codeで実装を進める基本フロー

FlutterプロジェクトでのClaude Codeの使い方は、ほかの言語のプロジェクトと基本的に同じです。公式ドキュメントが示す「コードベースの理解」「バグ修正」「テストの追加」という3つの定番フローを、Flutterの語彙に置き換えて使えます。

新しいFlutterプロジェクトに参加したときは、まず構造を把握するプロンプトから始めます。

• このコードベースの概要を教えて
• Widgetツリーの構成と状態管理の方法を説明して
• 既存の画面遷移(ルーティング)の実装パターンは

バグ修正では、エラーメッセージやスタックトレースをそのまま渡します。「flutter runでこのエラーが出た」に続けてログを貼り付けるだけで、該当箇所の特定まで任せられます。

テストを追加する場合は、公式ドキュメントの「テストを扱う」手順がそのまま使えます。未カバーのロジックを見つけ、テストの骨格を生成し、エッジケースを追加し、最後に実行して失敗を直すという4段階です。Flutterのテストにはunit test・widget test・integration testの3種類があり、flutter testはこのうちunit testとwidget testを実行します。

3種類のテストは対象範囲によって位置づけが変わります。unit testは関数・メソッド・クラス単体の正しさを検証し、外部依存はモックに置き換えるのが基本です。widget testは他のUIフレームワークでいうコンポーネントテストに相当し、単一Widgetの見た目と操作への反応を検証します。integration testはアプリ全体または大部分を通しで動かす分、実行は遅くなりますが確認できる範囲は最も広くなります。Claude Codeに「テストを書いて」とだけ指示すると粒度が曖昧になりやすいため、unit・widget・integrationのどれを書いてほしいかを指示に含めておくと精度が上がります。

依存パッケージの追加や更新もClaude Codeに任せられます。pubspec.yamlを直接編集させたうえでflutter pub getを実行させれば、バージョン制約の調整まで含めて一度に完了します。ただしメジャーバージョンを跨ぐ更新は破壊的変更を伴うことがあるため、差分を確認してから反映したほうが安全です。

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

hot reloadとhooksによる自動化

FlutterのUI確認で使うhot reloadは、Claude Codeが自動で行う機能ではありません。公式ドキュメントはAIコーディングアシスタントが変更後に自動でhot reloadを実行する例としてGoogle Antigravityを挙げていますが、Claude Codeにこの統合はありません。Claude Codeがファイルを編集した後、変更を画面に反映するには次のいずれかの操作が必要です。

• flutter runを実行しているターミナルでrキーを押す
• エディタの保存時hot reloadを有効にし、Claude Codeの編集後に保存を挟む

VS Codeで保存時hot reloadを使う場合は、.vscode/settings.jsonに次の設定を追加します。

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

フォーマットの実行は、hot reloadと違いhooksで自動化できます。Claude CodeのPostToolUse hookは、EditまたはWriteツールが使われた直後にコマンドを実行できるため、dart formatを毎回手動で呼ばずに済みます。

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

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

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

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

よくあるつまずき

• flutter doctorの警告を無視して進め、ビルドが失敗する: 公式ドキュメントはissue報告時にflutter doctorの出力を添付するよう求めています。Android SDKやXcodeの未設定はこのコマンドで先に検出したほうが早く済みます
• Claude Codeが既存のProvider実装を無視して書き換える: CLAUDE.mdに状態管理の方針を書いていないと、Claudeは一般的なパターンで実装を提案しがちです。参照してほしいファイルを指示に含めると改善します
• flutter pub getのたびに許可確認が出る: 上記のpermissions.allow設定を.claude/settings.jsonに追加すると解消します
• 依存パッケージのバージョン競合でflutter pub getが失敗する: エラーメッセージにはどのパッケージ同士が競合しているかが表示されます。そのままClaude Codeに渡せばpubspec.yamlの制約を調整する提案を出してくれます

複数のIDE・端末をまたいでClaude Codeを使う場合、CLIだけでなくDesktopアプリのプレビュー機能でUIの変化を確認できる場面もあります。対応範囲はClaude Code DesktopアプリプレビューでWebアプリを検証するにまとめています。

Claude CodeとFlutter開発、どこまで任せられるか

Flutter開発のどの作業をClaude Codeに任せやすいかは、作業の種類によって差があります。Dartのコードだけで完結する作業は既存コードを参照した提案ができる一方、画面の見た目確認やプラットフォーム固有の設定は人の手を挟む工程が残ります。

まとめ

Claude CodeでFlutterアプリを開発する基本形は、Flutter SDKとClaude Codeを別々にインストールし、CLAUDE.mdにビルド・テストコマンドを書き、PostToolUse hookでフォーマットを自動化することです。hot reloadだけはClaude Codeの自動化対象外なので、flutter runのターミナルか保存時hot reloadで手動に反映させます。プロジェクトが大きくなってきたら、複数ツールの設定統合やより高度なhooksの設定も検討します。DartのロジックやWidget実装のようにテキストで完結する作業ほどClaude Codeとの相性がよく、実機での見た目確認やネイティブ設定は引き続き人の目で確かめる工程として残る、という役割分担を意識しておくと運用しやすくなります。