🍳 AI x Flutter Cookbook

トラブルシューティング#7-4: AIとの開発で起こる典型的なトラブルと対処法

AI（Cursor + Claude、Claude Codeなど）を使ったFlutter開発では、従来の開発とは異なる特有のトラブルに遭遇することがあります。このガイドでは、よくある問題とその対処法を解説します。

トラブル1: AIが古いコードを生成する

症状

原因

AIの学習データが古く、最新のFlutter/Dartの仕様を反映していない場合があります。

対処法

方法1: プロンプトで最新バージョンを指定

Flutter 3.27 と Dart 3.6 の最新機能を使って、
TODOアプリを作成してください。
非推奨のAPIは使わないでください。

方法2: @Docsで公式ドキュメントを参照させる

Cursor/Claude Codeで：

@Docs Flutter 公式ドキュメント
最新のNavigator 2.0を使ったルーティングを実装してください。

方法3: 生成されたコードを確認する習慣

# 非推奨の警告を確認
flutter analyze

# pubspec.yamlのバージョンを確認
cat pubspec.yaml

解決例:

// ❌ 古いコード（AIが生成）— RaisedButtonはFlutter 2.0で削除済み
RaisedButton(
  onPressed: () {},
  child: Text('保存'),
);

// ✅ 最新のコード（修正後）
ElevatedButton(
  onPressed: () {},
  child: Text('保存'),
);

トラブル2: AIが間違った依存関係を追加する

症状

原因

AIがパッケージ名を間違えたり、互換性のないバージョンを指定したりします。

対処法

方法1: 依存関係を明示的に指定

pubspec.yamlに以下を追加してください：
- http: ^1.2.0
- provider: ^6.1.0

バージョンは必ず pub.dev の最新安定版を確認してください。

方法2: 生成後に確認

# pub.devで最新バージョンを確認
flutter pub outdated

# 依存関係の競合を確認
flutter pub get

方法3: AIに確認させる

@pubspec.yaml を見て、
依存関係に問題がないか確認してください。
不要なパッケージがあれば削除してください。

トラブル3: AIが生成したコードが動かない

症状

原因

対処法

方法1: エラーメッセージをそのままAIに見せる

Cursorで：

以下のエラーが出ています。修正してください：

[エラーメッセージ全体をコピー＆ペースト]

方法2: 全体を見直すよう指示

@lib/ フォルダ全体を見て、
このエラーの原因を特定し、修正してください。

方法3: 段階的にテスト

// 小さく始めて、動作確認しながら進める
void main() {
  print('Step 1: OK');
  runApp(MyApp());
}

デバッグのコツ:

# Hot Restart（完全再起動）
R  # flutter run中にRキーを押す

# ログを確認
flutter logs

トラブル4: AIがハルシネーションを起こす

症状

原因

AIが「こうあるべき」という理想を生成してしまい、実際のAPIと乖離します。

対処法

方法1: 公式ドキュメントを参照させる

@Docs Flutter Widget Catalog
Scaffoldウィジェットの正しい使い方を確認してから、
コードを書いてください。

方法2: 検証を依頼

このコードは本当に動きますか？
Flutter 3.27の公式APIドキュメントと照らし合わせて確認してください。

方法3: 小さく実装して確認

まず、最小限の動作する例を作成してください。
その後、段階的に機能を追加していきましょう。

ハルシネーションの見分け方:

// ❌ 存在しないメソッド
Widget.magicLayout() // こんなメソッドはない

// ✅ 実際のAPI
Widget build(BuildContext context) // 正しい

トラブル5: AIが既存コードを壊してしまう

症状

原因

対処法

方法1: Gitでバージョン管理（必須）

# 変更前に必ずコミット
git add .
git commit -m "AIに修正を依頼する前の状態"

# 問題があればロールバック
git reset --hard HEAD

方法2: 変更範囲を限定する

Cursorで：

@lib/home_page.dart のみを修正してください。
他のファイルは変更しないでください。

方法3: Composerで変更内容をプレビュー

Cursor Composer（Ctrl+I）を使うと： 1. AIが変更案を提示 2. Accept/Rejectで承認/拒否できる 3. 部分的に承認することも可能

ベストプラクティス:

# 小さな変更ごとにコミット
git add lib/home_page.dart
git commit -m "ホームページにボタン追加"

# 大きな変更は新しいブランチで
git checkout -b feature/new-ui

トラブル6: AIとの対話で望む結果が得られない

症状

原因

対処法

方法1: 具体的に指示する

❌ 悪い例：

ボタンを追加して

✅ 良い例：

画面下部に、青色のElevatedButtonを追加してください。
ボタンのテキストは「保存」で、
押すとデータをSharedPreferencesに保存する処理を実装してください。

