Antigravity の Context Window 管理術 — 大規模コードベースで精度を落とさない実践テクニック

5万行のプロジェクトで Antigravity の補完が的確だったのに、10万行を超えたあたりから急に見当違いな提案をし始めた——この経験に心当たりはないだろうか。原因はほぼ確実に Context Window の飽和です。

AI コーディングアシスタントの性能を決めるのは、モデルの賢さだけではありません。「何を見せるか」がそれ以上に重要です。Antigravity は開いているファイル、プロジェクト構造、最近の編集履歴を自動的にコンテキストに含めるが、プロジェクトが大きくなるとこの自動収集が裏目に出る。

Context Window 飽和の症状を見分ける

Context Window の問題は徐々に進行するため気づきにくい。以下の症状が2つ以上あれば、コンテキスト管理を見直すタイミングです:

補完候補が現在のファイルと無関係なモジュールのコードを提案する
型情報を正しく推論できず、any や未定義の型を返す頻度が上がる
インラインチャットの回答が「一般的なベストプラクティス」に逃げ始める
同じ質問をしても回答の品質にばらつきが大きくなる

3番目の症状が最も見逃されやすい。Antigravity が具体的なコード提案ではなく「一般的には〜が推奨されます」と答え始めたら、コンテキストにプロジェクト固有の情報が十分に入っていないサインです。

.antigravityignore で不要コンテキストを排除する

最初にやるべきことは、コンテキストに含める必要のないファイルを除外することです。.antigravityignore は .gitignore と同じ構文で、AI のコンテキスト収集から特定のパスを除外する:

# .antigravityignore

# ビルド成果物（コンテキストを汚染する最大の原因）
dist/
build/
.next/
out/

# 自動生成ファイル（人間が書いたコードではない）
*.generated.ts
*.d.ts
prisma/migrations/

# テストのスナップショット（大量のテキストでコンテキストを圧迫）
**/__snapshots__/
**/*.snap

# 巨大な設定ファイル
package-lock.json
yarn.lock
pnpm-lock.yaml

# ドキュメント・アセット（コーディングには不要）
docs/
*.md
\!README.md
public/images/

私の経験では、この設定だけで Context Window の有効利用率が 40〜60% 改善します。特に package-lock.json（数万行になることもある）と __snapshots__/ の除外は効果が大きいです。

ただし注意点があります。*.d.ts を除外すると、ライブラリの型定義を参照できなくなる場合があります。プロジェクト固有の .d.ts（env.d.ts など）だけ除外し、node_modules 内の型定義は Antigravity のデフォルト処理に任せるほうが安全です:

# より安全な型定義の除外
src/**/*.generated.d.ts
\!src/env.d.ts

手動参照で「見せたいファイル」を明示する

.antigravityignore が「見せたくないもの」の制御なら、手動参照は「見せたいもの」の指定です。Antigravity のチャットパネルで @file を使うと、特定のファイルを明示的にコンテキストに追加できます。

効果的な手動参照パターン:

# パターン1: 型定義 → 実装の順で参照
@types/api.ts この型に基づいて、新しいエンドポイントのハンドラーを書いて

# パターン2: テスト → 実装の逆順参照
@__tests__/auth.test.ts このテストが通るように認証ミドルウェアを実装して

# パターン3: 設計書 → 実装
@docs/architecture.md この設計に従って、キャッシュレイヤーを追加して

パターン2の「テスト先行型参照」は特に強力です。テストコードは仕様の最も正確な表現であり、Antigravity に「何を実現すべきか」を明確に伝えられます。

ワークスペース分割戦略

プロジェクトが大きい場合、Antigravity のワークスペースをサブディレクトリに限定する方法があります。モノレポで全パッケージをワークスペースに含めるのではなく、今作業しているパッケージだけを開く:

# ❌ モノレポ全体を開く（Context Window が分散する）
antigravity open /path/to/monorepo
 
# ✅ 作業対象のパッケージだけ開く
antigravity open /path/to/monorepo/packages/api

ただし、この方法には欠点があります。他パッケージの型定義やインターフェースを参照できなくなるため、パッケージ間の依存関係が強い場合は使いにくい。

その解決策として、私は「コンテキストブリッジファイル」を作成している:

// packages/api/CONTEXT_BRIDGE.ts
// このファイルは Antigravity のコンテキスト用。実行時には使用しない。
 
// 共有パッケージの重要な型を再エクスポート
export type { User, Session, Permission } from '@monorepo/shared';
export type { APIResponse, PaginatedResult } from '@monorepo/shared/api';
 
// 他パッケージとの接点を明示
// Web パッケージは /api/auth/* エンドポイントに依存
// Worker パッケージは Redis の pub/sub チャネル "events:*" を購読

このファイルをワークスペースに含めておくと、Antigravity は他パッケージとの接点を理解した上でコード提案を行える。ビルドには影響しないが、AI の精度を大幅に向上させるテクニックです。

セッション管理: コンテキストのリフレッシュ

長時間の作業セッションでは、コンテキストが古い情報で埋まっていく問題があります。朝から作業していて、午前中に触ったファイルの情報がまだコンテキストに残り、午後の作業に干渉することがあります。

対処法はシンプルです。大きなタスクの切り替え時にチャットセッションをリセットする:

1. 機能Aの実装が完了 → チャットをクリア
2. 機能Bの作業を開始 → 必要なファイルだけ @file で参照し直す

これは「面倒くさい」と感じるかもしれないが、古いコンテキストを引きずったまま作業を続けるよりも、トータルで見れば時間の節約になります。私の場合、2時間ごとにセッションをリフレッシュするルーティンにしてからは、「なぜか午後になると補完精度が落ちる」問題がほぼ解消しました。

マイクロサービス構成での実践

マイクロサービス構成では、各サービスが独立したリポジトリを持つことが多いです。この場合の Context 最適化は、単一リポジトリとは異なるアプローチが必要です:

# .antigravity/context.yaml（プロジェクトルートに配置）
external_references:
  - name: "user-service"
    openapi: "https://internal-docs.example.com/user-service/openapi.json"
  - name: "payment-service"
    proto: "./proto/payment.proto"
 
priority_files:
  - "src/config/services.ts"     # サービス間通信の設定
  - "src/middleware/auth.ts"      # 認証ロジック
  - "src/types/events.ts"        # イベント型定義

external_references で他サービスの API 仕様を参照可能にし、priority_files でコンテキストに常に含めるべきファイルを指定します。特に events.ts のようなサービス間通信の型定義は、コンテキストに含まれているかどうかで提案の質が劇的に変わる。

次のステップ

まずは .antigravityignore の作成から始めてほしい。ビルド成果物とロックファイルを除外するだけで、体感できるレベルの改善があります。その後、作業スタイルに合わせてワークスペース分割やコンテキストブリッジファイルを導入していくのがおすすめです。