夜中に仕掛けた Background Agent のタスクが、朝起きたら途中で止まっていた——そういう経験はありませんか？ 私は何度もあります。しかも「どこで止まったのか」「なぜ止まったのか」がすぐに分からないのが Background Agent の難しいところです。
通常のエージェントセッションなら、エラーが出た瞬間に目の前で確認できます。でも Background Agent は非同期で動くぶん、失敗してもすぐに気づけません。気づいたときには「何時間も何もしていなかった」という状況になっています。
Background Agent が途中で止まる原因を5つに整理して、それぞれの診断方法と具体的な対処法を順を追って整理していきます。
なぜ Background Agent は止まるのか
原因の見当をつけずに「もう一回やり直せばいいか」で済ませていると、同じことが繰り返されます。止まる理由はほぼ次の5つのどれかです。
- セッションタイムアウト: 処理時間が上限を超えた（目安は2〜3時間）
- コンテキスト枯渇: AIのコンテキストウィンドウが満杯になってタスクを継続できなくなった
- ネットワーク切断: PCのスリープ・Wi-Fi再接続・VPN切断でAPI通信が途絶えた
- ファイル競合: 自分やGitが編集中のファイルにエージェントが書き込もうとして競合した
- エラーループ脱出失敗: 同じエラーを何度も繰り返してエージェントが自動停止した
この中で最も遭遇頻度が高いのは「セッションタイムアウト」と「コンテキスト枯渇」の2つです。次いで「ネットワーク切断」が多く、この3つを対策するだけで未完走の大半はなくなります。
診断: どこで止まったかを確認する
Background Agent が止まった後、まずサイドパネルのエージェントスレッドを開いてください。確認するポイントは3つです。
[確認手順]
1. 最後のメッセージ内容 → 何をしようとして止まったか
2. エラーメッセージの有無 → 赤字で表示される場合は原因特定が早い
3. タイムスタンプ → いつ止まったかで原因の絞り込みができる
最後のメッセージが「I've been working on...」で途切れている場合はタイムアウトの可能性が高いです。「Context length exceeded」や「Token limit」に近い文言が出ていればコンテキスト枯渇、同じエラーメッセージが繰り返されていればエラーループです。
また、git log で最後のコミットタイムスタンプを確認すると、「どこまで完了していたか」が把握できます。これを確認するだけで、次のリトライをどこから始めれば良いかが分かります。
対処法1: タイムアウトを回避するタスク分割
Antigravity の Background Agent にはセッション継続時間の上限があります。公式には明記されていませんが、経験上2〜3時間を超えるタスクは要注意です。大規模リファクタリングや全テスト生成のような「とにかく全部やって」系の指示は、タイムアウトで止まりやすい筆頭です。
対処法はシンプルで、タスクをマイルストーン単位に分割することです。
# 良い例（フェーズ分割）
「フェーズ1: src/api/ 以下のエラーハンドリングを統一して、
完了したら git commit してください。それだけで終わりです。」
# 悪い例（範囲が広すぎる）
「src/ 以下全体のコードを読んでリファクタリングして、
テストも書いて、ドキュメントも更新してください。」「全部やって」という指示より「フェーズ1だけやって」という指示の方が確実に完走します。私がテストカバレッジ向上を任せるときは必ずフェーズ分けするようにしてから、未完走はほぼゼロになりました。
フェーズをまたぐ場合は、前のフェーズのコミットログに「次のフェーズで何をすべきか」を残しておくと、次のエージェントへの引き継ぎがスムーズになります。
対処法2: コンテキスト枯渇を防ぐスコープ指定
大きなコードベースで作業させると、AIがプロジェクト全体を把握しようとしてコンテキストを消費しすぎてしまいます。これを防ぐには、どのファイル・ディレクトリだけを対象にするかを最初から明示することが効果的です。
# 良い例（スコープを明示）
「src/components/Button/ 以下のファイルだけを対象に、
props の型定義を整理してください。
他のディレクトリには手を触れないでください。」
# 悪い例（AIが全ファイルを読もうとする）
「プロジェクト全体を読んで、型定義を整理してください。」
また、AGENTS.md に「このプロジェクトで頻繁に参照するファイルのパス」や「設計上の注意点」を書いておくと、AIが毎回ファイルを探し回る手間が省けてコンテキストの節約になります。AGENTS.md を使ったコンテキスト管理についてはコンテキストドリフト問題の診断と修正も参考にしてください。
対処法3: ネットワーク切断への備え
Background Agent がAPIと通信できなくなると、タスクはその時点で中断されます。PCをスリープさせたり、Wi-Fiが一時的に切れたりするだけで起きます。長時間タスクを夜間に走らせる場合は特に注意が必要です。
macOS でスリープを防止する一番シンプルな方法はターミナルからの caffeinate コマンドです。
# PCのスリープを防止（Ctrl+C で解除）
caffeinate -i &
# Background Agent の実行時間に合わせてタイマーを設定する場合
# 例: 3時間スリープを防止
caffeinate -i -t 10800 &ただし、それより根本的な対処法はコミット駆動設計です。チェックポイントごとにコミットさせておけば、途中で切断されても「どこまで完了したか」がgit logで分かり、次のセッションで続きから再開できます。
# AGENTS.md に書く例
## コミットポリシー
- 各機能の実装完了後に必ずgit commitを実行すること
- コミットメッセージ形式: "agent: [完了した作業内容]"
- 1コミットに含めるファイル変更は10ファイル以内対処法4: ファイル競合を防ぐブランチ戦略
Background Agent が動いている間に自分でファイルを編集すると、書き込み競合が発生することがあります。「エージェントに任せながら自分も開発したい」という場合に起きやすいです。
最もシンプルな解決策は、Background Agent に専用ブランチで作業させることです。
# Background Agent への指示例
「feature/refactor-auth という新しいブランチを作成して、
そのブランチ上で src/auth/ 以下のリファクタリングを実施してください。
main ブランチには一切手を触れないでください。」こうすることで、自分はmainブランチで安全に別の開発を進めながら、Background Agentはfeatureブランチで作業できます。完了したらPRとしてマージするだけです。Background Agentをより安全に活用する方法はBackground Agent 本番運用ガイドで詳しく解説しています。
対処法5: エラーループに出口条件を設ける
Background Agentが同じエラーを繰り返し続けて止まらない——これは地味につらい問題です。何時間後に確認してもひたすらリトライしていたり、逆に自動停止してすべての作業が消えていたりします。
対処法は、最初の指示に「エラーが繰り返された場合の撤退条件」を明示することです。
# Background Agent への指示例
「もし同じエラーが3回以上連続して発生した場合は、
それ以上リトライせずに作業を中断してください。
その際、発生したエラーの詳細と最後に試みた修正内容を
agent-debug-notes.md というファイルに書き出してから終了してください。」この「出口条件」を明示するだけで、翌朝「エラーが50回繰り返されていた」という状況を防げます。書き出されたデバッグノートを見れば、何が詰まっていたかもすぐ分かります。AI エージェントのエラーリカバリ設計パターンも参考になります。
原因が分からないときの確認フロー
止まった理由がどうしても特定できないときは、この順番で確認してください。
1. エージェントスレッドの最後のメッセージを読む
→ タイムアウト / コンテキスト枯渇 / エラーループのどれかが大半
2. git log で最後のコミット時刻を確認
→ 「いつまで正常に動いていたか」が分かる
3. git diff HEAD で未コミットの変更を確認
→ 何に手を付けていたかが分かる
4. ターミナルログを確認
→ ネットワークエラーやファイルアクセスエラーが残っていることがある
この4ステップで、原因のほぼ全てが特定できます。
今日試してほしい2つの改善
Background Agent の未完走を完全にゼロにするのは難しいですが、頻度は大幅に下げられます。まずは今日、次の2点だけ試してみてください。
- 長時間タスクを90分以内のフェーズに分割して、各フェーズの終わりにコミットさせる
- AGENTS.md に「同じエラーが3回続いたら中断してデバッグノートを残す」と書く
この2つを実践するだけで、Background Agent の完走率はかなり改善するはずです。Background Agent 入門ガイドでまだ使ったことがない方は、まずそちらで基本的な使い方を確認してからお試しください。