Flutterのvibeコーディングの落とし穴：スムーズなリリースのための12の対処法

チャットで作ったFlutterプロジェクトがリリース直前に壊れる理由

VibeコーディングはクリックできるFlutterデモを素早く作れます。Koder.aiのようなツールはチャットから画面やフロー、場合によってはバックエンドの配線まで生成できます。しかし変えられないのは、モバイルアプリがナビゲーション、状態、権限、リリースビルドに対して非常に厳格である点です。電話は実際のハードウェアとOSルール、ストア要件で動いています。

多くの問題は“ハッピーパス”を外れたときにしか見えないため遅れて発生します。シミュレータはローエンドのAndroidを再現しないかもしれません。デバッグビルドはタイミングの問題を隠すことがあります。ある機能が一画面では問題なく見えても、戻ったときやネットワークが切れたとき、回転したときに壊れることがあります。

遅い驚きはだいたい次の分類に収まります。症状はとても分かりやすいです：

• ナビゲーションと状態の問題：画面がリセットされる、戻るでアプリが終了する、戻ったらデータが消える
• APIの不整合：画面ごとにベースURLやヘッダー、トークンが違い、“ここでは動くが別の場所では失敗する”
• フォーム検証の抜け：サインアップが不正な入力を受け入れる、支払いが黙って失敗する、エラーが期待する場所に表示されない
• 権限トラップ：カメラや通知がOSごとに動いたり動かなかったり、使用目的テキストが欠けて審査で弾かれる
• リリース専用の変化：リリースでのみクラッシュ、資産がない、ディープリンクが壊れる、起動が遅い

簡単なメンタルモデルが役に立ちます。デモは「一度動く」ですが、出荷可能なアプリは「現実の雑多な状況でも動き続ける」です。「完了」は通常、次が成り立つことを意味します：

• 少なくとも1台のAndroidと1台のiPhoneで動く（エミュレータだけでない）
• オフラインや遅いネットワークに対して明確なメッセージと再試行がある
• アプリをバックグラウンドにして戻っても状態が保たれる
• 権限とOSのプロンプトがアプリの実際の動きに合っている
• 実際の鍵や署名、ロギングでリリースビルドが成功する

多くの遅い驚きを防ぐ簡単なセットアップ（ステップバイステップ）

「昨日は動いていたのに」を招くのは、プロジェクトに共有ルールがないことが原因です。vibeコーディングで多くを素早く生成できますが、パーツを噛み合わせるための小さな枠組みは必要です。このセットアップは速度を保ちながら遅い致命的な問題を減らします。

30分で作る基礎

1. 単純な構成を選び、それに従う。 何を画面と呼ぶか、どこにナビゲーションがあるか、誰が状態を所有するかを決めます。実用的なデフォルトは、画面は薄く保ち、状態は機能レベルのコントローラが持ち、データアクセスは一つのデータ層（リポジトリやサービス）を通すことです。

2. いくつかの規約を早めに固定する。 フォルダ名、ファイル名、エラー表示方法に合意しましょう。非同期読み込みのパターン（loading, success, error）を一つに決めると画面の振る舞いが一貫します。

3. 各機能にミニテスト計画を付ける。 チャット生成の機能を受け入れる前に、ハッピーパスと2つのエッジケースを確認するチェックを3つ書きます。例：「ログインは成功する」「パスワード間違いのメッセージが出る」「オフラインなら再試行を表示する」。これで実機でしか出ない問題を捕まえられます。

4. ログとクラッシュ報告のプレースホルダを今入れておく。 すぐに有効にしなくても、ロガーの入口を一つ作り（後でプロバイダを差し替えられるように）、未捕捉エラーを記録する場所を一つ作っておきます。ベータユーザーがクラッシュを報告したとき、痕跡が欲しくなります。

5. 生きた「出荷準備」ノートを持つ。 リリース前にレビューする短い1ページが、直前のパニックを防ぎます。

Koder.aiで作るなら、まず初期のフォルダ構成、共通のエラーモデル、単一のロギングラッパーを生成するよう指示してください。その枠の内側で機能を生成すれば、各画面が独自のアプローチを発明するのを防げます。

出荷準備の定義（短く保つ）

実際に従えるチェックリストを使いましょう：

