"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.
Running apps as an indie developer means I'm also the only reviewer of whatever diff comes back. A collateral edit that a second pair of eyes would have caught ships straight to production. Once I noticed that, I started spending less time trying to make the AI smarter and more time deciding what it's allowed to reach.
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.
The mental model that helped most: @file is not "let the AI see this," it's "the AI may edit this." If you attach a file purely as background reading, the model reads that as permission. When I only want something seen, I pass the relevant part with @symbol instead, or state "reference only, do not modify" in the prompt body.
@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 is also better than copy-paste for read-only questions. Asking "explain @symbol parseUserInput and its main risks" carries the line numbers and surrounding type information along with the body, and nothing gets truncated by a sloppy selection.
@folder — Passing a Directory
Sometimes one file isn't enough but the whole workspace is far too much. @folder fills that gap.
@folder src/features/billing
Within this directory only, find every place where a Stripe price ID is hardcoded.
Do not fix anything yet.
Return only a list of file:line:snippet.
I use @folder almost exclusively for investigation. The three-part formula — "find," "return a list," "don't fix yet" — then switch to @file for the actual edit once I've seen the results. Since adopting that two-step split, I've stopped getting sweeping diffs back from prompts I meant as questions.
If you hand a directory over and allow edits, breadth and permission combine, and you're effectively back to "read everything." Think of @folder as eyes, not hands, and you'll rarely misuse it.
@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. Sweeping multi-API migrations with broad context almost always produce 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.
Which @ to Reach For
| Reference | Scope | Good for | Avoid when |
|---|---|---|---|
@file | One file | Edits with a clearly known target | You only want it seen — attaching implies edit permission |
@symbol | A function or class | Partial changes; asking what code does | Structural changes across files |
@folder | A directory tree | Investigation, inventory, impact mapping | Delegating the edit itself |
@docs | An official docs page | Version migrations, API changes | Undocumented behavior |
@web | Any URL | RFCs, issues, posts outside the docs | Sources you haven't vetted |
It collapses to one line: attach with @file only what you want edited; show the rest with @symbol or @folder.
Long Context Doesn't Make Scoping Obsolete
Antigravity 2.0 runs on Gemini 3.5 Flash with a context window long enough to hold an entire codebase in memory. Which raises the obvious question: if it can read everything, why bother scoping?
My experience points the other way. The more the model can read, the more valuable it is to state what it may change. Long context solved "the AI doesn't know about that file." It did not solve "how far is the AI allowed to reach." The first is a model capability; the second is a design decision you make in the prompt. Conflate them and you get an AI that knows everything and fixes everything.
Parallel agents make this sharper still. When one agent writes a component while another configures an API route, the moment their scopes overlap their edits collide. An @-reference is how you draw that boundary in a single line. Scoping doesn't become unnecessary as models get smarter — it becomes more necessary as the number of things you're directing goes up.
Three Things to Check When @ Isn't Working
When a scope I set clearly isn't being respected, I check these in order.
1. The symbol index is stale. If @symbol doesn't autocomplete, or hands over an outdated definition, the index likely hasn't caught up. This shows up most often right after switching branches or generating a large batch of files at once. Reloading the window rebuilds the index and resolves it.
2. The conversation got long and diluted the original scope. Past roughly ten exchanges, that "don't touch any other files" line from the top starts losing its grip. That's less a bug than a property of a conversation being one long context. My rule: when the task changes, start a new thread. Continuing unrelated work in the same thread lets the previous request bleed into the diff.
3. The @docs page never actually loaded. Pages behind auth or several redirects deep may not come through even though you pasted the URL. Testing is easy — ask "name one function that appears on the page I gave you." If it can't, the page didn't arrive, and pasting the relevant excerpt into the prompt is the reliable fallback.
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, 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
To tune context handling at the editor-settings level, see Mastering Context Control in Antigravity Editor. For blocking files that should never reach the AI in the first place, Keep the Wrong Files Out of Antigravity's AI Context covers the setup. 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 touch as by which model runs underneath. @-references express that decision in a single line. 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.