Referencing Specific Files with @mentions in Your Prompts
@mentions let you point a Claude Code prompt at an exact file, like @src/utils/foo.ts, instead of describing what you want in prose and hoping the agent finds the right one.
//
Search across all documentation pages
@mentions let you point a Claude Code prompt at an exact file, like @src/utils/foo.ts, instead of describing what you want in prose and hoping the agent finds the right one.
Describing a file in words leaves room for Claude Code to search, guess, or pick the wrong candidate when several files have similar names or purposes.
@mentions remove that ambiguity by naming the file directly, so the agent starts from the exact content you mean.
They are a prompting habit, not a special feature to configure - you simply type @ followed by a path while writing a prompt.
Used well, they make requests faster and more accurate; used carelessly, they can pull more content into context than a task actually needs.
Quick-reference recipe card - copy-paste ready.
# reference a single file directly
Fix the bug in @src/utils/formatDate.ts where timezones aren't applied.
# reference two related files in the same prompt
Compare @src/api/userController.ts with @src/api/orderController.ts
and make the error handling consistent between them.
# reference a config file alongside a source file
Update @src/config/rateLimits.ts to match what @docs/rate-limiting.md describes.When to reach for this:
A realistic bug-fix prompt that combines a source file and a test file with @mentions:
The date formatter in @src/utils/formatDate.ts returns the wrong day
when the input timestamp is near midnight UTC. The existing test in
@__tests__/formatDate.test.ts doesn't cover this case yet.
Fix the bug and add a test case for a timestamp within one minute of
UTC midnight.What this demonstrates:
@mentions replace file-finding, not the description of what's wrong.@mention on a one-line prompt saves a search step.@ followed by a path inserts a direct reference to that file into the prompt.@mentions with ordinary prose in the same prompt.| Situation | Better approach |
|---|---|
| You know the exact 1-3 files involved | @mention them directly |
| The task spans "wherever the auth logic lives" and you're not sure where that is | Describe the goal in prose and let Claude Code search |
| You need to reference an entire folder's worth of files | Describe the folder/pattern in prose rather than mentioning every file individually |
| The file is very large and only one function in it matters | Prose pointing at the function name, or a targeted description, often costs less context than mentioning the whole file |
# a task that genuinely spans a few files benefits from naming all of them
Refactor @src/services/payment.ts, @src/services/refund.ts, and
@src/types/transaction.ts to share the new `TransactionResult` shape
instead of each defining their own return type.Each additional mention adds that file's full content to context, so this pattern works best when the file count stays small and every file named is actually relevant to the task.
@mention on a thousand-line file pulls the whole thing into context even if only one function matters. Fix: describe the specific function or section in prose instead, or ask Claude Code to look at just that part.@mention only pulls in the exact file named - it does not automatically pull in files that import it or depend on it. Fix: mention each genuinely relevant file explicitly, or describe the relationship in prose.| Alternative | Use When | Don't Use When |
|---|---|---|
| Prose description of the task | The relevant file(s) aren't known ahead of time, or the task spans a broad, loosely defined area | You already know the exact file and want to skip the search step |
@mention a small, targeted set of files | You know exactly which 1-4 files matter | The task genuinely requires exploring a whole directory or unfamiliar territory |
| Let Claude Code search the codebase | Genuine exploratory or "find where X happens" tasks | You already know precisely where the code lives - searching would just waste a turn |
It inserts a direct reference to that file in your prompt, so Claude Code has the file's content available immediately instead of needing to search for or read it first.
Yes. Chain as many @mentions as the task genuinely needs, keeping in mind that each one adds its full content to context.
Yes, typically. A mention pulls in the file's actual content, while a prose description costs only the words you wrote - though prose risks Claude Code picking the wrong file or spending a turn searching.
Yes. @mentions work for any file in the project, not just source code.
It won't resolve to the content you intended - a stale or incorrect path after a rename or move is a common mistake. Double-check the path is current before sending the prompt.
There's no hard rule, but every mention adds its file's full content to the context window, so mentioning many large files at once can consume a large share of your available context.
@mentions target individual files. For a task spanning a whole folder, describing the folder and the pattern in prose is usually cheaper on context than mentioning every file in it.
No. A mention only points at the file - you still need to describe the problem, goal, or change you want in prose alongside it.
When you don't yet know which file is relevant, or when only a small part of a very large file matters - in both cases, letting Claude Code search or describing just the relevant part costs less than mentioning the whole file.
They're independent but complementary. CLAUDE.md supplies standing project context every session; @mentions narrow a specific prompt to exact files for the task at hand.
Yes. Repeated large mentions across a long session are one of the common sources of context window bloat, alongside large files read in full and verbose tool output.
Each mention independently pulls that file's content into context at the point it's used. If the file hasn't changed and is still fresh in the conversation, re-mentioning it later adds its content again rather than reusing the earlier copy.
Stack versions: Written against the Claude model lineup current as of ~June 2026 - Claude Fable 5, Claude Opus 4.8, Claude Sonnet 5 (the default), and Claude Haiku 4.5. Model names, pricing, and product features move quickly - verify current specifics at platform.claude.com/docs before relying on them.
Reviewed by Chris St. John·Last updated Jul 16, 2026