• API呼び出し失敗から回復してフリーズしない
• コアフローは不正な入力（空欄、無効メール、遅いネットワーク）でも動く
• 権限は必要な時にだけ要求し、拒否された場合にハンドリングがある
• リリースモードでビルドが成功し（デバッグだけでなく）、主要画面をスモークテストする
• 誰かが実機にインストールして説明なしで使える

これは官僚的手続きではなく、チャット生成コードが「一回きりの画面」にならないための小さな合意です。

実機で目に付くナビゲーションと状態の落とし穴

ナビゲーションバグはハッピーパスのデモに隠れがちです。実機では戻るジェスチャ、回転、アプリ復帰、遅いネットワークが入り混じり、「setState() called after dispose()」や「Looking up a deactivated widget’s ancestor is unsafe.」のようなエラーが突然出ます。チャットで作られたフローでは、アプリが画面ごとに成長し、全体設計としては成長しないためこれらが起きやすいです。

電話で感じるバグ

よくある問題は、既に無効になったcontextでナビゲーションを行うことです。これは、Navigator.of(context)を非同期処理の後に呼ぶと、ユーザーが既に画面を離れていたり、回転でウィジェットが再構築されているときに起きます。

もう一つは「ある画面では動く」戻る挙動です。Androidの戻るボタン、iOSのスワイプ戻り、システムの戻るジェスチャは、ダイアログ、ネストしたナビゲータ（タブ）、カスタム遷移を混ぜると違ってくることがあります。

ディープリンクもひとひねりあります。アプリが詳細画面に直接開くとき、コードがホームから来たことを前提にしていると「戻る」で空白ページに行くか、ユーザーが一覧を期待しているのにアプリが閉じてしまいます。

遅い驚きを防ぐ修正

一つのナビゲーションアプローチを選び、それに従ってください。混ぜると最大の問題が生じます：ある画面は名前付きルート、別は直接push、さらに別は手動でスタック管理――ルールを決めて各画面が同じモデルに従うようにしましょう。

非同期ナビゲーションを安全にします。ログイン、支払い、アップロードなど画面より長く生きうるawait呼び出しの後は、状態更新やナビゲーションを行う前に画面がまだ有効か確認してください。

すぐ効くガードレール：

• awaitの後はif (!context.mounted) return;を使ってからsetStateやナビゲーションをする
• dispose()でタイマー、ストリーム、リスナをキャンセルする
• BuildContextを後で使うために保存しない（データを渡す）
• バックグラウンドのコールバックからルートをpushするのは避けるか「ユーザーが離れた」場合を扱う
• ログイン、オンボーディング、チェックアウトなどの各フローでpush、pushReplacement、popをいつ使うかを決める

状態については、回転、テーマ変更、キーボードの開閉で再構築されるとリセットされる値に注意してください。フォームや選択タブ、スクロール位置が大事なら、再構築を越えて生きる場所に保存してください（ローカル変数ではなく）。

フローを「完了」とする前に実機で素早く確認します：

• ダイアログとボトムシートを含めて、各画面からAndroidの戻るを押す
• 主要画面でiOSの戻るスワイプを試す（一覧→詳細、設定→プロフィール）
• 読み込み中に回転してから戻る
• リクエスト中にバックグラウンドにしてから復帰
• 通知やディープリンクから開いて戻る挙動を確認する

Koder.aiや他のチャット駆動ワークフローでFlutterを作るなら、ナビゲーションルールが守りやすい初期段階でこれらをチェックしてください。

APIクライアントの一貫性："ある画面では動く"バグを止める

遅れて壊れる典型例は、画面ごとにバックエンドとのやり取りが微妙に違うことです。vibeコーディングでは頻繁に起きます：一つの画面で「簡単なログイン呼び出し」を頼み、別画面で「プロファイル取得」を頼むと、2つか3つのHTTP設定が生まれてしまいます。

ある画面は正しいベースURLとヘッダーを使っているので動き、別画面はステージングを指していたりヘッダーを忘れたり、トークン形式が違ったりして失敗します。見かけ上ランダムなバグに見えますが、通常は一貫性の欠如です。

“ある画面では動く”を引き起こす落とし穴

よく出るパターン：

