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.
Summary
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.
Recipe
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:
- You already know which file (or handful of files) the task involves.
- You want to avoid Claude Code spending a turn searching the codebase to find the right file.
- Two files share a similar name or purpose and you need to be unambiguous about which one.
- You're referencing a non-code file, like a config or a markdown doc, that prose alone might not surface.
Working Example
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:
- Naming both the source file and its test file up front means Claude Code does not have to search for either one.
- The prompt still explains the problem in prose -
@mentionsreplace file-finding, not the description of what's wrong. - Referencing the existing test file signals where the new test case should live, rather than leaving Claude Code to guess the project's test conventions.
- This pattern scales down cleanly: even a single
@mentionon a one-line prompt saves a search step.
Deep Dive
How It Works
- Typing
@followed by a path inserts a direct reference to that file into the prompt. - Claude Code resolves the reference and includes the file's actual content as context for that turn, rather than needing to locate it first.
- This applies to any file in the project, not just source code - config files, markdown docs, and data files can all be mentioned the same way.
- The mechanism is additive: you can combine several
@mentionswith ordinary prose in the same prompt. - Because the full content of a mentioned file is added to context, mentioning a very large file has the same context cost as if Claude Code had read that file in full through a tool call.
When Prose Beats @mentions
| 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 |
Chaining Multiple Mentions
# 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.
Gotchas
- Mentioning a very large file for a small task. A single
@mentionon 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. - Chaining too many mentions in one prompt. Every mention adds its full content to context, so five or six mentions in one prompt can consume a large chunk of the context window before the actual task even starts. Fix: keep mentions to the files that are truly central to the task; describe the rest.
- Mentioning a file to "just be safe." Adding a mention out of caution rather than necessity is a common source of unnecessary context bloat. Fix: only mention a file if the prompt genuinely needs its content, not as a reflex.
- Assuming a mention searches the codebase for related files. An
@mentiononly 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. - Using a stale or wrong path. A mention pointing at a path that no longer exists (after a rename or move) won't resolve to what you intended. Fix: double-check the path is current, especially after a refactor.
Alternatives
| 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 |
FAQs
What does typing @ followed by a path actually do?
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.
Can I mention more than one file in a single prompt?
Yes. Chain as many @mentions as the task genuinely needs, keeping in mind that each one adds its full content to context.
Does mentioning a file cost more context than describing it in words?
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.
Can I @mention a file that isn't code, like a markdown doc or config file?
Yes. @mentions work for any file in the project, not just source code.
What happens if I mention a file that doesn't exist anymore?
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.
Is there a limit to how many files I can mention?
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.
Should I mention an entire folder?
@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.
Do @mentions replace explaining what I want done?
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 should I prefer prose over an @mention?
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.
Do @mentions interact with CLAUDE.md?
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.
Can excessive @mentions contribute to needing /compact or /clear?
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.
Is there a difference between mentioning a file once early in a conversation versus mentioning it again later?
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.
Related
- What CLAUDE.md Actually Does - standing project memory versus per-prompt file references.
- Context Management Basics - where @mentions fit among the section's core tools.
- Auditing What's Eating Your Claude Code Context Window - spotting when mentions are contributing to bloat.
- Why /compact and /clear Exist - recovering context space after a mention-heavy session.
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.