「Bug を直してほしいだけなのに、関係ないファイルまで AI が触ってしまった」— Antigravity を使い始めた頃の私の最大のストレスがこれでした。原因はシンプルで、AI に渡すコンテキストが広すぎたのです。プロジェクト全体を読ませた状態で「ここのバグを直して」と頼むと、AI は良かれと思って隣接コードまで一緒に修正してしまいます。
個人開発でアプリを運用していると、AI が広げた差分をレビューするのも自分一人です。レビュアーがもう一人いれば気づけたはずの巻き込み変更が、そのまま本番に出ていく。この構造に気づいてから、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 つずつ追加していく方が結果として意図通りの差分が返ってきます。
もう一つ意識しているのは、@file は「読ませる指定」ではなく「編集を許可する指定」だと捉えることです。参考にしてほしいだけのファイルを @file で足すと、AI はそれも編集対象だと解釈します。読ませたいだけなら、後述の @symbol で必要な部分だけを渡すか、プロンプト本文に「〜は参照のみ」と明記します。
@symbol — 関数・クラス単位で部分指定する
ファイル全体ではなく特定の関数やクラスだけを参照したい場合は @symbol が便利です。
@symbol parseUserInput
この関数の input が null のときに、暗黙の falsy チェックではなく
明示的に InvalidInputError を投げるように変更してください。
他の呼び出し箇所への破壊的変更がある場合は、影響範囲を箇条書きで先に教えてください。
@symbol は IDE のシンボルインデックスを利用しているため、定義元と使用箇所の両方を AI が把握しやすくなります。「他の呼び出し箇所への影響を先に教えて」と一言加えると、いきなり書き換えるのではなく、影響を要約してから提案を返してくれます。破壊的変更の事故を避ける小さなコツです。
@symbol は「聞くだけ」の用途でも有効です。コードレビュー中に「この関数は何をしていて、どこが危ういか」を確認したいとき、チャットに関数本文を貼り付けるより @symbol で渡した方が、行番号と周辺の型情報まで一緒に届きます。貼り付けは手が滑ると一部が欠けますが、シンボル参照なら欠けません。
@folder — ディレクトリ単位でまとめて渡す
1 ファイルでは足りず、かといってワークスペース全体は広すぎる。この中間を埋めるのが @folder です。
@folder src/features/billing
このディレクトリ配下だけで、Stripe の price ID をハードコードしている箇所を
すべて洗い出してください。まだ修正はしないでください。
一覧（ファイル:行番号:該当コード）だけを返してください。
私が @folder を使うのは、ほぼ調査フェーズに限定しています。「洗い出す」「一覧を返す」「まだ修正しない」の 3 点をセットで書き、修正は結果を見てから @file に切り替える。この二段構えにしてから、調査のつもりで投げた指示が大規模な差分になって返ってくる事故がなくなりました。
ディレクトリ単位で編集まで任せると、範囲の広さと編集許可が同時に効いてしまい、事実上「全部読ませる」に近い状態に戻ってしまいます。@folder は目であって手ではない、と考えておくと扱いを間違えません。
@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 で対象ページを固定するようにしています。
複数 API にまたがる移行でも、ページを 1 枚ずつ固定してファイル単位で進める方が確実です。まとめて渡すと、新旧のパターンが混ざった差分が返ってきます。
どの @ を使うかの早見表
迷ったときの判断軸をまとめておきます。
| リファレンス | 渡る範囲 | 向いている場面 | 避けたい場面 |
|---|---|---|---|
@file | ファイル1枚 | 編集対象がはっきりしている修正 | 参考として見せたいだけのとき（編集許可と解釈される） |
@symbol | 関数・クラス単位 | 部分的な変更／コードの意味を聞く | ファイルをまたぐ構造変更 |
@folder | ディレクトリ配下 | 調査・洗い出し・影響範囲の把握 | そのまま編集まで任せること |
@docs | 公式ドキュメントのページ | バージョン追従・API 移行 | ドキュメント化されていない挙動の確認 |
@web | 任意の URL | RFC・Issue・記事など公式外の根拠 | 出典の信頼性が確認できていないページ |
「編集させたいものだけを @file、見せたいものは @symbol か @folder」— この一行に集約されます。
長文脈になっても、範囲を絞る意味は薄れない
Antigravity 2.0 は Gemini 3.5 Flash を核に据え、コードベース全体をメモリに載せられる長文脈を備えました。ここで自然に浮かぶ疑問があります。全部読めるなら、もう @ で絞る必要はないのではないか、と。
私自身の実感は逆です。読める範囲が広がるほど、編集させる範囲を明示する価値が上がります。長文脈が解決したのは「AI が知らない」という問題であって、「AI がどこまで手を出してよいか」という問題ではありません。前者はモデルの能力、後者は指示の設計です。混同すると、全部知っている AI が全部を直しにきます。
並列エージェントを使うようになると、これはさらに切実になります。あるエージェントがコンポーネントを書き、別のエージェントが API ルートを構成する、という同時進行では、各エージェントの担当範囲が重なった瞬間に編集が衝突します。@ リファレンスは、この境界線を一行で引くための道具でもあるのです。範囲指定は、モデルが賢くなるほど不要になるのではなく、指揮する対象が増えるほど必要になります。
@ が効いていないと感じたときに疑う3つのこと
指定したはずなのに範囲が守られない。そんなときに私が順に確認しているのは次の 3 点です。
1. シンボルインデックスが古い
@symbol の候補に出てこない、あるいは古い定義が渡っている場合は、インデックスが更新されていない可能性があります。ブランチを切り替えた直後や、大量のファイルを一気に生成した直後に起きやすい症状です。ウィンドウを再読み込みしてインデックスを作り直すと直ります。
2. 会話が長くなり、初期の指定が薄まっている
10 往復を超えたあたりから、最初に書いた「他のファイルは触らないでください」が効きづらくなることがあります。これはモデルの不具合というより、会話全体が一つの長いコンテキストである以上、避けがたい性質です。私はタスクが変わったら会話を切ると決めています。同じスレッドで別件を続けると、前の依頼の残り香が差分に混ざります。
3. @docs のページが実際には取得できていない
URL を渡したつもりでも、認証が必要なページやリダイレクトの多いページは中身が届いていないことがあります。判定は簡単で、「渡したページに書かれている固有の関数名を一つ挙げてください」と聞けば分かります。答えられなければ、届いていません。その場合は該当箇所を本文に貼り付ける方が確実です。
私が現場で使っている @ 操作の3原則
実プロジェクトで定着しているのは次の 3 つです。
- 「広く読ませて絞る」より「狭く始めて足す」 — 最初は
@fileを 1 つだけ指定し、必要になった時点で@symbolや別の@fileを足します。コンテキストは加算式の方が事故が少ないです - 修正対象と期待出力を必ず明記する — 「
@file src/api/login.tsの関数loginUserのみ、UI 表示文字列を日本語化、ロジックは変更しない」のように、ファイル・対象・粒度を文章で固定します - 「触ってほしくない範囲」も明示する — 「
src/lib/i18n.tsには触らない」「テストコードは別タスクで扱う」と書いておくと、想定外の連鎖変更を抑えられます
コンテキストの渡し方をエディタ設定のレベルで整えたい方は、Antigravity Editor のコンテキスト制御 が参考になります。そもそも渡してはいけないファイルを遮断する設計は、Antigravity に渡してはいけないファイルを確実に除外する にまとめました。Plan モードでの大規模変更については、Antigravity の Plan モードと Fast モードの実践使い分け をどうぞ。
全体を振り返って — 今日試せる1つのこと
明日の作業で 1 つだけ試してほしいのは、「AI に頼みたい変更を、@file を 1 つだけ指定した状態で書き始めてみる」ことです。広く読ませたくなる気持ちをいったん抑えて、狭く始めてみる。それだけで、想定外の差分は劇的に減ります。
AI IDE の出力品質は、モデルの賢さだけでは決まりません。「何を読ませるか」ではなく「何に手を出させるか」を設計すること。@ リファレンスは、その設計を一行で表現できる道具です。型レベルでさらにコンテキストを縛る設計に踏み込みたい方は、Antigravity と Effect-TS で堅牢なエラーハンドリングを設計する実装ガイド もあわせてご覧ください。