Antigravity に的確なコンテキストを渡す — @ リファレンスで AI 出力の精度を上げる実践ガイド

「Bug を直してほしいだけなのに、関係ないファイルまで AI が触ってしまった」— Antigravity を使い始めた頃の私の最大のストレスがこれでした。原因はシンプルで、AI に渡すコンテキストが広すぎたのです。プロジェクト全体を読ませた状態で「ここのバグを直して」と頼むと、AI は良かれと思って隣接コードまで一緒に修正してしまいます。

なぜ @ リファレンスを使うのか — 「全部読ませる」が逆効果になる場面

エディタ全体やワークスペース全体を AI に読ませると、たしかに「賢く」なるような感覚があります。しかし実際には、関係ないファイルの命名規則を真似してしまったり、修正範囲が広がりすぎたりして、レビューにかかる時間が逆に増えてしまうことがあります。

特に困るのが次のような場面です。

単一の関数だけ直したかったのに、テストコードや型定義まで勝手に書き換えられる
ある型を聞いただけなのに、「ついでに」実装まで提案され、レビューの集中が分散する
ライブラリの古い API を学習データから引っ張ってきて、現行バージョンと食い違う実装を出してくる

@ リファレンスは、AI に「ここだけを見て、ここだけを直して」と明確に伝えるための語彙です。範囲を絞ると、出力の精度はむしろ上がります。「広く読ませれば賢くなる」は、半分しか正しくないのです。

@file — 単一ファイルを正確に渡す

最も基本的なリファレンスが @file です。チャット入力欄で @ を打つと候補が表示されるので、対象のファイルを選ぶだけで使えます。

@file src/utils/format-date.ts

このファイルの formatDate 関数で、表示を UTC ではなく JST に変更してください。
出力例: 2026-04-29 12:00 JST
他のファイルは触らないでください。

ポイントは、「変更してほしいファイル」と「期待する出力」をセットで書くことです。@file で範囲を限定したうえで、最後に「他のファイルは触らないでください」と一文添えるのが私の定型です。これだけで、AI が勝手に隣接コードまで広げてしまう事故が体感で 8 割ほど減りました。

複数ファイルにまたがる変更でも、最初から「依存関係も含めて全部読んで」と頼むより、@file を 1 つずつ追加していく方が結果として意図通りの差分が返ってきます。

@symbol — 関数・クラス単位で部分指定する

ファイル全体ではなく特定の関数やクラスだけを参照したい場合は @symbol が便利です。

@symbol parseUserInput

この関数の input が null のときに、暗黙の falsy チェックではなく
明示的に InvalidInputError を投げるように変更してください。
他の呼び出し箇所への破壊的変更がある場合は、影響範囲を箇条書きで先に教えてください。

@symbol は IDE のシンボルインデックスを利用しているため、定義元と使用箇所の両方を AI が把握しやすくなります。「他の呼び出し箇所への影響を先に教えて」と一言加えると、いきなり書き換えるのではなく、影響を要約してから提案を返してくれます。破壊的変更の事故を避ける小さなコツです。

@docs / @web — 外部ドキュメントを参照させる

ライブラリのバージョン違いによる古い情報の混入を防ぐには、@docs や @web で公式ドキュメントの URL を直接渡すのが効きます。

@docs https://nextjs.org/docs/app/api-reference/functions/headers

@file src/app/api/me/route.ts

このページに従って、headers() の最新の使い方でリライトしてください。
非同期化が必要な箇所はすべて await を付けてください。

学習時のスナップショットではなく指定ページを優先するため、Next.js や Tailwind CSS のように更新ペースが速いライブラリでは差がはっきり出ます。私は破壊的変更を含むメジャーアップデートに追従するときは、必ず @docs で対象ページを固定するようにしています。

私が現場で使っている @ 操作の3原則

実プロジェクトで定着しているのは次の 3 つです。

「広く読ませて絞る」より「狭く始めて足す」 — 最初は @file を 1 つだけ指定し、必要になった時点で @symbol や別の @file を足します。コンテキストは加算式の方が事故が少ないです
修正対象と期待出力を必ず明記する — 「@file src/api/login.ts の関数 loginUser のみ、UI 表示文字列を日本語化、ロジックは変更しない」のように、ファイル・対象・粒度を文章で固定します
「触ってほしくない範囲」も明示する — 「src/lib/i18n.ts には触らない」「テストコードは別タスクで扱う」と書いておくと、想定外の連鎖変更を抑えられます

関連する設計の話は、Antigravity のカスタムルールでプロジェクト固有の規約を浸透させる方法でも扱っています。Plan モードでの大規模変更については、Antigravity の Plan モードと Fast モードの実践使い分けが参考になります。

全体を振り返って — 今日試せる1つのこと

明日の作業で 1 つだけ試してほしいのは、「AI に頼みたい変更を、@file を 1 つだけ指定した状態で書き始めてみる」ことです。広く読ませたくなる気持ちをいったん抑えて、狭く始めてみる。それだけで、想定外の差分は劇的に減ります。

AI IDE の出力品質は、モデルの賢さだけでは決まりません。「何を読ませるか」というコンテキスト設計が同じくらい重要で、@ リファレンスはその設計を一行で表現できる強力な道具です。型レベルでさらにコンテキストを縛る設計に踏み込みたい方は、Antigravity と Effect-TS で堅牢なエラーハンドリングを設計する実装ガイドもあわせてご覧ください。