• ベースURL、タイムアウト、デフォルトヘッダーが違う複数のHTTPクライアント
• 一貫しないトークンリフレッシュロジックで401ループや黙ったログアウトが起きる
• 画面ごとに違うパースやエラーハンドリングで同じバックエンドエラーが別のメッセージになる
• 動的マップでのパースと型付きモデルが混ざり、あるレスポンスでランタイムクラッシュが起きる

解決：一つのクライアント、一つの契約、一つの失敗パターン

単一のAPIクライアントを作り、全機能でそれを使わせます。そのクライアントがベースURL、ヘッダー、トークン保存、リフレッシュフロー、リトライ（あれば）、リクエストログを管理します。

リフレッシュロジックは一か所に置いて推論しやすくします。リクエストが401なら一度だけリフレッシュしてリクエストを再実行し、リフレッシュに失敗したらログアウトして明確なメッセージを表示します。

型付きモデルは期待以上に役立ちます。成功とエラーのモデルを定義して、サーバが何を返したか推測しないようにします。エラーはアプリレベルの少数の結果（unauthorized、validation error、server error、no network）にマップして、各画面が同じように振る舞うようにします。

ログにはメソッド、パス、ステータスコード、リクエストIDを残し、トークンやパスワード、カード情報を含むペイロードは決して記録しないでください。ボディをログに残す必要があるときは、「password」や「authorization」などのフィールドをマスクしてください。

例：サインアップ画面は成功するが「プロフィール編集」が401ループになる。サインアップはAuthorization: Bearer <token>を送っているのに、プロフィールはtoken=<token>をクエリパラメータで送っていた。単一の共有クライアントにすれば、その不一致は起きず、デバッグもリクエストIDで辿るだけになります。

サインアップや支払い失敗を招くフォーム検証の落とし穴

現実世界の失敗はフォーム内部で起きることが多いです。デモでは問題なく見えても、本当の入力では壊れます。結果は費用がかかります：完了しないサインアップ、チェックアウトを阻む住所欄、曖昧なエラーで失敗する支払いなど。

最もよくある問題は、アプリ側のルールとバックエンドのルールが一致していないことです。UIが3文字のパスワードを許していたり、スペース入りの電話番号を受け入れたり、任意フィールドを必須と扱ったりすると、サーバが拒否します。ユーザーは「何か問題が起きました」とだけ見て再試行し、諦めます。

検証はアプリ全体で共有する小さな契約と考えてください。チャットで画面を生成するなら、バックエンドの制約（最小/最大長、許可文字、必須フィールド、空白トリムなど）を明確に伝えましょう。エラーはフィールドのそばに平易な言葉で表示し、トーストだけに頼らないでください。

もう一つの罠は、iOSとAndroidでキーボードが違う点です。オートコレクトがスペースを入れる、引用符やダッシュが変わる、数値キーボードにプラス記号がない、コピー＆ペーストで不可視文字が入るなど。検証前に入力を正規化（トリム、連続スペースの縮約、ノンブレークスペースの除去）し、通常の入力を罰する厳しすぎる正規表現は避けてください。

非同期検証も遅い驚きを生みます。例：blurで「このメールは既に使われているか」をチェックしているが、ユーザーがSubmitを先に押してページ移動してしまう。エラーがあとから戻り、既に離れたページにエラーが表示されることがあります。

実務で効く対策：

• フォーム状態の一本化（isSubmittingやpendingChecksを追う）
• フォームが有効で非同期チェックが終わるまでSubmitを無効化
• リクエストIDや「最新の値が勝つ」方式で古い非同期応答を無視・キャンセル
• フィールドごとに1つの明確なエラー表示、加えてサーバエラーの短いサマリ

素早くテストするには、ハッピーパスを超えて次の“厳しい”入力を試してください：

• 必須フィールドを空のまま送信
• 境界値（最小長、最大長、1文字オーバー）
• 先頭/末尾に空白があるコピー＆ペースト
• 国際電話番号や非米国住所
• 遅いネットワークでの非同期チェックの遅延

これらが通れば、サインアップや支払いがリリース直前で壊れる可能性は大幅に下がります。

プラットフォーム権限：AndroidとiOSでよくある罠

