Antigravity で大きなファイルを AI が処理できない——コンテキスト制限の壁を越える実践的対処法

開発中に「さっきまで普通に動いていた AI が、急に的外れな提案をし始めた」という経験はないでしょうか。指示した関数とは全く違う箇所を触り始めたり、ファイルの後半部分を完全に無視したりします。そういうとき、多くの場合 Antigravity のバグを疑いがちですが、実はコンテキストウィンドウの制限に達しているケースがほとんどです。

ここでは大きなファイルで AI が正しく動作しなくなる原因を整理し、実際に効果のある対処法を順番に紹介します。

なぜ大きなファイルで AI が失敗するのか

Antigravity が内部で使用している Gemini 2.5 Pro をはじめとする大型モデルは、非常に大きなコンテキストウィンドウを持っています。しかし「大きい」と「無制限」は別物です。チャット会話が長くなるにつれ、あるいは巨大なファイルを丸ごと読み込ませると、モデルはトークン制限に近づきます。

このとき AI は「読めていないことを正直に報告する」のではなく、後半の情報を静かに圧縮・省略して処理を続けます。その結果、ファイルの前半だけを参照した「不完全な理解」に基づく提案が返ってくるわけです。

特に問題になりやすいのは以下のようなケースです。

3,000 行を超える TypeScript・JavaScript ファイル
長時間続いたチャットセッション（会話履歴が積み重なったもの）
複数の大きなファイルを同時に参照させる指示
node_modules を含んだプロジェクト全体のインデックス

よくある症状と見分け方

コンテキスト不足が原因の失敗には、いくつかの共通パターンがあります。自分のケースがどれに当てはまるか確認してみてください。

症状①：ファイルの後半部分が無視される

「この 4,000 行の utils.ts 全体を見てリファクタリングして」と依頼したとき、AI が 1,500 行目あたりまでしか言及しありません。後半に実際のバグがあっても検出されません。

症状②：ファイルの内容と矛盾する修正が来る

すでに定義されている関数と同名の関数を新たに生成したり、既存のインポート文を重複させたりします。これは AI がファイルの一部しか「見えていない」ことを示しています。

症状③：「提供されていない情報です」と言い始める

ファイルは確かに存在し、以前は参照できていたのに、「そのファイルの内容は提供されていません」という返答が来るようになった場合、コンテキストが限界を迎えつつあります。

症状④：前の会話内容を忘れる

長いセッションで「さっき説明した仕様に従って」と指示したのに、セッション初期に共有した仕様が反映されていない場合も同じ原因のことがあります。

診断：本当にコンテキストが原因か確認する方法

対処に進む前に、コンテキスト制限が原因かどうかを確認します。シンプルな手順ですが、確認を省くと的外れな対処に時間を使ってしまいます。

# 対象ファイルの行数確認
wc -l path/to/your/file.ts
 
# ファイルサイズを KB で確認
du -k path/to/your/file.ts
 
# プロジェクト内の大きなファイルを探す（上位10件）
find src -name "*.ts" -o -name "*.tsx" | xargs wc -l 2>/dev/null | sort -n | tail -10

目安として、**2,000 行・100 KB を超えるファイルは「要注意」**と考えてください。

次に、新しいチャットセッションを開いて、問題のファイルの一部（冒頭 500 行など）だけを渡し、同じ指示を試してください。これで正常に動くなら、コンテキスト不足がほぼ確実に原因です。

対処法①：ファイルを論理的な単位に分割する

最も根本的な解決策は、大きなファイルを責務ごとに分割することです。AI との相性という観点でも、小さく凝集したファイルのほうが明確に処理精度が上がります。

たとえば utils.ts が 5,000 行を超えた場合の分割例：

src/
  utils/
    index.ts         # 再エクスポートのみ（既存コードのインポートを壊さない）
    formatters.ts    # 日時・数値・通貨フォーマット系
    validators.ts    # バリデーション・スキーマ系
    apiHelpers.ts    # fetch ラッパー・エラーハンドリング系
    storage.ts       # localStorage・Cookie 操作系

index.ts でまとめてエクスポートすれば、既存のインポート文（import { formatDate } from "@/utils"）を変更する必要がありません。

Antigravity への分割指示は段階的にするのがポイントです：

「src/utils.ts を見て、関数をカテゴリ別に分類して（移動はまだしない）」
→ カテゴリを確認してから
「フォーマット系の関数を src/utils/formatters.ts に移動して。index.ts の再エクスポートも追加して」

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

Antigravity がプロジェクト全体を参照する際、AI がコンテキストに含める不要なファイルを明示的に除外できます。.gitignore と同じ書き方で、プロジェクトルートに .antigravityignore ファイルを作成してください。

