Antigravity でファイルが見えない・エージェントがアクセスできないときの対処法

「ファイルが見つかりません」——その原因は1つではない

Antigravity で開発を進めていると、ある日突然エージェントが「そのファイルは見つかりません」と返してくることがあります。昨日まで普通に参照できていたファイルが、なぜか認識されなくなります。あるいは新しくプロジェクトを開いたのに、エージェントがディレクトリ構造をまったく把握していません。

この問題は単純に見えて、実際には複数の原因が絡み合っています。インデックスの未完了、.antigravityignore の設定ミス、ファイルパーミッション、さらにはプロジェクトサイズによるコンテキストウィンドウの溢れまで。原因ごとに対処法がまったく異なるため、やみくもにリトライしても解決しません。

ここでは、実際に開発中に遭遇しやすいパターンを原因別に分類し、それぞれの確認手順と修正方法を解説します。

インデックスが完了していないパターン

Antigravity を開いた直後にエージェントへ質問すると、プロジェクトのインデックスが完了する前にリクエストが処理されます。この状態ではエージェントがファイルの存在自体を知らないため、「ファイルが見つかりません」というレスポンスになるのは当然です。

確認方法は簡単で、Antigravity のステータスバーにインデックスの進行状況が表示されています。「Indexing...」や進捗バーが出ている間は、エージェントへの複雑な質問は控えたほうがいい。

# プロジェクトのファイル数を確認する
# 数千ファイル以上あると初回インデックスに数分かかる
find . -type f -not -path './.git/*' -not -path './node_modules/*' | wc -l

ファイル数が多い大規模プロジェクトでは、初回のインデックスに体感で2〜5分かかることもあります。特に node_modules を除外していない場合、数万ファイルのインデックスが走るため、エージェントが使い物になるまでかなり待たされます。

対処法: Antigravity を開いたら、ステータスバーのインデックス完了を待ってから作業を始める。大規模プロジェクトでは .antigravityignore で不要ディレクトリを除外してインデックス対象を減らすことが根本的な解決策になります。

.antigravityignore の設定ミス

.antigravityignore は .gitignore と同じ構文で、エージェントのインデックス対象からファイルやディレクトリを除外する設定ファイルです。これが意図しない形で動作すると、開発に必要なファイルまで除外されてしまう。

よくある間違いを見てみよう。

# ❌ 悪い例：パターンが広すぎて src 配下の設定ファイルまで除外
*.json
*.yaml
dist/
build/
 
# ✅ 良い例：除外対象を明確に限定
node_modules/
dist/
build/
.next/
*.log
coverage/

上の悪い例では *.json を指定しているため、package.json、tsconfig.json、さらには src/ 配下のJSON設定ファイルまですべて除外されます。エージェントはプロジェクトの依存関係も TypeScript の設定も把握できなくなります。

確認手順:

# .antigravityignore の内容を確認
cat .antigravityignore
 
# 特定のファイルが除外されているかテスト
# .gitignore と同じ構文なので git check-ignore で近似的にテストできる
git check-ignore -v src/config/settings.json

もう一つ見落としやすいのが、.antigravityignore と .gitignore の両方が適用される点です。.gitignore で除外しているファイルは、Antigravity のエージェントからも見えなくなる場合があります。意図的に Git 管理外にしているが、エージェントには認識させたいファイル（たとえばローカルの .env.local や一時的なテストデータ）がある場合は注意が必要です。

ワークスペースが検出されない問題

Antigravity の Agent Customizations UI で「no workspaces found」エラーが表示されるケースがあります。これはプロジェクトのルートディレクトリが正しく認識されていない状態です。

主な原因は3つあります。

1. プロジェクトルートに .git/ ディレクトリがない

Antigravity はプロジェクトの境界を .git/ ディレクトリで判定するケースが多いです。git init していないディレクトリを開くと、ワークスペースとして認識されないことがあります。

# プロジェクトルートで git が初期化されているか確認
ls -la .git/
 
# 初期化されていなければ
git init

2. シンボリックリンク経由でプロジェクトを開いている

macOS で Dropbox や iCloud Drive 内のプロジェクトをシンボリックリンク経由で開くと、実際のパスとシンボリックリンクのパスが食い違い、ワークスペースの検出に失敗することがあります。

# シンボリックリンクを解決した実パスを確認
realpath .
 
# Antigravity は実パスで開き直す
# 例: ~/Dropbox/projects/my-app ではなく
# /Users/username/Library/CloudStorage/Dropbox/projects/my-app

3. ネストされたプロジェクト構造

モノレポの中のサブパッケージを直接開いた場合、Antigravity がルートの package.json を見つけられず、ワークスペースの一部の機能が動作しないことがあります。モノレポ全体をルートから開くのが安全です。

エージェントが特定のファイルだけ参照できない

プロジェクト全体は認識しているのに、特定のファイルだけエージェントが参照できないケースもあります。

ファイルサイズの制限: Antigravity にはインデックス対象のファイルサイズに上限があります。数MB以上のファイル（大きなJSONデータ、バンドル済みJSファイル、画像のBase64埋め込みなど）はインデックスから自動的に除外されます。

