Antigravity でコンテキスト上限に達したときの症状・原因・回復手順

Antigravity を使って大きめのコードベースを触っているとき、「なぜかエージェントが以前の指示を忘れてしまう」「返答が短くなってきた」「突然エラーが出てセッションが終わった」という経験をした方は少なくないと思います。

こうした現象の多くは、コンテキストウィンドウ（モデルが一度に処理できる情報の範囲）の上限に達していることが原因です。エラーメッセージが出る場合はすぐ気づけますが、エラーなく「じわじわと品質が落ちる」タイプの症状は見逃しやすく、「自分の使い方が悪いのかな」と悩んでしまうこともあります。

ここではコンテキスト上限に関連する症状の見分け方と、実際に上限に達したときの具体的な回復手順をお伝えします。

コンテキスト上限エラーの症状と見分け方

コンテキスト上限に達したときに現れる症状は大きく2種類に分かれます。

明示的なエラーメッセージが出る場合

会話の途中で以下のようなメッセージが表示されます。

Context length exceeded. Please start a new conversation or reduce the context.

または Gemini API のエラーとして：

400 INVALID_ARGUMENT: Request payload size exceeds the limit

症状が「じわじわ」現れる場合

エラーメッセージなしに次のような変化が起きます。

会話の前半で決めた命名規則やアーキテクチャをエージェントが無視し始める
「さっき実装したあの関数のことです」という参照が通じなくなる
応答が突然短くなる、または途中で終わる
コードの一貫性が失われ、以前と異なるライブラリのインポートを提案してくる

この後者のパターンを「エージェントの品質低下」や「バグ」と誤解しがちです。しかし実態は、モデルが「会話の最初のほうの情報」を処理しきれなくなっているサインです。

接続エラーとの区別

接続エラーは「Network Error」「タイムアウト」「サーバーに接続できません」といったネットワーク関連のメッセージで現れます。コンテキスト上限エラーはモデル側の制限なので、ネットワークを再接続しても解決しません。新しいチャットを開始して問題が消えた場合は、コンテキスト上限が原因です。

即時対処法：新しい会話を効率よく再開する

最も確実な回復手順は、新しいチャットセッションを開始することです。Cmd/Ctrl + N またはサイドバーの「+」ボタンで新しい会話を作成できます。

ただし、単純に新しいチャットを開いて「続きをお願いします」と伝えるだけでは、前の会話のコンテキストが引き継げません。かといって会話履歴をまるごとコピーすると、またすぐに上限に達してしまいます。

そこで活用したいのが「コンテキスト要約」の手法です。作業中の情報を100〜300字程度に凝縮して、新しい会話の冒頭に貼ります。

## 作業中のプロジェクト
Next.js 15 + TypeScript + Supabase の SaaS アプリ
 
## 現在のタスク
/src/app/api/auth/route.ts の JWT リフレッシュ処理を修正中
 
## これまでの決定事項
- Middleware ではなく Route Handler でセッション管理を統一する方針
- Supabase の RLS はサーバーコンポーネント側で明示的に確認する
 
## 次のやること
handleRefreshToken 関数のエラーハンドリングを try/catch に置き換える

「プロジェクトの概要・現在のタスク・決定済みの方針・次のアクション」の4点を整理するだけで、新しいチャットでもほぼ瞬時に作業を再開できます。

この要約を「会話の途中で困ったとき用のテンプレート」として手元に用意しておくと、コンテキスト上限が来ても慌てずに済みます。

@ファイル参照の使い方を改善する

コンテキスト上限に頻繁に達する場合、@ファイル参照 の使い方に改善の余地があることが多いです。詳細な使い方については Antigravity の @参照機能を使いこなす：コンテキスト精度を上げる実践ガイドにまとめていますが、ここではトークン節約に直結するポイントを紹介します。

トークンを使いすぎる参照の例

# ❌ ディレクトリ全体を参照（大量のファイルが一度に読み込まれる）
@src/
 
# ❌ 関係のない大きなファイルを複数同時に参照
@src/lib/utils.ts @src/types/global.ts @src/app/layout.tsx @src/components/Nav.tsx

トークンを節約する参照の例

# ✅ 必要なファイルだけ、必要な文脈と一緒に渡す
「@src/app/api/auth/route.ts を見てください。
  handleRefreshToken 関数のエラーハンドリングを改善したいです。」
 
# ✅ 「どの部分を見てほしいか」を明示する
「@src/components/Button.tsx の disabled 状態の CSS クラスだけを修正してください」

「このファイル全体を見てください」ではなく「このファイルの ○○ の部分だけ見てください」と伝えることで、消費トークンを大幅に削減できます。大きなファイルを渡すときほど、この一手間が効いてきます。

.antigravityignore で不要ファイルをコンテキストから除外する

Antigravity はプロジェクトのファイルを自動でインデックス化し、関連しそうなファイルをコンテキストに含めます。.antigravityignore ファイルを使うと、特定のディレクトリやファイルをこのインデックスから除外できます。

詳しい設定方法は .antigravityignore 完全ガイド — 除外設定でコンテキストを最適化するを参考にしてください。コンテキスト上限対策として特に効果的な設定を以下に示します。

# .antigravityignore（プロジェクトルートに配置）
 
# ビルド成果物（必ずコンテキストから除外する）
.next/
dist/
build/
out/
 
# テストのスナップショットファイル（肥大化しやすい）
__snapshots__/
*.snap
 
# 大容量データファイル
data/
*.csv
*.json.bak
 
# ドキュメント（必要なときだけ @参照 で渡す）
docs/
 
# ログファイル
logs/
*.log

設定後はウィンドウをリロード（Cmd/Ctrl + Shift + P → 「Reload Window」）することで反映されます。

モノレポや大規模プロジェクトでは、関係のないパッケージディレクトリを除外するだけでも大きな効果が出ることがあります。

繰り返しを防ぐためのワークフロー

コンテキスト上限に繰り返し悩まされる場合、タスクの粒度が大きすぎる可能性があります。

Antigravity エージェントは「全機能を実装して」という大きなタスクよりも、「この API エンドポイントを1つ実装して」「このコンポーネントのバリデーションを追加して」という小さなタスクを繰り返す方が、コンテキストを効率よく使えます。

特に大きなリファクタリングや機能追加に取り組む場合は、Antigravity の計画モードと高速モードを使い分ける実践ガイドで紹介されている「計画フェーズ → 実装フェーズ」の切り替えが効果的です。

具体的には次のような流れです。

まず「この機能の実装計画を立てて」とエージェントに依頼し、タスクを分解してもらう
その計画をメモか README に保存する
新しい会話を開き「ステップ1から実装します。計画はこれです：○○」と始める
各ステップが終わったら会話を区切り、次のステップに進む

このリズムを身につけると、コンテキスト上限に悩む頻度は大きく下がります。また、ステップごとに会話が分かれているため、どのステップで問題が起きたかも特定しやすくなります。

コンテキスト制限はどのAI IDEでも必ず直面する壁ですが、回復手順とワークフローを身につければ作業効率はむしろ上がります。まずは今日の作業で参照するファイルを1〜2個に絞ることから試してみてください。それだけで、体感できる変化があるはずです。