取り組みの背景 — なぜコンテキスト制御が重要なのか
Antigravity の AI エージェントがどれだけ優れたコードを生成できるかは、与えるコンテキストの質 に大きく左右されます。同じプロンプトを投げても、コンテキストウィンドウに適切な情報が含まれているかどうかで、出力の精度は劇的に変わります。
多くの開発者は Antigravity を使い始めた直後こそ生産性の向上を実感しますが、プロジェクトが大規模になるにつれて「AI の応答がずれてくる」と感じることがあります。これはほとんどの場合、コンテキストウィンドウの管理が不十分であることが原因です。
ここで扱うのはAntigravity Editor のコンテキスト制御メカニズムを深く理解し、AI の精度を最大化するための実践的なテクニックを体系的に解説します。対象読者は Antigravity を日常的に使っている中〜上級の開発者です。
コンテキストウィンドウの仕組みを理解する
トークンとコンテキストの関係
Antigravity のバックエンドで動作する LLM（Gemini 等）には、一度に処理できるトークン数の上限があります。Gemini 2.5 Pro の場合、最大 100 万トークンのコンテキストウィンドウを持ちますが、すべてのトークンが等しく重要なわけではありません 。
LLM のアテンション機構には「迷子効果（Lost in the Middle）」と呼ばれる特性があります。コンテキストの先頭と末尾に置かれた情報は強く参照される一方、中間部分の情報は見落とされやすくなります。つまり、大量のファイルを闇雲にコンテキストに詰め込むと、かえって精度が低下する可能性があるのです。
// ❌ 悪い例: 関係ないファイルもすべてコンテキストに含めている // → トークンを浪費し、重要な情報が中間に埋もれる
// ✅ 良い例: 必要なファイルだけを戦略的に参照する // @file:src/lib/auth.ts — 認証ロジックの現在の実装 // @file:src/types/user.ts — ユーザー型定義 // @file:tests/auth.test.ts — 既存テストのパターン // この3ファイルを参照して、OAuth 2.0 のリフレッシュトークン処理を追加してください Antigravity のコンテキスト階層
Antigravity が AI に渡すコンテキストは、以下の階層で構成されています。
レベル1（常時参照） : AGENTS.md、Knowledge Items、ユーザー設定で定義された常時読み込みファイル
レベル2（セッション参照） : 現在開いているファイル、チャット履歴、最近編集したファイル
レベル3（明示的参照） : @メンションで指定したファイル・フォルダ・シンボル・URL
レベル4（自動収集） : エージェントが自律的にファイルツリーやシンボルテーブルから収集した情報
この階層構造を理解することで、どの情報をどのレベルに配置すべきか が明確になります。
@メンションの戦略的活用
基本的な@メンション構文
Antigravity のチャットパネルでは、@ プレフィックスで様々な要素を参照できます。
@file:src/components/Button.tsx — 特定ファイルを参照
@folder:src/lib/ — フォルダ全体を参照
@symbol:handleSubmit — 特定の関数・クラスを参照
@url:https://docs.example.com — Web ページを参照
@git:HEAD~3 — Git コミット差分を参照
@terminal — ターミナル出力を参照
ファイル参照の最適化パターン
大規模プロジェクトでは、参照するファイルの順序と組み合わせ が重要です。以下のパターンを意識してください。
パターン1: インターフェース → 実装 → テスト
型定義やインターフェースを最初に参照し、次に実装、最後にテストを参照します。AI は「仕様 → 実装 → 検証」の流れで理解しやすくなります。
@file:src/types/payment.ts
@file:src/services/payment.service.ts
@file:tests/payment.service.test.ts
上記の決済サービスに、Stripe Webhook のイベント検証ロジックを追加してください。
エラーハンドリングは既存パターンに合わせ、テストも追加してください。
パターン2: 設定 → ミドルウェア → ルート
バックエンドの変更では、設定ファイルから参照を始めると、AI がアーキテクチャの制約を正しく把握できます。
@file:wrangler.toml
@file:src/middleware.ts
@file:src/app/api/checkout/route.ts
Cloudflare Workers の制約を考慮して、checkout エンドポイントにレート制限を追加してください。
パターン3: 類似実装の参照
新しい機能を追加するとき、既存の類似機能を参照させると、プロジェクトの規約に沿ったコードが生成されやすくなります。
@file:src/app/api/auth/route.ts — 既存の認証 API（参考パターン）
@file:src/app/api/webhook/route.ts — 既存の Webhook API（参考パターン）
上記2つの API ルートを参考にして、新しい /api/notifications エンドポイントを作成してください。
エラーハンドリング、ログ出力、型定義のパターンは既存コードに合わせてください。
フォルダ参照の注意点
@folder: は便利ですが、大きなフォルダを参照するとトークンを大量に消費します。以下のガイドラインに従ってください。
ファイル数が 10 以下 のフォルダ: @folder: で問題なし
ファイル数が 10〜30 のフォルダ: 必要なファイルを個別に @file: で指定
ファイル数が 30 以上 のフォルダ: フォルダ構造だけ参照し、個別ファイルは AI に選ばせる
// 大きなフォルダの場合の推奨アプローチ
src/components/ フォルダの中から、フォーム関連のコンポーネントを探して
@file:src/components/FormField.tsx と同じパターンで新しいフォームを作成してください。
Knowledge Items を活用したコンテキストの永続化
Knowledge Items の役割
Knowledge Items は、セッションをまたいで AI に記憶させたい情報を保存する仕組みです。Knowledge Items 完全ガイドで基本を解説していますが、ここではエディタでの高度な活用法に焦点を当てます。
Knowledge Items に保存すべき情報は以下の通りです。
プロジェクト固有の規約 : コーディングスタイル、命名規則、アーキテクチャパターン
ドメイン知識 : ビジネスロジックの制約、業界用語の定義
過去の決定事項 : 「なぜこの設計にしたか」の記録、技術的な意思決定ログ
よく使うプロンプトテンプレート : 定型的なコード生成指示
Knowledge Items の設計パターン
効果的な Knowledge Items は、以下の構造で記述します。
# プロジェクト: ECサイト基盤
## アーキテクチャ制約 - ランタイム: Cloudflare Workers（Node.js API の一部が使用不可） - DB: Cloudflare D1（SQLite 互換、トランザクションは制限あり） - KV: Cloudflare KV（結果整合性、strong consistency が必要な場合は D1 を使用）
## コーディング規約 - 状態管理: Zustand を使用（Redux は使わない） - スタイリング: Tailwind CSS のみ（CSS Modules は使わない） - テスト: Vitest + Testing Library（Jest は使わない） - インポート順序: 外部 → 内部 → 型 → スタイル
## API 設計規約 - レスポンス形式: { success: boolean, data?: T, error?: string } - エラーコード: HTTP ステータスコード準拠 - 認証: Bearer トークン（JWT）を Authorization ヘッダーに設定 この Knowledge Items があると、AI は毎回のプロンプトで「Cloudflare Workers を使っています」と伝える必要がなくなります。
Knowledge Items とファイルコンテキストの使い分け
以下の判断基準で使い分けてください。
変更頻度が低い + 全セッションで必要 → Knowledge Items に保存変更頻度が高い + 特定のタスクで必要 → @file: で都度参照変更頻度が低い + 特定のタスクで必要 → AGENTS.md に記述
// Knowledge Items に保存すべき例 // → プロジェクト全体の規約（めったに変わらない） const CODING_STANDARDS = { formatter: "Biome" , testRunner: "Vitest" , stateManagement: "Zustand" , };
// @file: で参照すべき例 // → 現在のスキーマ定義（頻繁に変わる可能性がある） // @file:prisma/schema.prisma AGENTS.md によるコンテキストの構造化
AGENTS.md の配置戦略
AGENTS.md はリポジトリのルートだけでなく、サブディレクトリにも配置できます。Antigravity はファイルツリーを走査して、関連する AGENTS.md を自動的にコンテキストに含めます。
project-root/
├── AGENTS.md ← プロジェクト全体の方針
├── src/
│ ├── AGENTS.md ← src 配下の開発規約
│ ├── components/
│ │ └── AGENTS.md ← コンポーネント設計ルール
│ └── api/
│ └── AGENTS.md ← API 設計ルール
└── tests/
└── AGENTS.md ← テスト記述ルール
この階層構造により、AI は作業対象のディレクトリに応じて適切なルールを参照 します。src/api/ 配下のファイルを編集するときは、ルートの AGENTS.md と src/AGENTS.md、src/api/AGENTS.md が自動的にコンテキストに含まれます。
AGENTS.md の書き方のベストプラクティス
効果的な AGENTS.md は、AI が判断に迷う場面 を想定して書きます。
# API ルート設計ガイド
## 必須パターン - すべての API ルートで try-catch を使用する - エラーレスポンスは必ず { success: false, error: string } 形式 - 環境変数は getCloudflareContext() 経由で取得する（process.env は使わない）
## 禁止パターン - fs モジュールのインポート（Cloudflare Workers で使用不可） - グローバル変数への状態保存（Worker はステートレス） - console.log を本番コードに残す（wrangler tail でのみデバッグ）
## 判断基準 - KV と D1 の選択: 読み取り頻度が高く結果整合性で問題ない → KV、整合性が必要 → D1 - ミドルウェア vs ルート内処理: 3つ以上のルートで共通 → ミドルウェア化 AGENTS.md によるマルチエージェント設計 も併せて参照してください。
大規模コードベースでのコンテキスト最適化
コンテキストバジェットの考え方
大規模プロジェクトでは、コンテキストウィンドウを「バジェット（予算）」として管理する発想が有効です。
コンテキストバジェット配分の目安:
全体: 100%
├── AGENTS.md + Knowledge Items: 10-15%
├── チャット履歴: 15-20%
├── 明示的ファイル参照: 40-50%
├── エージェント自動収集: 15-20%
└── プロンプト本文: 5-10%
この配分を意識すると、@file: で参照するファイルの数に自ずと上限が見えてきます。一般的に、1回のプロンプトで参照するファイルは 5〜8 個 が最適です。
コンテキストプルーニング（不要情報の除去）
長いチャットセッションでは、過去のやり取りがコンテキストを圧迫します。以下の対策を取りましょう。
新しいチャットセッションを開始する : タスクが切り替わったら、新しいチャットを開始してコンテキストをリセットします。Antigravity では Cmd+L（Mac）/ Ctrl+L（Windows/Linux）で新しいチャットを開始できます。
要約プロンプトを挟む : 長いセッションの途中で「ここまでの変更内容を3行で要約してください」と依頼し、要約をベースに新しいセッションを始めます。
不要なファイル参照を外す : タスクが進むにつれて不要になったファイル参照は積極的に外します。
// セッション途中での整理例
ここまでの変更を要約すると:
1. PaymentService に Webhook 検証ロジックを追加
2. 対応するテストを 5 件追加
3. wrangler.toml に新しい KV 名前空間を設定
次のタスクに移ります。
@file:src/services/notification.service.ts
@file:src/types/notification.ts
通知サービスの実装に取り掛かります。
モノレポでのコンテキスト管理
モノレポ（複数パッケージを1つのリポジトリで管理する構成）では、パッケージ間の境界を AI に明示する点が肝心です。
# AGENTS.md（モノレポルート）
## パッケージ構成 - packages/web — Next.js フロントエンド - packages/api — Hono バックエンド - packages/shared — 共有型定義・ユーティリティ - packages/db — Drizzle ORM スキーマ
## 依存関係ルール - web → shared, api（直接インポート可） - api → shared, db（直接インポート可） - shared → 外部依存のみ（他パッケージに依存しない） - db → 外部依存のみ
## 変更時の影響範囲 - shared を変更したら web と api の両方をテスト - db を変更したら api のテストとマイグレーションを確認 実践ワークフロー: コンテキスト制御の具体的な運用
日常開発のコンテキスト設計テンプレート
以下は、日常的なタスクごとに最適化されたコンテキスト設計のテンプレートです。
バグ修正のコンテキスト設計 :
1. エラーログ / スタックトレース（@terminal）
2. エラーが発生しているファイル（@file:）
3. 関連する型定義（@file:）
4. 既存テスト（@file:）
5. 「このエラーの原因を特定し、修正してください。既存テストが通ることを確認し、
再発防止のテストを追加してください。」
新機能追加のコンテキスト設計 :
1. 類似機能の実装（@file:）— パターンの参照元
2. 関連する型定義（@file:）
3. ルーティング設定（@file:）
4. 「@file:src/app/api/auth/route.ts のパターンに従って、
新しい /api/billing エンドポイントを作成してください。」
リファクタリングのコンテキスト設計 :
1. リファクタリング対象（@file: × 複数）
2. AGENTS.md のコーディング規約
3. テストファイル（@file:）
4. 「以下のファイルを Single Responsibility Principle に従って分割してください。
テストが全て通ることを確認してから完了としてください。」
コンテキスト品質の自己診断
AI の応答品質が低いと感じたら、以下のチェックリストで自己診断してください。
チェック1: AI が間違った前提で応答していないか
→ 正しい設定ファイルや型定義がコンテキストに含まれているか確認
チェック2: AI が古い情報を参照していないか
→ チャット履歴が長くなっていないか確認。新しいセッションを試す
チェック3: AI が関連ファイルを見落としていないか
→ @file: で明示的に参照を追加する
チェック4: 情報過多になっていないか
→ 不要な @folder: 参照を個別の @file: に分解する
// コンテキスト品質チェックのプロンプト例 // AI の理解状況を確認するテクニック
// まず確認する: `現在のコンテキストで把握しているファイル一覧と、 それぞれの役割を簡潔に説明してください。`
// AI の回答を確認して、不足があれば @file: を追加 // 過剰があれば不要な参照を外す 個人開発者の視点から（実体験メモ）
まとめ
Antigravity Editor のコンテキスト制御は、AI コーディングの精度を決定づける最も重要なスキルの一つです。この記事で解説した内容を実践すれば、大規模プロジェクトでも AI の応答品質を高く維持できるようになります。
重要なポイントを振り返ると、コンテキストウィンドウには階層構造があり、各レベルに適切な情報を配置することが精度向上の基本です。@メンションはファイル参照の順序と組み合わせを意識し、Knowledge Items と AGENTS.md は変更頻度と共有範囲で使い分けます。そして、大規模コードベースではコンテキストバジェットの概念を導入し、情報の過不足を常にチェックする習慣が大切です。
コンテキスト制御のスキルは一朝一夕で身につくものではありませんが、日々の開発の中で意識的に実践することで、確実に AI との協業品質が向上していきます。