権限は「昨日は動いていたのに」を生む主要因です。チャット生成プロジェクトでは、機能が素早く追加されプラットフォームルールが見落とされがちです。シミュレータでは動き、本物の電話でしか失敗しない、あるいはユーザーが一度「許可しない」を押してから動かなくなる、ということが起きます。

チームがよく詰まる場所

一つの罠はプラットフォーム宣言の不足です。iOSではカメラや位置情報、写真の使用目的を明確に書く必要があります。曖昧だったり欠けていると、iOSはプロンプトをブロックするか、App Store審査でリジェクトされます。Androidではマニフェストのエントリが欠けている、あるいはOSバージョンに合わない権限を使うと呼び出しが黙って失敗します。

もう一つは権限を一度きりの決定だと扱うことです。ユーザーは拒否したり、後で設定で取り消したり、Androidでは「次回は尋ねない」を選べます。UIが結果を永遠に待っているとフリーズした画面や何もしないボタンが残ります。

OSバージョンごとの挙動差もあります。通知は典型例で、Android 13+ではランタイム許可が必要で古いバージョンは不要です。写真やストレージアクセスも両プラットフォームで変わっています：iOSは「限定写真」があり、Androidは広いストレージではなく新しい“media”権限があります。バックグラウンド位置情報は両方で別カテゴリになり、追加手順とより明確な説明が必要です。

権限は小さな状態機械として扱ってください：

• 機能がトリガーされたときにだけ要求する（起動時に要求しない）
• 拒否されたら短い説明と「再試行」を提供する
• 永続的に拒否されたら設定での有効化方法と安全な代替を示す
• iOSの「限定」はエラーでなく有効な状態として扱う

その後、主要な権限フローを実機でテストします。簡単なチェックリストで大半の驚きを捕まえられます：

• カメラ：カメラを開き、撮る、キャンセル、再試行
• 写真/ストレージ：画像選択、iOSの「限定写真」への対応
• 通知：Android 13+のプロンプト、実際の通知が届くか確認
• 位置情報：使用中とバックグラウンド、iOSの「正確」vs「概算」
• 設定変更：最初に拒否してから設定で有効化し、アプリが回復するか確認

例：チャットで「プロフィール写真をアップロード」を追加し、自分の端末では動いた。しかし新規ユーザーが一度写真許可を拒否するとオンボーディングが続かない。解決は見た目のUIの改善ではなく、「拒否」を通常の結果として扱い、代替（写真はスキップする、後で追加できる）を用意し、機能を使うときだけ再度尋ねることです。

Koder.aiのようなプラットフォームでFlutterコードを生成するなら、各機能の受け入れチェックリストに権限を含めてください。正しい宣言と状態を最初に追加する方が、ストアでのリジェクトやオンボーディングの詰まりを追いかけるより速いです。

リリースビルドの落とし穴：出荷すると何が変わるか

Flutterアプリはデバッグで完璧に見えても、リリースで崩れることがあります。リリースビルドはデバッグヘルパーを取り除き、コードを縮小し、資源や設定に厳格になります。多くの問題はスイッチを切り替えて初めて現れます。

デバッグは動くがリリースでクラッシュする

リリースでは、未使用と見なされたコードやアセットが除去されやすくなります。リフレクションに基づくコード、動的なJSONパース、動的アイコン名、正しく宣言されていないフォントなどが壊れやすいです。

よくあるパターン：起動して最初のAPI呼び出し後にクラッシュする。理由は設定ファイルや鍵がデバッグ専用のパスから読まれているから。別の例は、動的なルート名を使う画面でデバッグでは動くが、リリースではルート参照が無いため失敗することです。

早めにリリースビルドを作って起動直後を観察してください：スタートアップ、最初のネットワークリクエスト、最初のナビゲーション。ホットリロードだけでテストしているとコールドスタートの挙動を見逃します。

フレーバーや環境変数がリリースにない

チームはよく開発用APIでテストして、そのまま本番設定も大丈夫だろうと仮定します。しかしリリースビルドにenvファイルが含まれていなかったり、アプリIDが間違っていたり、プッシュ通知の設定が本番と合っていないことがあります。

ほとんどの驚きを防ぐ速いチェック：

