3.1 File References with @

Course: Claude Code - Essentials Section: Basic Input & Interaction Video Length: 2-5 minutes Presenter: Daniel Treasure

Opening Hook

"Show me this one file" is more powerful than you'd think. With the @ symbol, you can give Claude instant context about specific files or folders—without copying-pasting code. It's the fastest way to focus Claude's attention.

Key Talking Points

@ Syntax: Three Flavors
@filename - reference by fuzzy match (fastest for simple cases)
@path/to/file - explicit path reference
@directory/ - show entire folder structure and file list
Fuzzy Matching Magic
Type @auth → matches auth.js, AuthService.ts, authenticate.py
No need for full path; Claude shows what it matched
Case-sensitive on first character: @Auth won't match auth.js
Line Range References (VS Code & JetBrains IDEs)
@app.ts#5-10 - specific lines only
Use Alt+K (Option+K on Mac) shortcut to auto-insert with selected lines
Reduces context bloat when only one function matters
Example: Instead of referencing 500-line file, pull just lines 150-175
Directory Context
@src/components/ - show Claude the full folder structure
Use cases: understand patterns, spot inconsistencies, refactor groups of files
Be careful with large directories (saves context; respect .gitignore by default)
MCP Resources (Advanced - requires MCP setup)
@server:protocol://resource/path - pull from external systems
Real example: @github:issue://456 fetches live GitHub issue
Real example: @postgres:schema://users queries database schema
Real example: @docs:file://api/authentication pulls doc server content

Demo Plan

Live Session Walkthrough (2-3 minutes):

Setup bash cd /path/to/sample-project claude
Demo @ File Reference (30 seconds)
Type: @app.js (or similar file in project)
Say: "Claude, what does this function do?"
Point out: Claude has full file context instantly
Call out the fuzzy match working
Demo @ Directory Reference (30 seconds)
Type: @src/utils/ (or appropriate folder)
Say: "What patterns do you see in this folder?"
Show Claude responding with insights across all files in directory
Demo Line Range (30 seconds, if in VS Code)
Show file with multiple functions
Demo Alt+K shortcut to select lines 10-25
Result: @file.ts#10-25
Ask Claude to refactor just that function
Demo File + File (Optional, 30 seconds)
Reference two related files: @auth.js @user.ts
Ask: "how do these work together?"
Show Claude explaining the interaction between files

Code Examples & Commands

Basic @ References

# Fuzzy match by filename
@auth explain how login works

# Explicit path
@src/models/User.ts show me the User schema

# Directory
@config/ what configuration options are available?

# Line range (VS Code/JetBrains)
@middleware.ts#15-35 refactor this to use async/await

# PDF files (with page ranges)
@docs/api.pdf#1 summarize this API documentation
@docs/spec.pdf#5-10 explain pages 5-10

Real-World Workflows

# Ask about a specific module
@Logger is this thread-safe?

# Find issues across files
@services/ there's a memory leak; find it

# Review naming patterns
@components/ these React components have inconsistent styles

# MCP integration (with GitHub configured)
Can you implement this? @github:issue://456
# Claude pulls live issue data and implements solution

# MCP integration (with database)
@postgres:schema://users design a query to find inactive accounts

Gotchas & Tips

Gotcha: Fuzzy matching is case-sensitive for first char
@Auth will not match auth.js
Use lowercase @auth or full path @src/auth.js
Gotcha: @ on large directories loads all files
@src/ on a monorepo = huge context
Better: @src/components/buttons/ for specific subset
Respects .gitignore by default (unless you configure otherwise)
Tip: @ at the start of your message
Good: @auth.js what does this do?
Less clean: What does @auth.js do?
Claude reads @ first, loads context, then processes question
Tip: Line ranges save massive context
1000-line file = 1000 lines of context
@file.ts#200-220 = 20 lines (and focused)
Use this constantly for large files
Tip: Use multiple files in one message
@auth.js @middleware.ts @user.ts how do these interact?
Claude sees all three and explains relationships
More efficient than asking separately
Tip: Use @ in CLAUDE.md and skills
In .claude/CLAUDE.md: See @README for project overview and @package.json for scripts
In skills: @.claude/rules/security.md to auto-load rules
Keeps context modular and reusable
Gotcha: MCP resources require setup
@github: syntax only works if GitHub MCP server configured
Run /mcp in session to check what's available
New users won't have MCP servers by default (advanced feature)
Gotcha: .gitignore respected by default
.env, node_modules/, build artifacts ignored by default
If you need to reference ignored files: use absolute path or check respectGitignore setting
This is a good security default (don't leak secrets)

Lead-out

Now you can point Claude at specific files with laser focus. Next up: slash commands. These are shortcuts that trigger actions without full prompts—like /help, /clear, and custom commands you can create. They're the glue that ties everything together into a faster workflow.

Reference URLs

Official Docs - File References: https://code.claude.com/docs/en/vs-code (section: "Using @-Mentions")
Official Docs - MCP Resources: https://code.claude.com/docs/en/mcp (section: "Use MCP Resources")
Official Docs - Settings (respectGitignore): https://code.claude.com/docs/en/settings (search: "respectGitignore")

Prep Reading

Recent Articles: "10 Claude Code Productivity Tips" - emphasizes @ mentions as time-saver
Official: VS Code Integration docs, "Using @-Mentions" section
Official: MCP docs, "Use MCP Resources" section

Quick Reference