Antigravity の Retry 機能を使いこなす — エージェントが詰まったときの賢いやり直し方

エージェントを動かしているとき「あ、また同じところで止まった」と Retry ボタンを連打してしまった経験はありませんか。私自身、Antigravity を使い始めた最初の数日で、同じタスクを4回続けて Retry して結局同じエラーに終着するという、なかなかに不毛な時間を過ごしました。

Antigravity の Retry はただの「やり直しボタン」ではなく、3つの異なるモードがあります。どのモードが今の状況に適しているのかを判断できるようになると、無駄な API コール（クレジット消費）も減り、開発のテンポが目に見えて変わります。

ここではRetry が「魔法のリカバリ機能」ではなく「条件付きで効く道具」であるという前提のもと、私自身が現場で詰まりながら身につけた使い分けを共有します。

Retry が効く失敗・効かない失敗

最初に押さえておきたいのは、Retry を押せば直る失敗とそうでない失敗があるという事実です。これを理解しないまま Retry を連打すると、クレジットを溶かしながら同じ場所で止まり続けることになります。

Retry が効くのは、以下のような「一時的・確率的な要因による失敗」です。

API のレート制限やタイムアウト（時間を空けて再試行）
LLM の出力ブレ（同じプロンプトでも結果が揺れるケース）
依存パッケージの一時的なダウンロード失敗
ネットワークの瞬断

逆に、以下のような「決定論的な失敗」は何度 Retry しても結果は変わりません。

プロンプトの指示が曖昧で、エージェントが意図を取り違えている
必要なファイルが agents.md などのコンテキストに含まれていない
TypeScript の型エラーなど、構造的に解決不能な問題
API キーの未設定や権限不足

「直近1時間で同じ Retry を3回以上失敗している」場合は、Retry を一旦止めて、原因の切り分けに移った方が結果的に速いです。

Retry の3つのモードと使い分け

Antigravity の Retry にはいくつかの選択肢があります。エージェントタスク失敗時のメニューから選べる主なモードは以下の3つです。

1. Quick Retry（同じ条件で再実行）

そのまま「Retry」を選んだときの挙動です。プロンプトもコンテキストも変えずに、もう一度走らせます。

向いている場面: API タイムアウト、レート制限、ネットワーク瞬断
向かない場面: プロンプト解釈の問題、依存関係の不足

2. Edit & Retry（プロンプトを修正して再実行）

失敗したタスクのプロンプトを直接編集してから再実行できます。私が一番よく使うのはこのモードで、エージェントの出力ログを見て「ああ、ここを誤解しているな」と分かったときに、その箇所だけを足したり直したりします。

向いている場面: 指示が曖昧で意図が伝わらないケース、対象ファイルが不明確なケース
向かない場面: そもそもの設計が間違っているケース（その場合は新しいタスクを作り直す方が早いです）

3. Retry from Checkpoint（チェックポイントから再実行）

Antigravity は長いタスクを実行している途中、内部的にチェックポイントを保持しています。途中まで進んでいたが後半で失敗した、というケースで「成功した最後のステップ」から再開できます。

向いている場面: マルチステップタスクの後半でエラーになったとき
向かない場面: 序盤の前提が崩れている場合（最初からやり直した方が良いです）

3つのモードを意識的に選ぶようになるだけで、同じ Retry でも体感的な解決速度が大きく変わります。

失敗ログから原因を読み取る最短ルート

Retry を押す前に、私はだいたい30秒くらいログを眺めます。30秒というのは「全部読む」のではなく「キーワードだけ拾う」時間です。

特に注目すべきキーワードは以下の通りです。

429 / rate limit / timeout → 一時的な要因。Quick Retry が効く可能性が高い
cannot find module / not found → 依存解決の問題。Retry より npm install などの確認が先
unexpected token / syntax → コードの構造的問題。Edit & Retry でプロンプトを補強
permission denied / unauthorized → 認証の問題。Retry しても直らない

