Feeding Context: @-mentions vs Full Files

The Problem

You need the agent to understand auth.js. Do you @-mention it or copy-paste the whole file? You try @-mention and the agent seems to miss details. You paste the whole file and it works - so now you paste everything. Your context window fills up fast and responses slow down.

Which method you use changes how the agent behaves.

@-mentions and full-file pastes aren't interchangeable. They have different token costs, different attention weights, and different effects on agent focus. Most developers pick one randomly and wonder why results vary.

The Core Insight

@-mentions are references. Full pastes are instructions. Use them differently.

When you @-mention a file, you're saying "this exists, check if needed." When you paste a file, you're saying "this is critical, prioritize it." The agent's attention follows your delivery method.

Think of it like giving someone directions: pointing to a map (@-mention) vs. reading the route aloud (paste). Different contexts need different approaches.

The Walkthrough

How @-mentions Work

When you @-mention a file:

• Agent has access to the full content (reads it from disk)
• Content is in context but not "foregrounded"
• Agent will reference it if your prompt makes it relevant
• Token cost: full file size (but shared across agent's memory)
• Best for: background reference, existing code that doesn't need changes

How Full Pastes Work

When you paste a file inline:

• Agent sees it as part of your message (higher priority)
• Content is "foregrounded" in agent's attention
• Agent will reference it even if only tangentially relevant
• Token cost: full file size (in your message, more attention weight)
• Best for: files to modify, critical context, focused analysis

The Decision Matrix

Hybrid Strategy: Excerpt Pasting

Best of both worlds for large files:

# Instead of pasting 500-line database.js
# Paste only the relevant function:

Here's the current getUserById implementation from database.js:

```javascript
async function getUserById(id) {
    const query = 'SELECT * FROM users WHERE id = $1';
    const result = await pool.query(query, [id]);
    if (result.rows.length === 0) {
        throw new NotFoundError('User not found');
    }
    return result.rows[0];
}
```

Update this to include user roles with a JOIN to the roles table.

(@database.js for full context if needed)

This gives the agent:

• Focused view of what to change (excerpt)
• Full file access if it needs more context (@-mention)
• Clear instructions (your prompt)

The Progressive Loading Pattern

Start minimal, add as needed:

1. Session start: @-mention architecture doc + 1-2 key files
2. First task: Paste the file you're modifying, @-mention dependencies
3. If agent seems confused: Paste more context or relevant excerpts
4. If agent ignores a file: Paste an excerpt to draw attention

Example Workflows

Workflow 1: Implementing a New Feature

# Session start
@ARCHITECTURE.md

# First message
I need to implement password reset functionality.
Here's the current auth.js:

[paste auth.js - file you'll modify]

@email-service.js  (reference for email patterns)
@database.js       (reference for user queries)

Follow the pattern in auth.js for token generation.

Workflow 2: Debugging an Error

# Error happens in production
I'm getting this error:

```
TypeError: Cannot read property 'id' of undefined
at getUserProfile (api/users.js:45)
```

Here's the getUserProfile function:

[paste the function - focused debugging]

@api/middleware/auth.js  (might be passing wrong user object)

What's causing this?

Workflow 3: Code Review

# You want agent to review a PR
Review this PR for issues:

[paste the changed file completely]

@STYLE-GUIDE.md     (check for style compliance)
@tests/user.test.js (ensure tests cover changes)

Focus on edge cases and potential race conditions.

Failure Patterns

1. The @-mention Everything

Symptom: You @-mention 20 files, agent gives generic responses.

Fix: Paste 1-2 critical files, @-mention the rest. Pasting creates focus.

2. The Paste Everything

Symptom: You paste 10 full files, hit token limit fast, agent is slow.

Fix: Paste only files you're modifying. @-mention the rest.

3. The Wrong File Foregrounded

Symptom: Agent keeps referencing the config file you pasted instead of the code file you @-mentioned.

Fix: Swap them. Paste the code, @-mention the config.

4. The Hidden Critical Detail

Symptom: You @-mention a file with critical context, agent misses it.

Fix: Paste the critical section as an excerpt, @-mention the full file for reference.

Advanced: Context Layering

Combine both methods strategically:

Layer 1: Foundation (@-mentions)

Architecture docs, style guides, core patterns - always available, low attention weight.

Layer 2: Task Focus (Pastes)

The 1-3 files relevant to this specific task - high attention weight.

Layer 3: On-Demand (@-mentions + excerpts)

As agent asks questions or needs clarification, paste excerpts or @-mention additional files.

# Layered context example
@ARCHITECTURE.md          (Layer 1: foundation)
@CONVENTIONS.md           (Layer 1: foundation)

Here's the PaymentService I'm refactoring:

[paste PaymentService.js]  (Layer 2: focus)

@vendor/stripe-api.js     (Layer 3: available if needed)

Refactor to use async/await instead of promises.