# .antigravityignore
 
# ビルド成果物（AI が読む必要はない）
node_modules/
dist/
.next/
out/
build/
 
# ロックファイル（変更しないし読む必要もない）
*.lock
package-lock.json
yarn.lock
pnpm-lock.yaml
 
# ログ・キャッシュ
*.log
.cache/
coverage/
 
# 圧縮済みファイル
*.min.js
*.min.css
*.map

node_modules がコンテキストに入り込んでいるプロジェクトでは、これだけで数十万トークンが解消される場合があります。.antigravityignore を追加した直後に Antigravity を再起動（またはプロジェクトを再オープン）すると確実に反映されます。

対処法③：AGENTS.md でコンテキストを能動的に設計する

プロジェクトルートに AGENTS.md を配置することで、AI に「このプロジェクトで何が重要か」を事前に伝えられます。ファイルを全部読まなくても構造を把握できるため、コンテキストの節約と精度の向上が同時に実現できます。

# AGENTS.md
 
## プロジェクト概要
Next.js 16 + TypeScript + Cloudflare Workers 構成の SaaS。Stripe 課金あり。
 
## アーキテクチャの重要な制約
- Cloudflare Workers では `fs` モジュールが使えない（Node.js API 非対応）
- `articles.json` にはメタデータのみ格納。HTML は `public/content/` に個別出力する
- self-fetch（`fetch('/')` 等）は Workers 環境で禁止
 
## 変更してはいけないファイル（要確認）
- `src/config/pricing.ts` — 価格の唯一の定義場所
- `cache-worker.js` — エッジキャッシュ制御。変更時は DEPLOY_VERSION を更新
- `public/robots.txt` — SEO に直結。変更は 4 サイト同時に
 
## よく使うコマンド
\`\`\`bash
npm run dev          # 開発サーバー起動
npm run build        # ビルド（generate-content.mjs が自動実行される）
npm run type-check   # 型チェックのみ
\`\`\`

AGENTS.md の効果は、使い始めてから数日で実感できます。AI が「このプロジェクトの文脈」を最初から理解した状態で返答するようになり、的外れな提案が明らかに減ります。

対処法④：大きなタスクを段階的に分割する

「プロジェクト全体を見てリファクタリングして」という一発指示は、コンテキストを一気に消費してしまいます。代わりに、タスクを小さなステップに分けて進めましょう。

❌ コンテキストを一気に消費する指示
「このリポジトリ全体を見て、型安全でない箇所を全部直して、テストも書いて」

✅ 段階的に進める指示
Step 1（新しいセッション）: 「src/app/api/ フォルダだけ見て、any 型が使われている箇所を列挙して（修正はしない）」
Step 2（新しいセッション）: 「checkout/route.ts の any 型を修正して。変更差分だけ見せて」
Step 3（新しいセッション）: 「webhook/route.ts の any 型を修正して」

各ステップを新しいチャットセッションで行うのがポイントです。セッションをリセットすると、前の会話履歴が消えてコンテキストが最大まで解放されます。

対処法⑤：それでも解決しない場合のチェックリスト

上記の対処法を試しても改善しない場合、以下を順番に確認してください。

Antigravity 本体のアップデート確認 — 古いバージョンでコンテキスト処理に既知のバグがある場合があります。ヘルプメニューから最新版を確認してください。
プロジェクトの再インデックス — Ctrl + Shift + P（Mac は Cmd + Shift + P）から "Reload Workspace" を実行して、Antigravity のインデックスをリセットします。
別モデルへの一時切り替え — 設定から Gemini 2.5 Flash など、コンテキストウィンドウが異なるモデルに切り替えてみると、問題が特定モデルに固有かどうか確認できます。
ネットワーク状況の確認 — 稀に、ネットワーク遅延が原因でレスポンスが途中で切れているだけのケースもあります。Google ステータスページで障害がないか確認してみてください。

全体を振り返って：コンテキストは「使い切るもの」ではなく「設計するもの」

Antigravity と効果的に協働するには、コンテキストウィンドウを「消耗品」ではなく「能動的に管理するリソース」として捉えることが大切だと感じています。

今日から試せる最初の一手は、プロジェクトルートに .antigravityignore を追加することです。5 分の作業で、AI の応答精度が目に見えて改善することがあります。次のステップとして、AGENTS.md に主要ファイルの説明を書き加えていくと、長期的に安定した AI 協働環境が整っていきます。

コンテキストを丁寧に設計したプロジェクトほど、AI がより深く理解した状態で提案してくれるようになります。ぜひ少しずつ試してみてください。