# プロジェクト内の大きなファイルを検出
find . -type f -not -path './.git/*' -not -path './node_modules/*' \
  -size +1M -exec ls -lh {} \;

バイナリファイル: 画像、フォント、コンパイル済みバイナリはインデックスされません。エージェントにこれらのファイルの存在を伝えたい場合は、チャットで明示的にパスを指定します。

エンコーディング: UTF-8 以外のエンコーディングで保存されたファイルは正しく読み取れない場合があります。特に Windows 環境から持ち込んだ Shift-JIS ファイルは要注意です。

# ファイルのエンコーディングを確認
file -bi src/legacy/old-module.js
# 出力例: text/plain; charset=iso-8859-1
 
# UTF-8 に変換
iconv -f SHIFT-JIS -t UTF-8 src/legacy/old-module.js > src/legacy/old-module-utf8.js

コンテキストウィンドウの溢れによる見落とし

エージェントがファイルの存在は知っているのに、内容を正しく参照できない場合があります。これはコンテキストウィンドウの容量を超えて情報が詰め込まれた結果、古い情報が押し出されてしまう現象です。

典型的な症状は「さっき見せたファイルの内容を覚えていない」「10ファイル以上を同時に参照させると一部を見落とす」というもの。

対処法:

# エージェントに渡すコンテキストを絞る
# @file で参照するファイルは同時に3〜5個に抑える
# 悪い例: @src/components/ でディレクトリごと渡す
# 良い例: @src/components/Header.tsx @src/components/Nav.tsx に限定

長い会話を続けていると初期のコンテキストが失われるため、重要なファイルは会話の途中で再度 @ メンションで参照し直すと精度が上がる。セッションを分割して、1つの作業単位ごとに新しいチャットを始めるのも有効です。

コンテキスト制御の詳しいテクニックは Antigravity Editor のコンテキスト制御完全ガイド が参考になります。

パーミッションとOS固有の問題

ファイルの読み取り権限がない場合、エージェントはそのファイルにアクセスできません。特に macOS では、Antigravity アプリに対するディスクアクセス許可が影響します。

# ファイルのパーミッションを確認
ls -la src/config/secrets.json
 
# 読み取り権限がない場合
chmod 644 src/config/secrets.json
 
# macOS: Antigravity にフルディスクアクセスを許可
# System Settings → Privacy & Security → Files and Folders
# Antigravity に対して「Documents」「Desktop」等のアクセスを許可する

macOS の GUI 経由で Antigravity を起動した場合、MCP サーバーが executable file not found in $PATH エラーでクラッシュするケースも報告されています。これはターミナルの $PATH と GUI アプリの $PATH が異なるためです。

# ターミナルから Antigravity を起動すると PATH の問題を回避できる
# macOS の場合
open -a "Antigravity" /path/to/project
 
# または PATH を明示的に設定してから起動
export PATH="/usr/local/bin:/opt/homebrew/bin:$PATH"

問題が解決しないときのリセット手順

上記をすべて試しても解決しない場合は、Antigravity のキャッシュとインデックスを一度リセットするのが最終手段です。

# Antigravity のキャッシュディレクトリを削除
# macOS の場合
rm -rf ~/Library/Caches/com.google.antigravity/
rm -rf ~/.antigravity/cache/
 
# プロジェクト固有のインデックスをリセット
rm -rf .antigravity/index/
 
# Antigravity を再起動して再インデックスを待つ

リセット後は初回インデックスが再度走るため、完了まで待ってからエージェントに質問します。それでも改善しない場合は、Antigravity 自体のアップデートを確認しよう。バージョン 1.20 以降ではインデックスの安定性が大幅に改善されています。

動作が全体的に遅い場合は Antigravity の動作が遅い・フリーズする時の対処法 も合わせて確認してほしい。初期セットアップで問題が起きている場合は Antigravity のインストール・セットアップエラー解決ガイド が役立つ。

日常の予防策

ファイル認識の問題を未然に防ぐために、プロジェクトのセットアップ時に以下を習慣にしておくと安心です。

まず .antigravityignore をプロジェクトの初期段階で作成し、node_modules/、dist/、build/、.next/、coverage/ といったビルド成果物やキャッシュを除外します。これだけでインデックスの速度とエージェントの応答精度が目に見えて改善します。

次に、AGENTS.md（プロジェクトルートに配置するエージェント向けのルールファイル）にプロジェクト構造の概要を書いておく。エージェントはこのファイルを最初に読み込むため、ディレクトリ構成や主要ファイルの役割を記述しておけば、ファイルを「知っている」状態からスタートできます。

最後に、バックグラウンドインデックスによるクレジット消費に注意すること。Antigravity はファイルを保存するたびにインデックスを更新するが、これがクレジットを消費します。大量のファイルを一括変更する作業（npm install、git checkout でブランチを切り替える等）の後は、インデックスの再構築が完了するまで少し待つのがよい。