Antigravity で「参照の検索（Find References）」が抜ける・空になる時の修正手順

ある関数を消したい、リネームしたい、影響範囲を見たい。そういう時にいつも頼りにしている Shift+F12（Find References）ですが、Antigravity で作業を続けていると、ある日突然「結果が 1 件も出ない」「呼び出し元が 5 つあるはずなのに 1 つしか出てこない」という状態に出会うことがあります。

エージェントに「この関数を全部置き換えて」と依頼する前提で考えると、参照の検索が抜けるのは静かなバグです。エージェントは見えていない呼び出しを残したまま、全部書き換えたつもりで作業を終えてしまいます。

私はこの問題で何度か本番に壊れたコードを通してしまった経験があり、原因ごとに対処を整理しておくのが結局いちばん安全だと感じています。今日はその診断フローを、TypeScript・Python・モノレポ環境の順で書きます。

結果が空・部分的に抜ける時、まず確認する 3 点

Find References は「言語サーバー（LSP）が答えるもの」と「Antigravity 側のインデックスが答えるもの」の二段構成で動いています。どちらが沈黙しているかで原因と直し方がまったく違うので、最初に切り分けます。

確認したい点は次の 3 つです。

LSP の状態バーが「Idle」になっているか（読み込み中なら待つ）
対象ファイルがプロジェクトの「ワークスペースルート」配下に置かれているか
node_modules や .venv、dist 配下のファイルを除外設定で隠していないか

LSP がまだファイルを読み終えていない状態で Find References を実行すると、結果は「今、解析できているぶんだけ」が返ります。これは「壊れている」のではなく「まだ知らない」だけなので、ステータスバーで Indexing... 70% のような表示が見えていれば、まず最後まで待つのが正解です。

TypeScript で参照が抜ける典型パターン

TypeScript プロジェクトで参照が抜ける原因は、ほぼ次のどれかに収束します。

(1) tsconfig.json の include から外れているファイル

最も多いのがこれです。include に書かれていないディレクトリは TypeScript Server の解析対象に入らないため、そこからの呼び出しは Find References の結果に出てきません。

// tsconfig.json
{
  "include": [
    "src/**/*",
    "scripts/**/*"  // ← これが抜けていると scripts 配下の参照が出ない
  ],
  "exclude": ["node_modules", "dist", ".next"]
}

tsc --listFiles を一度実行して、参照を探したいファイルが出力に含まれているかを確認すると一発でわかります。

npx tsc --listFiles | grep "scripts/migrate.ts"
# 何も出なければ tsconfig の include に追加が必要

(2) JavaScript ファイルからの参照

TypeScript 関数を JS ファイル側で呼んでいると、allowJs が無効なプロジェクトでは TypeScript Server がその JS を読まないので、当然参照も出ません。tsconfig.json に次を足すと拾えるようになります。

{
  "compilerOptions": {
    "allowJs": true,
    "checkJs": false  // 型チェックは不要なら off
  }
}

(3) 動的インポートと文字列ベースのルーティング

import('./pages/' + slug) のような動的構築や、ルーティングテーブルで文字列キーから関数を引く実装は、構造上 LSP が追えません。これは Antigravity の問題ではなく言語仕様の限界なので、エージェントにリファクタを依頼する前に「動的解決があるかどうか」を grep で先に確認します。

grep -rn "import(" src | head
grep -rn "registry\[\|handlers\[" src | head

Python で参照が抜ける典型パターン

Python の場合、Find References は Pylance または Pyright が答えます。私の経験では次の 2 つが明確に多い原因です。

(1) pyrightconfig.json の include 不足

TypeScript と同じ理屈で、include に書かれていないディレクトリは解析されません。

{
  "include": ["src", "tests", "scripts"],
  "exclude": ["**/__pycache__", ".venv", "build"],
  "venvPath": ".",
  "venv": ".venv"
}

(2) 仮想環境のパスが Antigravity に渡っていない

.venv を Antigravity が見つけられないと、その venv にしか入っていないモジュール経由の参照は壊れます。コマンドパレットから Python: Select Interpreter を開いて、現在のプロジェクトの .venv/bin/python を明示的に指定してください。指定後、Pylance の再起動（Pylance: Restart Server）が要ります。

参考までに、私は Python プロジェクトでは必ず pyrightconfig.json をリポジトリにコミットして、新しい開発環境に移っても Find References が同じ範囲を返すようにしています。これは Antigravity 固有の話ではなく、長く運用するときの保険です。

モノレポで一部パッケージだけ抜ける時

pnpm workspace、Yarn workspace、Turborepo、Nx といったモノレポ構成では、Find References が「そのパッケージ内」だけを見て、他パッケージからの呼び出しを返さないことがあります。

原因はだいたい 2 つです。

TypeScript の references フィールドを tsconfig.json で設定していない
Antigravity がワークスペースルートを正しく認識していない

前者は次のように書きます。これを書くと、各パッケージから他パッケージの型を辿れるようになり、Find References もパッケージ境界を越えるようになります。

// packages/ui/tsconfig.json
{
  "extends": "../../tsconfig.base.json",
  "compilerOptions": { "composite": true, "outDir": "dist" },
  "references": [{ "path": "../core" }]
}

後者については、Antigravity を cd packages/ui && antigravity . のように個別パッケージから起動すると、ワークスペースルートを誤認します。必ずモノレポのルート（pnpm-workspace.yaml や turbo.json がある場所）から起動してください。

それでも直らない時にやる、私の最終手段

ここまでで直らない時、私が順に試している手順です。

コマンドパレットから Developer: Reload Window を実行する
.next/、dist/、build/、.cache/ などのビルド成果物を削除する
node_modules/.cache/ または ~/.cache/typescript/ を削除する
Antigravity を一度終了して、もう一度開く
それでも空のままなら、対象ファイルを 1 文字編集して保存する（LSP に再解析を促す）

5 番が地味に効くことがあります。LSP は内部的に「最後の編集が反映済み」というフラグでファイルを管理しているため、ごく稀に状態が古いままになります。空白の追加削除でも構わないので、わざと差分を作って保存すると目が覚めます。

エージェントに置換を依頼する前のセルフチェック

最後に、これは私が必ずやっているチェックです。Antigravity のエージェントに「この関数を全部書き換えて」と頼む前に、まず Find References の結果と grep の結果を突き合わせます。

# Find References の結果（4 件）
# vs
grep -rn "fetchUserProfile" src --include="*.ts" --include="*.tsx" | wc -l
# 6 件出たら、Find References が 2 件取りこぼしている

数が合わない時は、上のどこかで LSP が黙っています。エージェントを走らせる前に必ず合わせておくこと。リファクタの安全性は、エージェントの賢さよりも、参照の網羅性に依存します。

モノレポでの型解決の見通しが、読む前と後で明らかに変わりました。