方法2: ファイルを明示的に参照

@lib/main.dart を見て、
同じスタイルでボタンを追加してください。

方法3: 期待する動作を説明

以下のような動作を実装してください：
1. ボタンを押す
2. ローディングインジケーターを表示
3. APIからデータ取得
4. 成功したら画面を更新
5. 失敗したらエラーメッセージを表示

方法4: 段階的に指示

Step 1: まず、ボタンだけを追加してください。
（確認後）
Step 2: ボタン押下時の処理を追加してください。

トラブル7: Cursorが正しいファイルを参照していない

症状

原因

対処法

方法1: @マークで明示的に指定

@lib/screens/home_page.dart
@lib/widgets/custom_button.dart
これらのファイルを参照して、統一感のあるUIにしてください。

方法2: Cursorのインデックスを再構築

Cmd+Shift+P (Mac) / Ctrl+Shift+P (Windows)
→ "Cursor: Reindex"

方法3: プロジェクトをシンプルに保つ

.cursorignore の例:

build/
.dart_tool/
*.g.dart
*.freezed.dart

トラブル8: AIが生成するコードが複雑すぎる

症状

原因

AIが「ベストプラクティス」として複雑なパターンを提案します。

対処法

方法1: シンプルさを要求

初心者でも理解できる、最もシンプルな実装をしてください。
デザインパターンや抽象化は不要です。
StatefulWidgetで素直に実装してください。

方法2: 具体的なパターンを指定

Riverpodは使わないでください。
StatefulWidgetとsetStateで実装してください。

方法3: ファイル単位で自己完結させる

1つのファイル内で完結する、
自己完結型のウィジェットとして実装してください。

このCookbookの推奨： - 小さな自己完結型Widget - setState中心の状態管理 - 複雑な状態管理ライブラリを避ける

トラブル9: AIが遅い・応答しない

症状

原因

対処法

方法1: モデルを変更

方法2: コンテキストを減らす

# 特定のファイルだけを参照
@lib/home_page.dart のみを見て修正してください。

方法3: Cursorを再起動

# Cursorを完全に終了して再起動

方法4: キャッシュをクリア

Cmd+Shift+P / Ctrl+Shift+P
→ "Developer: Reload Window"

トラブル10: パッケージのバージョン競合

症状

原因

AIが互換性のないパッケージバージョンを指定しました。

対処法

方法1: AIに解決させる

@pubspec.yaml
以下のエラーが出ています。依存関係を修正してください：

[エラーメッセージをペースト]

方法2: 手動で最新版に統一

# パッケージの最新版を確認
flutter pub outdated

# 特定のパッケージを更新
flutter pub upgrade http

方法3: バージョン指定を緩める

# ❌ 厳密すぎる
http: 1.2.0

# ✅ 範囲指定
http: ^1.2.0  # 1.2.0以上2.0.0未満

予防策：AIとうまく付き合うためのベストプラクティス

1. 常にGitでバージョン管理

# 作業前
git status
git add .
git commit -m "作業前の状態"

# AIに依頼
# ...

# 確認後
git add .
git commit -m "AIによる変更を承認"

2. 小さく始める

❌ 「TODOアプリ全体を作成してください」
✅ 「まず、TODOリストを表示する画面だけを作成してください」

3. 段階的に検証

1. コード生成
2. flutter run で動作確認
3. 問題があれば即座にAIに報告
4. 動作確認できたらコミット

4. プロンプトの型を作る

【テンプレート】
ファイル: @lib/xxx.dart
目的: [何をしたいか]
制約: [使わないパッケージ、守るべきルール]
期待する動作: [具体的な挙動]

5. ドキュメントを参照させる

@Docs Flutter公式ドキュメント
@pubspec.yaml
@README.md
これらを参照して実装してください。

6. エラーは隠さず全て見せる

以下のエラーが出ています：

[エラーメッセージ全文]
[スタックトレース]

解決方法を教えてください。

7. シンプルさを優先

複雑な設計パターンは不要です。
初心者でも理解できる、最もシンプルな方法で実装してください。

まとめ

AIとの開発は、以下を意識すると成功率が上がります：

✅ Gitでバージョン管理（必須） ✅ 小さく始めて、段階的に進める ✅ 具体的で明確なプロンプト ✅ エラーはすぐAIに見せる ✅ @マークで参照を明示 ✅ シンプルさを優先 ✅ 生成されたコードを必ず確認

AIは強力なパートナーですが、完璧ではありません。上記のトラブルシューティングを参考に、AIとうまく付き合いながら開発を進めましょう。

関連レシピ: - #1-2: AI開発ツールの導入 - #4-1: Cursorを使った効率的な開発ワークフロー

➡️ 次のセクションへ: セクション8: BFFとサーバーサイドDart