Flutter material_ui分割でAIエージェントが誤爆する落とし穴と対策

Flutter（Googleが開発するクロスプラットフォームUIフレームワーク）でClaude CodeやGitHub Copilot、Cursorなどのコーディングエージェントを使っている方に向けて、最近のパッケージ分割にAIが対応できない問題を整理します。プロジェクトのimport文を見直す前に、まずこの記事で該当有無を確認してみてください。

FlutterはMaterial Design（Googleのデザインシステム）とCupertino（iOS風デザインシステム）のウィジェット群を、これまでコアのflutter SDKに同梱していました。これがmaterial_uiとcupertino_uiという独立したpub.devパッケージに分割されています。便利だった一括importpackage:flutter/material.dartが、将来的に段階を経て非推奨化に向かう変更です。

何が起きるか

AIエージェントに「新しい分割パッケージへ移行して」と指示すると、多くのケースで期待通りに動きません。

存在しないパッケージ名や、すでに廃止されたimportパスを生成する「ハルシネーション（AIが事実に基づかない出力をする現象）」が起きます。

さらにDartアナライザ（静的解析ツール）が提供する自動修正ルールをAIが認識せず、GlobalMaterialLocalizationsのような多言語対応クラスの破壊的変更を見落とすケースも報告されています。

結果として、ビルドが通らないコード片が生成され、レビューやCIで手戻りが発生します。チーム開発では、これが複数人の環境で同時に起きると地味に工数を食います。

なぜ起きるか

原因は段階的に分解すると見えてきます。

1つ目はLLM（大規模言語モデル）の学習データの「カットオフ（学習データの収集を打ち切った時点）」です。material_uiとcupertino_uiの分割はFlutterのアーキテクチャ変更としてかなり新しく、多くのモデルの学習データには反映されていません。

2つ目は、AIエージェントがパッケージ構成の変更を「知識」としてではなく「推測」で補おうとする構造的な限界です。似た名前のパッケージやAPIパターンから類推してコードを生成するため、微妙に間違ったimportパスや存在しないクラス名を出力しがちです。

3つ目は、移行ルール自体がDartアナライザの「データ駆動修正（fix data driven）」という仕組みに埋め込まれており、AIエージェントが単体のプロンプトだけではその仕組みにアクセスできない点です。ルールはあるのに、AIがそこを見ていない、という状態です。

自分のプロジェクトが該当するか確認する

以下の手順で、影響範囲を確認できます。

# Flutter/Dart SDKのバージョンを確認
flutter --version

# プロジェクトのpubspec.yamlでflutter SDKのバージョン制約を確認
cat pubspec.yaml | grep -A2 "environment:"

# 既存コードでmaterial.dart/cupertino.dartを直接importしている箇所を列挙
grep -rl "package:flutter/material.dart" lib/
grep -rl "package:flutter/cupertino.dart" lib/

grepで該当ファイルが多数出てくる場合、移行対象が広いプロジェクトです。

またpubspec.yamlにmaterial_uiやcupertino_uiがすでに依存として追加されているかも確認してください。追加されていなければ、まだ移行に着手していない状態と判断できます。

AIエージェントを使ってこの移行を自動化しようとしている場合は、エージェントが使っているモデルの学習カットオフ時期も確認材料になります。カットオフが分割パッケージのリリースより前であれば、素のプロンプトだけでは正確な移行コードを出力できない可能性が高いと考えてよいでしょう。

対策の手順

対策の中心は、AIエージェントに「移行の正しい知識」を後から補う仕組みを使うことです。

ここで使われているのが「Agent Skills（AIエージェント向けに手順やルールを構造化して提供する仕組み）」という考え方です。SKILL.mdという形式で、バージョンごとのAPI差分や移行ルールを記述し、エージェントがプロンプト実行時に段階的に参照できるようにします。

DartとFlutter向けにはオープンソースのdart-sdk-skillsというリポジトリが提供されています。これをエージェントに組み込む手順は次の通りです。

# npx skillsツールを使ってグローバルに全AIエージェント向けへ導入
npx skills add RandalSchwartz/dart-sdk-skills -g

# Dart Skills CLIを使う場合
skills add https://github.com/RandalSchwartz/dart-sdk-skills --global --all

Google Antigravityのようにシンボリックリンクでのマニュアル導入をサポートするツールでは、リポジトリをクローンして該当ディレクトリに配置する方法も使えます。

導入後は、AIエージェントに対して「材料としてdart-sdk-skillsのmaterial_ui移行ルールを参照して」といった形で明示的に参照を促すプロンプトが有効です。単に「移行して」と依頼するより、どのルールセットを見るべきかを指示に含めることで、ハルシネーションの発生率を下げられます。

スキルを導入したあとも、生成されたコードは必ずDartアナライザ（dart analyzeコマンド）で検証してください。AIが提示した修正案が実際にコンパイル可能かどうかは、機械的な検証を通すまで確定させないのが安全です。

# 移行後のコードを静的解析でチェック
dart analyze

# 既知の破壊的変更に対する自動修正候補を確認
dart fix --dry-run

dart fix --dry-runは、アナライザに登録された既知の修正ルールに基づいて変更候補を表示するコマンドです。AIエージェントの提案と、このコマンドの出力を突き合わせることで、ハルシネーションによる誤ったimportを検出しやすくなります。

導入前に確認すること

material_ui・cupertino_uiへの分割は、Flutterのアーキテクチャとしては軽量化と独立したリリースサイクルという利点がありますが、AIエージェントの知識のズレという新しいリスクを持ち込みます。

実務では次の3点を確認してから移行に着手するとよいでしょう。

flutter --versionとpubspec.yamlの依存関係で現在の状態を把握する
使っているAIエージェントのモデルカットオフ時期と、素のプロンプトでの挙動を小規模に試す
dart-sdk-skillsのようなAgent Skillsを導入し、dart analyzeとdart fix --dry-runで機械的に検証する

AIエージェントは便利ですが、フレームワークの構造変化が新しいほど知識のギャップが大きくなります。移行作業に取りかかる前に、まず手元の環境でこの3点を確認してみてください。