• 実機でリリースビルドをビルドしてインストールする（エミュレータだけでない）
• 各フレーバーの署名と正しいパッケージ名を確認する
• ベースURL、APIキー、アナリティクスフラグが本番値であることを確認する
• クリーンインストールからログイン、ログアウト、トークンリフレッシュをテストする
• ディープリンクとプッシュ通知が正しい画面を開くか確認する

後回しにしていた“遅い作業”がブロッカーになる

アプリサイズ、アイコン、スプラッシュ画面、バージョニングは後回しにされがちで、リリース直前にサイズが大きすぎる、アイコンが荒い、スプラッシュが切れている、バージョン番号がストア要件と違う、などが発覚します。

これらは早めにやっておくべきです：適切なアプリアイコンを設定し、スプラッシュが小さい画面と大きい画面両方で見栄えが良いか確認し、バージョニングのルール（誰がいつ上げるか）を決めます。

提出前に、飛行機モード、遅いネットワーク、完全に殺した後のコールドスタートなどを意図的に試してください。もし最初の画面がネットワーク呼び出しに依存しているなら、明確なローディング状態と再試行が出るべきで、白紙ページは避けてください。

Koder.aiのようなチャット駆動ツールでFlutterを生成しているなら、「リリースビルド実行」を通常のループに入れてください。変更が小さいうちに現実的な問題を捕まえる最速の方法です。

vibeコーディングでよくある12のミス（と回避法）

チャットで作られたFlutterプロジェクトが遅れて壊れるのは、チャットでは小さく見える変更が実際のアプリでは多くの移動部分に触れるからです。これらのミスがクリーンなデモを乱れたリリースに変えます。

1. 状態やデータフロー計画を更新せずに機能を追加する。 新しい画面が同じデータを必要とするなら、コードを貼る前にそのデータの居場所を決める。

2. 選んだパターンに合わない生成コードを受け入れる。 アプリが一つのルーティングスタイルや状態アプローチを使っているなら、別のスタイルを導入する新しい画面は受け入れない。

3. 画面ごとのワンオフAPI呼び出しを作る。 リクエストは単一のクライアント／サービスの背後に置き、微妙に違うヘッダーやベースURLが散らばらないようにする。

4. 問題を見つけた場所だけでエラー処理する。 タイムアウトやオフライン、サーバエラーに対して一貫したルールを決め、画面ごとに推測させない。

5. 警告を無視する。 アナライザのヒント、非推奨、将来的に削除される通知は早期警告です。

6. シミュレータ＝実機と仮定する。 カメラ、通知、バックグラウンド復帰、遅いネットワークは実機で挙動が違います。

7. 新しいウィジェットで文字列、色、間隔をハードコーディングする。 小さな不一致が積み重なり、アプリが継ぎ接ぎに見えます。

8. フォーム検証を画面ごとにバラバラにする。 片方が空白をトリムし、もう片方がしないと「私の端末では動く」が起きます。

9. 機能が「完了」になるまでプラットフォーム権限を忘れる。 写真や位置情報、ファイルが必要な機能は、権限に対する両方の流れでテストが完了するまで未完です。

10. デバッグ専用の挙動に依存する。 ログ、アサーション、緩いネットワーク設定はリリースで消えます。

11. 素早い実験の後のクリーンアップを怠る。 古いフラグ、未使用のエンドポイント、死んだUI枝は後で驚きを生みます。

12. 最終判断の“オーナー”がいない。 Vibeコーディングは速いですが、命名、構造、「これが我々のやり方だ」の決定権は誰かが持つべきです。

速度を保ちつつ混乱を防ぐ実用的な方法は、意味ある変更ごとに小さなレビューを入れることです：

• 新コードがルーティングと状態パターンに従っているか確認する
• API呼び出しが同じクライアントとエラーハンドリングを通っているかチェックする
• アナライザを回して新しい警告を即修正する
• ハッピーパスと1つの失敗パス（オフライン、無効入力、権限拒否）をテストする
• 機能を重ねる前に一回実機で素早く走らせる

例：デモからストア準備まで、全てを書き直さずに進める

小さなチームがvibeコーディングツールとチャットでシンプルなFlutterアプリを作ります：ログイン、プロフィールフォーム（名前、電話、誕生日）、APIから取るアイテム一覧。デモでは全て良く見えます。実機テストを始めると、典型的な問題が一度に出てきます。

