先月、画面遷移の実装を任せたエージェントが、同じテストの手前で止まりました。私は Retry を押し、また止まり、もう一度押し——気づけば4回目で、クレジットの残りだけが静かに減っていました。胃のあたりが重くなったのを覚えています。
4回目に押す前、ようやくログの最後の数行を読みました。出ていたのは cannot find module で、押すべきだったのは Retry ではなく、依存の確認だったのです。
最初にお伝えしたいのは、Retry は「やり直しボタン」ではなく「確率的な失敗にだけ効く道具」だということです。以下では、効く失敗と効かない失敗の見分け方、状況別の使い分け、押す前の3つの確認を、私の運用に沿って書き残します。
なお、Retry まわりのメニュー名や選択肢はバージョンや画面によって異なります。ここで挙げる「同じ条件で再実行」「プロンプトを直して再実行」「途中から再開」は、私の環境で使い分けている考え方の区分であり、公式の固定名称ではありません。お使いの画面に出ている選択肢へ読み替えてください。
Retry が効く失敗・効かない失敗
Retry で直るのは、実行のたびに結果が揺れる種類の失敗です。
- API のレート制限やタイムアウト
- LLM の出力ブレ（同じ指示でも成否が分かれるケース）
- 依存パッケージの一時的なダウンロード失敗
- ネットワークの瞬断
一方、何度押しても結果が変わらない失敗があります。
- 指示の曖昧さによる、意図の取り違え
agents.mdなどの参照範囲に、必要なファイルが未登録- 型エラーなど、コード側の構造的な問題
- API キーの未設定や権限不足
もう一つ、見落としやすい中間のパターンがあります。ネットワークの瞬断で依存のインストールが途中で止まり、プロジェクトが半端な状態で残ると、最初の原因は一時的でも、その後の失敗は毎回同じかたちで再現されます。この場合は、Retry の前に状態を戻すのが先です。
目安として、同じタスクを1時間のうちに3回続けて失敗したら、Retry は止めます。4回目に違う結果が出る理由が、ログのどこにも見当たらないからです。
状況別の使い分け
同じ条件でそのまま再実行する
プロンプトも参照ファイルも変えずに、もう一度走らせる使い方です。
- 向いている場面: タイムアウト、レート制限、ネットワークの瞬断
- 向かない場面: 指示の解釈違い、依存関係の不足
プロンプトを直してから再実行する
私がいちばん使うのはこちらです。ログを読んで「ここを誤解している」と分かったら、その1か所だけを足します。
直すときは、1〜2文の追記にとどめています。全文を書き換えてしまうと、どの変更が効いたのか分からなくなり、次の失敗に持ち越せる学びが残らないからです。小さな修正を積み重ねたほうが、自分用の手引きとしてはるかに育ちます。
- 向いている場面: 曖昧な指示、対象ファイルの未指定、完了条件の不足
- 向かない場面: そもそもの設計が違うとき（新しいタスクに切り替えます）
成功した途中の段階から再開する
画面に途中再開の選択肢が出る場合、長いタスクの後半で失敗したときに役立ちます。1〜4番目の手順が通り、5番目で止まったなら、5番目だけをやり直したいからです。ただし、再開の単位や保持される範囲は、お使いのバージョンの挙動を一度確かめてから頼ってください。私は、前半の方針自体が怪しいときは再開せず、最初から組み直しています。
- 向いている場面: 複数手順のタスクの後半での失敗
- 向かない場面: 序盤の前提が崩れているとき
失敗ログは最後の10行から読む
Retry を押す前に、私はログを30秒だけ眺めます。全部を読むのではなく、キーワードを拾う時間です。
| ログのキーワード | 見立て | 最初にやること |
|---|---|---|
429 / rate limit / timeout | 一時的な要因 | 間隔を空けて再実行 |
cannot find module / not found | 依存の解決漏れ | インストール状態を確認 |
unexpected token / syntax | コードの構造的な問題 | プロンプトに制約を足して再実行 |
permission denied / unauthorized | 認証・権限 | キーと権限を直す（再実行は後） |
エラーの本当の原因は、たいてい最後の方に出ています。スクロールを遡って数百行を読み直すより、末尾の10行を確実に読むほうが速いのです。
もう一つ、どの段階で止まったかも手がかりになります。3つのファイルを書き終えてテストで落ちたなら、問題はテスト環境の周辺に限られていることが多く、最初の操作で落ちたなら、指示か参照範囲が最初から噛み合っていません。
出力をファイルにリダイレクトして長いタスクを回すときは、次のシェル関数を ~/.zshrc に入れています。
# 直近のエージェントログから「最後のエラー行」を抽出
# 使い方: 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つの確認
毎回ゼロから判断するのは消耗します。そこで、次の3つを決まった手順にしています。
1つ目は、コンテキストの更新です。長いセッションでは、エージェントの見ている情報が古いままになりがちです。全文を貼り直すのではなく、ファイルのパスを示し、前回から変わった点を1文だけ添えます。たとえば「db/schema.ts に deletedAt 列が加わりました」のような一文です。
2つ目は、小さな再現タスクの作成です。失敗しているタスクが大きいほど、Retry のたびに消費が膨らみます。同じ症状を再現する最小のタスクを別に立てれば、消費を大きく抑えたまま原因を絞れます。
3つ目は、モデルの切り替えです。Gemini で通らなかったものがローカルの Gemma 4 で通ったことも、その逆もありました。誤解しやすい箇所がモデルごとに違うのだと思います。ローカル側の構成は Antigravity と Ollama・Gemma によるローカル LLM ルーティング設計 にまとめています。
Retry を減らすための設計
Retry を頻繁に使っているなら、上流の設計に原因があることが多いです。
効果が大きいのは、タスクを小さく切ることです。「5ファイルを生成し、テストを書き、デプロイまで」と欲張ると、失敗の候補が5つあるのに、やり直しは1回で全部になります。私は、5〜10分で終わる単位を目安にしています。
次に、各タスクの冒頭へ目標を1行だけ置く習慣です。たとえば「旧認証ミドルウェアをセッション方式へ置き換える。利用者の挙動は変えない」という一行です。Retry が続くとき、エージェントの解釈がこの一行と合っているかを見比べると、半分くらいは解釈のずれでした。そこで押すべきは Retry ではなく、指示の修正です。
そして、同じ場所で3回続けて失敗したら、Antigravity を一度閉じて、状況をノートに手書きします。タイピングでは出てこなかった「見落としていた前提」が、ペンだと不思議と浮かんできます。
同じ問題を隣の角度から見たい方は、Antigravity でエージェントが無限ループする問題の対処法 と Antigravity のクレジット消費を最適化するコスト戦略 も参考になります。Retry の精度とクレジットの節約は、表と裏の関係にあります。
押す前に末尾の10行を読む。それだけで、Retry は祈りから判断に変わります。
次に Retry を押したくなったら、まずログの最後の10行だけを開いてみていただければと思います。