ここで重要なのは「ログの最後の数行だけ読む」習慣です。エラーの本当の原因はだいたい最後に出ています。スクロールを上に戻して大量のログを読み返すよりも、最後の10行を確実に読む方が明確に効率的です。

簡単な確認用のスクリプトとして、私はこんなシェル関数を ~/.zshrc に入れています。Antigravity の出力をファイルにリダイレクトしているとき、最後の数行を素早く確認できます。

# 直近のエージェントログから「最後のエラー行」を抽出
# 使い方: agentlog ~/agent-output.log
agentlog() {
  local log_file="${1:-./latest-agent.log}"
  if [ ! -f "$log_file" ]; then
    echo "ログファイルが見つかりません: $log_file"
    return 1
  fi
  echo "=== 最後の20行 ==="
  tail -n 20 "$log_file"
  echo "=== エラー行のみ ==="
  grep -iE "error|fail|exception|denied" "$log_file" | tail -n 5
}
# 期待出力:
# === 最後の20行 ===
# (タスクログの最後)
# === エラー行のみ ===
# Error: ECONNRESET
# Error: timeout after 30000ms

たったこれだけでも、Retry の前にやるべきことが見えてきます。

Retry を使う前にやっておくべき3つの準備

毎回ゼロから Retry の判断をするのは脳のリソースを消費します。私は次の3つを「Retry 前のルーチン」として固定しています。

第一に、コンテキストの最新化です。Antigravity のエージェントは agents.md やプロジェクトのファイルを参照して動きますが、長いセッションで会話を続けていると、エージェントの記憶が古いままになっていることがあります。Edit & Retry の前に、最新の状態をプロンプトに含めることを意識しています。

第二に、検証用の最小プロンプトを別タスクで試すことです。失敗しているタスクが大きい場合、そのまま Retry すると毎回大量の API コールが走ります。同じ問題を再現できる最小のプロンプトを別タスクで投げると、Retry のコストを大幅に下げられます。

第三に、モデルの切り替えを検討することです。Gemini で詰まっていたタスクが、ローカルの Gemma 4 で動かすとあっさり通った、ということが何度かありました。逆もまた然りで、Gemma 4 で曖昧になっていた指示を Gemini に切り替えると一発で解決することもあります。詳しくは Antigravity と Gemma 4 でローカル LLM を統合する完全ガイドを参考にしてみてください。

AI エージェントを使う時代でも、結局のところ読みやすいログ・読みやすいコードが Retry の精度を上げてくれます。

Retry を最終手段にしないためのワークフロー

最後に、私が実務で意識している「Retry そのものを減らす」工夫を共有します。Retry は便利ですが、毎回 Retry に頼っているということは、上流の設計が雑になっている可能性が高いです。

タスクを小さく区切る習慣はかなり効きます。1つのタスクで「ファイルを5個生成して、テストを書いて、デプロイまで」と欲張ると、どこで失敗してもやり直しのコストが大きくなります。私の感覚では、「1タスク = 5〜10分で完了する単位」に分けると、失敗時のリカバリが格段に楽になります。

また、Retry が失敗した直後に冷静になる時間を意図的に作るのも効果的です。3回連続で同じ場所で失敗したら、私は一度 Antigravity を閉じて、ノートに「いま何が起きているのか」を手書きで書き出します。タイピングではなく手書きが意外と効きます。これだけで、見えていなかった前提を発見することがあります。

エージェント運用の落とし穴をもう少し系統的に学びたい方は、Antigravity でエージェントが無限ループする問題の対処法や Antigravity のクレジット消費を最適化するコスト戦略も合わせて読んでみてください。Retry とコスト最適化は、実は同じ問題の表と裏の関係にあります。

今日からできることを1つだけ挙げるなら、「Retry を押す前に必ずログの最後の10行だけ読む」を習慣にしてみてください。それだけで、無駄な Retry が半分以下になるはずです。それでも詰まる失敗に出会ったとき、改めてこの記事に戻ってきていただけたら嬉しく思います。