最初の問題はログイン直後に出ます。アプリがホーム画面をpushするが、戻るとログインページに戻り、UIが古い画面をチラつかせます。原因は混在したナビゲーションスタイル：ある画面はpush、別はreplace、認証状態が2か所でチェックされていることが多いです。

次はAPI一覧です。一つの画面では読み込めるが別の画面では401が出る。トークンリフレッシュはあるが、1つのAPIクライアントだけが使っている。ある画面は生のHTTP呼び出し、別はヘルパーを使う。デバッグではタイミングやキャッシュで不整合が隠れます。

次にプロフィールフォームがとても人間的に失敗します：アプリがサーバが拒否する電話フォーマットを許している、または誕生日を空で許している。ユーザーは保存を押して一般的なエラーを見て止まります。

権限の驚きも遅れて来ます：iOSの通知許可が最初の起動時に出てオンボーディングの上に表示され、多くのユーザーが先に進むために「許可しない」を押します。重要な更新を見逃すユーザーが出ます。

最後にリリースビルドで動かなくなる。デバッグでは動くがリリースでは壊れる。原因はよくあるのは、本番設定の欠落、異なるAPIベースURL、あるいはランタイムで必要な何かを削除するビルド設定です。アプリはインストールされるが黙って失敗したり挙動が変わったりします。

チームが1スプリントで書き直さずに修正する方法：

• スコープを凍結し、現在のコードをスナップショットとしてエクスポートして、変更をロールバックしやすくする
• 認証状態の一元管理（成功時はログインを置き換えてホームへ）というナビゲーションルールを一つにする
• ヘッダー、リフレッシュ、エラー変換のインターセプタを持つ単一のAPIクライアントに標準化する
• フォームルールをサーバと合わせる（同じ必須項目、同じフォーマット、明確なフィールドエラー）
• 権限プロンプトは必要な瞬間に移し、完全なリリースビルドで検証する

Koder.aiのようなツールは、プランニングモードで反復し、小さなパッチとして修正を適用し、スナップショットでリスクを低く保ちつつ次の変更に進める点で役に立ちます。

出荷前にすぐできるチェックと次のステップ

遅い驚きを避ける最速の方法は、チャットで素早く作った機能でも同じ短いチェックを全てに対して行うことです。多くの問題は「大きなバグ」ではなく、スクリーンが繋がったりネットワークが遅くなったりOSが「ノー」と言ったときにだけ現れる小さな不整合です。

どの機能を「完了」と呼ぶ前に2分間で普段のトラブルスポットを確認してください：

• コールドスタートからその画面に到達でき、戻れるか？ ループはないか？
• 状態は一か所で所有され（毎回再作成されていない）、ナビゲーション後も保たれるか？
• API呼び出しは同じクライアント、ベースURL、ヘッダー、タイムアウトを使っているか？
• フォームは送信前に検証し、明確なメッセージを表示し、読み込み中は二重タップをブロックするか？
• 権限が必要なら「許可」「拒否」両方のフローをテストしたか？

次にリリースに重点を置いたチェックを行います。デバッグでは完璧に見えてリリースで失敗する問題は署名、厳格な設定、権限テキストの欠落などが原因です：

• リリースビルドを作って主要フローをエンドツーエンドでテストする
• 実機2台（古い機種と新しい機種）で画面サイズの違いも含めて確認する
• バージョン、ビルド番号、署名設定が正しいか確認する
• プラットフォームの権限宣言（Androidマニフェスト、iOS Info.plist）を確認する
• バグ申請時は再現手順、端末とOSバージョン、ログ、ネットワーク状態（Wi-Fiかセルラーか）を添える

パッチにするかリファクタにするか：問題が孤立しているならパッチ（1画面、1API、1検証ルール）で良い。三つ以上で繰り返しが見えるならリファクタ（複数クライアント、重複する状態ロジック、ルーティングの不一致）を検討する。

Koder.aiでチャット駆動ビルドをしているなら、大きな変更（状態管理やルーティングの切り替え）前にプランニングモードを使い、スナップショットとロールバックを活用してリスクを管理してください。