flutter-debugging

ログ出力

• すべてのログ出力には集中管理された AppLogger クラスを使用してください。print() や生の debugPrint() は絶対に使用しないでください
• ログレベルを定義してください: verbose、debug、info、warning、error、fatal
• dev フレーバーでは、すべてをログに記録します（verbose 以上）
• staging では、info 以上をログに記録します
• production では、warning 以上のみをログに記録し、Crashlytics に送信します
• ログにコンテキストを含めてください: AppLogger.error('Failed to fetch user', error: e, stackTrace: st)
• 機密データ（パスワード、トークン、PII）はどのレベルでも絶対にログに記録しないでください

Flutter DevTools

• Widget Inspector を使用してレイアウトの問題をデバッグし、不要な再ビルドを特定してください
• Performance Overlay（showPerformanceOverlay: true）を使用してフレームレートを監視してください
• Timeline View を使用してジャンクを特定してください: 1 フレームあたり 16ms（60fps）を目標にします
• Memory View を使用してメモリリークを検出し、割り当てパターンを監視してください
• Network Profiler を使用して開発中の Dio のリクエスト/レスポンスを検査してください

デバッグ戦略

• レイアウトの問題: debugPaintSizeEnabled = true を使用してウィジェットの境界を可視化してください（flutter-devtools を参照）。
• オーバーフローエラー: RenderFlex overflowed を確認してください: Expanded、Flexible を使用するか、寸法を制約してください
• 高さの制約なし: ListView を SizedBox でラップするか、NeverScrollableScrollPhysics とともに shrinkWrap: true を使用してください
• 再ビルドの追跡: 過剰な再ビルドを特定するために、一時的に debugPrint('$runtimeType rebuild') を追加してください（コミット前に削除してください）
• エージェント型ホットリロード: Flutter 3.44+/Dart 3.12+ では、AI コーディングエージェントと MCP サーバーがコードの変更を検出し、ホットリロードを自動的にトリガーします。リアルタイム更新を有効にするには、デバッグデーモン（flutter run）を実行したままにしてください。
• 非同期エラー: try-catch ブロック内でスタックトレースとともにエラーを必ず捕捉してログに記録してください
• リリースビルドでは除去される開発時の不変条件チェックには assert() を使用してください

メモリ管理

• dispose() ですべてのコントローラー、サブスクリプション、Timer、AnimationController を破棄してください
• initState() では late による初期化を使用してください: 破棄が必要なオブジェクトをインラインで初期化しないでください
• ガベージコレクションを妨げるべきでないキャッシュには WeakReference を使用してください
• DevTools の Memory タブでメモリをプロファイリングしてください: 単調に増加する割り当てに注意してください
• よくあるリークに注意してください: 破棄されていないリスナー、BuildContext を捕捉するクロージャ、キャンセルされないグローバルストリーム

パフォーマンスプロファイリング

• 常に --profile モード（debug ではない）でプロファイリングしてください: flutter run --profile --flavor dev
• クリティカルパスのカスタムパフォーマンストレースには Timeline.startSync / Timeline.finishSync を使用してください
• Impeller グラフィックス: Impeller は iOS および Android のデフォルトのレンダリングエンジンです。シェーダーの事前コンパイル（SkSL ウォームアップ）は非推奨であり、もはや必要ありません。レンダリングのアーティファクトが発生する場合は、ターミナルでコンパイルログを確認してください。
• ディスプレイの目標指標:
  • 60Hz スクリーン: フレームビルド時間 < 16.6ms。
  • 90Hz スクリーン: フレームビルド時間 < 11.1ms。
  • 120Hz スクリーン: フレームビルド時間 < 8.3ms。
  • 画面遷移: < 100ms。
  • コールドスタート: < 2s。

エラーバウンダリ

• staging/prod ではエラーを Crashlytics に送信してください（FlutterError.onError = FirebaseCrashlytics.instance.recordFlutterFatalError）
• フレームワークおよび非同期エラーを捕捉するために FlutterError.onError と PlatformDispatcher.instance.onError を設定してください
• クリティカルなウィジェットのサブツリーをカスタムのエラーバウンダリウィジェットでラップし、レッドスクリーンの代わりにフォールバック UI を表示してください
• リリースモードでは、ユーザーにスタックトレースを絶対に表示しないでください: ユーザーフレンドリーなエラーメッセージのみを表示してください

ランタイムエラーの分類

静的解析と型システムの知識を活用して、Dart のランタイムエラーを体系的に分類し修正してください。

型システムの健全性

• メソッドのオーバーライド: 健全な戻り値の型（共変）とパラメータの型（反変）を維持します。パラメータの型を意図的に厳密にする場合は covariant キーワードを使用します。
• ジェネリクス: ジェネリッククラスには明示的な型注釈を付けます（List<dynamic> ではなく List<int>）。List<dynamic> を型付きリストに代入しないでください。
• ダウンキャスト: dynamic からの暗黙的なダウンキャストは避けてください。実行時の型が保証されている場合にのみ、明示的なキャスト（as Type）を使用します。
• 厳密なキャストを有効化: analysis_options.yaml に追加します：

  analyzer:
    language:
      strict-casts: true
  

Null 安全性のエラーパターン

エラー	原因	修正
Property cannot be accessed on nullable receiver	Type? のメンバーにアクセスしている	?. または null チェックを使用する
Non-nullable instance field must be initialized	非 null フィールドが初期化されていない	late を使用するか null 許容にする
The argument type can't be assigned	Type が期待される箇所に Type? を渡している	null チェックまたは ! を追加する（注意して使用）

ルール:

• ! 演算子は避けてください：パターンマッチングまたは早期リターンを優先します。
• late は、最初のアクセス前に初期化が保証されている場合にのみ使用します。
• 未使用の変数には _ ワイルドカード（Dart 3.7+）を使用します。

自動解決ワークフロー

# 1. Identify all errors
dart analyze . --fatal-infos

# 2. Preview automated fixes
dart fix --dry-run

# 3. Apply automated fixes
dart fix --apply