"I just wanted to fix one bug, but the AI rewrote three other files I never asked it to touch." That was my biggest frustration when I started using Antigravity. The cause was simple — I was handing the AI too much context. When you let it read the whole project and then ask it to "fix this bug," it helpfully drags neighboring code along for the ride. The diff that lands in your review takes longer to read than the original problem would have taken to fix by hand.
This guide walks through how I use Antigravity's @-references — @file, @symbol, @docs, @web — to scope context and keep the AI's edits surgical. Everything below is something I do in real projects, and I'll be honest about where each pattern works and where it doesn't.
Why @-References Matter — When "Read Everything" Backfires
Letting the AI read your entire workspace feels like it should make the model smarter. In practice, the broader the context window, the more the model has to weigh, and the more it leans on heuristics like "match the surrounding style." That sounds harmless, but it often translates into the AI imitating naming conventions from unrelated files, expanding the edit surface beyond what you asked, and slipping in subtle behavioral changes that look correct in isolation.
A few situations where this consistently bites me:
- I want to fix one function, but tests and type definitions get rewritten "for consistency"
- I ask a question about a type signature, and the AI "helpfully" rewrites the implementation I never mentioned
- An old API signature from training data leaks in and contradicts the current library version
- A long file with many concerns gets restructured because the model decided the architecture could be cleaner
@-references are how you tell the AI, clearly and in one line, which files and symbols are in scope and which aren't. Narrower context tends to raise output quality, not lower it. The folk intuition that "more context equals smarter AI" is only half right — it's true up to a point and then becomes a liability.
@file — Pinning a Single File
@file is the most basic reference. Type @ in the chat input and the file picker appears.
@file src/utils/format-date.ts
In the formatDate function in this file, switch the output from UTC to JST.
Expected output: 2026-04-29 12:00 JST
Don't touch any other files.
The pattern I follow has three parts: pair the target file with the operation in plain English, give a concrete expected output the model can self-check against, and add a single line at the end that explicitly excludes everything else. That last sentence — "don't touch any other files" — feels redundant the first few times you write it, but in my experience it cuts unintended-edit incidents by what feels like 80%.
For changes that span multiple files, I get better results by adding @file references one at a time than by saying "read all dependencies." The narrower I start, the closer the diff lands to what I actually wanted, and the easier the review is. If a second file genuinely needs to change, I add it on the next turn after seeing the first diff. The conversation becomes a controlled expansion rather than a guess at the right blast radius up front.
A subtle benefit: starting narrow also produces shorter chat threads, which keeps the AI's working memory focused and reduces the chance that an unrelated assumption from earlier in the conversation will resurface ten messages later.
@symbol — Scoping to a Function or Class
When you only need a specific function or class rather than the whole file, @symbol is the right tool.
@symbol parseUserInput
When input is null, throw an explicit InvalidInputError instead of relying on
the implicit falsy check.
Before changing anything, list any breaking impact on existing call sites as a bullet list.
Because @symbol rides on the IDE's symbol index, the AI can reason about both the definition and the call sites. Adding "list breaking impact first" pushes the model to summarize before it edits, which is a small habit that has saved me from a lot of broken refactors. If the impact list shows something I didn't expect — say, three call sites that pass an explicitly nullable value — I can adjust the approach before any code changes.
@symbol also works well for "what does this do?" questions when you don't want the model to start writing code yet. Asking "explain @symbol parseUserInput and its main risks" usually returns a focused answer that doesn't drift into related symbols, which is what I want during code review.
@docs and @web — Pinning External Documentation
To stop stale API signatures from leaking out of the model's training data, I drop the official docs URL into @docs or @web.
@docs https://nextjs.org/docs/app/api-reference/functions/headers
@file src/app/api/me/route.ts
Following the page above, rewrite this file to use the latest headers() API.
Wherever the new API is async, add the appropriate await.
Pinned URLs effectively override the snapshot the model learned during training. With fast-moving libraries like Next.js or Tailwind CSS, where the API surface can shift between minor versions, the difference is dramatic. Whenever I'm following a major version migration, I always pin the relevant doc page first — and if the migration touches multiple APIs, I pin one at a time and migrate file by file. Trying to do a sweeping multi-API migration with broad context almost always produces a diff that mixes old and new patterns.
@web is similar but accepts arbitrary URLs, which is useful for blog posts, RFCs, and GitHub discussions where the canonical answer lives outside the official docs.
Common Mistakes I Made Early On
Three patterns I had to unlearn:
Treating @ as a shortcut for "give the AI more." I'd pile in @file after @file thinking I was being helpful. The model's behavior degraded — it would touch unrelated parts of every file I added because I'd implicitly told it everything I added was "in scope." The fix is to think of each @file as a commitment: I'm telling the model "you may edit this." Don't add it unless you actually want it edited.
Skipping the "expected output" line. When I'm in a hurry, I'll write @file foo.ts make it faster. The diff that comes back is technically faster, but in ways I didn't want — caching changes, signature changes, behavioral changes. Adding "expected output: same public API, internal loop unrolled" takes ten extra seconds and saves the round-trip.
Forgetting that @symbol works on read too. I used to copy-paste a function into chat to ask about it. @symbol funcName is shorter, includes the line numbers and surrounding type information, and lets the model jump to call sites if it needs to. For "explain this code" tasks, it's strictly better than copy-paste.
Three Rules I Follow When Using @-References
In real projects, three rules have stuck:
- Start narrow and add, instead of starting wide and trimming. Begin with one
@file. Add@symbolor another@fileonly when the output makes it obviously necessary. Additive context produces fewer accidents than reductive context, because every reference you add is a deliberate decision rather than a default - Always state the target and the expected output. "In
@file src/api/login.ts, only translate UI strings to Japanese; logic stays unchanged." Lock the file, the operation, and the granularity in a single sentence the model can verify against - Spell out what not to touch. Saying "leave
src/lib/i18n.tsalone" or "tests are out of scope for this task" prevents the cascade of unrelated edits I used to spend evenings undoing. Negative scope is as informative as positive scope
For related design ideas, see Mastering Custom Rules in Antigravity for Project-Wide Conventions. For larger refactors where Plan mode is the right fit, Antigravity Plan Mode vs Fast Mode in Practice is a good companion piece.
One Thing to Try Tomorrow
If you take only one thing from this article, try this: the next time you ask the AI for a change, start the prompt with exactly one @file and nothing else. Resist the urge to load up the context window. Stay narrow on purpose. The first few times this will feel like you're handicapping the model, but the diffs will surprise you — they land closer to what you actually wanted, and review goes faster.
The quality of an AI IDE's output is decided as much by what you let it see as by which model you're running underneath. @-references are the most direct way to express that decision in a single line, and they're the lowest-effort productivity gain I've found in the last year of AI-assisted development. If you want to push the same idea down to the type level — making "what context this code can use" enforceable through types rather than prompts — Building Robust Error Handling with Antigravity and Effect-TS is the natural next read.