Antigravity を使い込んでくると、必ずぶつかる壁があります。
AIがコードを生成してビルドエラーが出た。とりあえず Retry してみる。また同じエラー。もう一度 Retry。3回目も同じ結果——。この繰り返しに費やした時間を振り返ると、なんとなく「もっと早く別のアプローチを取るべきだった」と気づくことが多いのではないでしょうか。
Retry は便利な機能ですが、万能ではありません。むしろ「Retry すべき状況」と「即座に方針転換すべき状況」を見極めることが、Antigravity を使いこなす上で最も重要なスキルの一つだと思っています。ここではその判断基準を具体的なケースとともにお伝えします。
Retry が本当に効く状況
まず前提として、Retry が有効に機能するケースを整理しておきましょう。
一時的な外部要因によるエラーが最も典型的です。Gemini API への接続が一時的にタイムアウトした、レート制限（429エラー）に引っかかった、ネットワークが不安定だった——これらはリトライすれば解決することがほとんどです。エラーメッセージに rate limit、timeout、network error、temporarily unavailable などのキーワードが含まれている場合は、Retry の第一候補です。
非決定論的な失敗も Retry に向いています。たとえばフロントエンドの E2E テストで、特定の DOM 要素が表示されるタイミングのズレで偶発的に失敗するケース。あるいは AI が生成するコードが毎回わずかに異なるため、別のアプローチで正解に近づく可能性があるケース。「同じ条件でも違う結果になりうる」状況では、Retry は合理的な選択です。
リソースの競合も同様です。ポートが一時的に使用中だった（EADDRINUSE）、ファイルロックが解除されていなかった、など。少し時間をおいて Retry するだけで解決することがよくあります。
# 一時的なポート競合エラーの例
Error: listen EADDRINUSE: address already in use :::3000
# これは Retry より先にプロセスを確認するほうが確実
lsof -i :3000 | grep LISTEN
kill -9 $(lsof -t -i :3000)Retry しても解決しない状況のサイン
問題は、「解決しないのに Retry を続けてしまう」パターンです。以下のサインが出たら、Retry より先にやるべきことがあります。
まったく同じエラーが 2 回連続で出た場合は、3 回目を試す前に立ち止まってください。同じ入力に同じ処理をしても、同じ出力が返るのは当然です。ランダム性のないエラーは、Retry では解決しません。
エラーの内容が論理的な問題を示している場合も同様です。
// このようなエラーは Retry しても変わらない
Type 'string' is not assignable to type 'number'.
// あるいは
Cannot find module './userService' or its corresponding type declarations.型エラーや import エラーは、コードの構造そのものに問題があります。AI がどんなに「Retry」しても、型定義が間違っていれば同じエラーが出続けます。
AI が毎回異なるファイルを変更しているのに同じエラーが続く場合は、根本原因の特定ができていないサインです。このような状況では、Retry ではなく「AI にどの情報を与えるか」を変える必要があります。
「3 回の法則」と方針転換のタイミング
経験則として、私は同じアプローチで 3 回 Retry して改善が見られなければ、必ず方針を変えるようにしています。
この数字に厳密な根拠があるわけではありませんが、理由はシンプルです。非決定論的なエラーであれば 2〜3 回で解決することが多い。逆に 3 回試して変わらなければ、それは「確率の問題」ではなく「構造の問題」である可能性が高い。
方針転換のアプローチとしては、主に 3 つがあります。
① コンテキストを変える
Antigravity はチャットの文脈を積み上げながら処理します。エラーが続く場合、過去の不正確な情報が文脈に残っていることがあります。新しいチャットを開始して、エラーの内容と関連ファイルだけを渡し直すことで、クリーンな状態から診断してもらうのが効果的です。
# 新しいチャットで試す場合の伝え方の例
以下のエラーが出ています：
[エラーメッセージをそのまま貼り付け]
関連するファイルはこれです：
[src/lib/userService.ts を @ファイル参照で指定]
このエラーの根本原因を特定して、修正案を 1 つだけ提示してください。
② モデルを切り替える
Antigravity では使用するモデルを切り替えられます。特定のエラーに対して Gemini 2.5 Pro が苦手なアプローチを取り続けている場合、Gemini 3 Flash に切り替えると別の視点で解決策を提示してくれることがあります。
③ 問題を分解する
「ビルドエラーを直して」という大きな指示より、「まずこのファイルの型エラーだけを直して」という小さな単位に分解する方が、AI は正確に動きます。問題が複雑なほど、粒度を細かくすることが解決への近道です。
Plan Mode を活用したエラー診断フロー
Retry が効かない状況で特に役立つのが、Antigravity の Plan Mode です。
修正を試みる前に Plan Mode で「このエラーの根本原因は何か？考えられる原因を全て列挙して」と尋ねると、AI がコードベース全体を確認した上で仮説をリストアップしてくれます。このリストを確認してから実行フェーズに移ることで、無駄な Retry を大幅に減らせます。
# Plan Mode での効果的な使い方
1. Plan Mode を有効にする
2. 「このエラーの原因として考えられるものを全て挙げてください。
修正はまだしないでください」と入力する
3. 原因リストを確認し、最も可能性が高いものを選ぶ
4. 「[特定の原因] を修正してください」と指示する
5. Plan Mode を解除して実行
Antigravity の Retry 機能が強力なのは事実です。しかしそれは「一時的な失敗を乗り越えるため」のツールであり、「根本的な問題を無視して先に進むため」のツールではありません。
エラーが続いているとき、立ち止まって「これは Retry すべき問題か、それとも根本修正が必要な問題か」を自問する習慣をつけると、開発速度は確実に上がります。
まず今日試してほしいのは、次に Retry を押す前に 5 秒だけエラーメッセージを読むことです。「外部の一時エラーか、ロジックの問題か」——その判断だけで、無駄な時間を大きく削減できます。