The @-mention Strategy Guide

The Problem

You @-mention five files thinking you're being helpful. The AI generates code that contradicts itself, uses outdated patterns from file 3, and ignores the critical detail in file 5 because token attention degraded.

Or worse: you don't @-mention anything. The AI invents file structures, hallucinates APIs, and writes code that doesn't match your architecture because it's flying blind.

The @-mention feature is your most powerful tool and your easiest way to confuse the AI.

The Core Insight

@-mentions aren't bookmarks. They're attention anchors.

When you @-mention a file, you're telling the AI "this matters for this task." But AI attention isn't uniform - it degrades across large context. The 7th file you mention gets less "cognitive weight" than the 2nd.

Think of @-mentions like tabs in your browser. Too many, and you can't focus. Too few, and you're missing information. The art is knowing when to be explicit vs. letting the AI discover.

The Walkthrough

When to @-mention Explicitly

Always @-mention for:

• Files you want modified: "Update @routes/api.js to include rate limiting"
• Pattern templates: "@routes/users.js shows the pattern. Follow it for @routes/posts.js"
• Breaking assumptions: "Don't use axios. We standardized on fetch. See @utils/http.js"
• Critical constraints: "@config/security.js defines our auth approach. Follow it exactly."

When to Let AI Discover

Skip @-mentions for:

• Exploration: "How does authentication work here?" (Let AI find auth-related files)
• Standard patterns: "Add error handling" (AI knows common patterns, no need to force-feed)
• Broad questions: "What's the project structure?" (Don't constrain the search)
• Dependency discovery: AI tools can follow imports - trust the tooling

Layering @-mentions

Advanced pattern: Layer context across multiple messages instead of front-loading everything.

Rookie Approach (Front-load Everything):

@models/User.js @models/Post.js @models/Comment.js @routes/users.js @routes/posts.js @middleware/auth.js @utils/validation.js
"Add ability to mention users in comments"

Problem: 7 files is too much. AI gets overwhelmed. Attention spreads thin.

Expert Approach (Layer Context):

# Message 1 - Establish pattern
@models/Post.js @models/Comment.js
"Comments already exist. Here's the schema."

# Message 2 - Add user mentions (AI retains previous context)
@models/User.js
"Now add user mentions in comments. Users have username field."

# Message 3 - Implementation (specific files only)
@routes/comments.js @utils/validation.js
"Update comment routes to parse @username mentions and validate"

Why this works: Context builds incrementally. Each message adds one layer. AI maintains focus.

Multi-file Change Patterns

Changing multiple files? Order matters.

Example: Adding a Feature Across Layers

# Step 1: Data layer
@models/Payment.js
"Create Payment model with these fields: amount, status, userId"

# Step 2: Business logic
@services/PaymentService.js
"Implement payment processing. Reference @models/Payment.js"

# Step 3: API layer
@routes/payments.js
"Add POST /payments endpoint using @services/PaymentService.js"

# Step 4: Validation
@middleware/validation.js
"Add payment validation schema for @routes/payments.js"

Notice: Each step @-mentions previous work. AI builds incrementally with full context at each layer.

Advanced Patterns

Pattern 1: The Anchor File

When working across many files, designate one as the "anchor" that stays mentioned throughout.

# Anchor: @docs/API_PATTERNS.md (stays in all messages)

# Message 1
@docs/API_PATTERNS.md @routes/users.js
"Update users route to follow patterns"

# Message 2
@docs/API_PATTERNS.md @routes/posts.js
"Now update posts route"

# Message 3
@docs/API_PATTERNS.md @routes/comments.js
"Finally update comments route"

The anchor ensures consistency without re-mentioning all previous files.

Pattern 2: Diff-Based Mentions

For refactors, show what changes between versions:

@old-auth.js @new-auth.js
"I'm migrating from old-auth pattern to new-auth pattern.
Update @routes/login.js to use new pattern."

AI sees both old and new, knows what to replace.

Pattern 3: Negative @-mentions

Sometimes you need to exclude files from consideration:

"Update all route files to use async/await.
Do NOT touch @routes/legacy-*.js files.
Start with @routes/api/"

Explicit exclusions prevent unwanted changes.

Failure Patterns

1. The Mention Spam

Symptom: You @-mention 10+ files. AI response is generic or misses key details.

Fix: Limit to 3-5 files per message. Use layering for complex tasks.

2. The Zero Mentions

Symptom: AI invents file paths and APIs that don't exist in your codebase.

Fix: @-mention at least one "anchor" file showing real structure.

3. The Wrong File Priority

Symptom: You mention implementation details before interfaces. AI generates code that violates contracts.

Fix: @-mention interfaces/types first, then implementations.

4. The Stale Mentions

Symptom: You keep @-mentioning files from 20 messages ago that are no longer relevant.

Fix: Start a new session when the task changes. Old mentions create noise.

Tool-Specific Strategies

Claude Code (Desktop/Web)

• Strength: Excellent at discovering files from natural language
• Strategy: Ask questions first, @-mention for precision edits second
• Tip: Use @-mentions to override AI's file discovery when it guesses wrong

Cursor

• Strength: Fast multi-file edits, good at following imports
• Strategy: @-mention entry points, let it follow dependency chains
• Tip: Use Cmd+K on specific files for focused edits vs. chat for exploration

Claude Code (CLI)

• Strength: Agent-scale edits across dozens of files with persistent session state
• Strategy: @-mention the entry point; let the agent expand context via tool calls rather than pre-loading
• Tip: Write a CLAUDE.md with architecture conventions so you don't burn @-mentions re-explaining structure every session

Real-World Example

Task: Add caching layer to an API with 20+ routes.

Bad Approach:

@routes/ @services/ @middleware/
"Add Redis caching to all API routes"

Result: Generic caching code that doesn't fit architecture

Good Approach:

# Step 1: Pattern
@middleware/cache.js (create)
"Create caching middleware. Use this pattern:
- Cache GET requests
- Invalidate on POST/PUT/DELETE
- 5 min TTL default
- Redis client from @config/redis.js"

# Step 2: Example
@routes/users.js
"Add caching middleware from @middleware/cache.js"

# Step 3: Scale
"Apply same caching pattern from @routes/users.js to:
- @routes/posts.js
- @routes/comments.js
- @routes/tags.js"

Result: Consistent implementation across all routes

# Create a .cursorrules or CLAUDE.md file
@.cursorrules
"These are the project standards. Follow them for all changes."

# Now that file is implicitly in context for every request