L3Lesson 1

Tell the Model What to Look At

After this, you'll be able to use @ context references to point the model at the exact files it needs, so your answers are grounded in your actual code instead of a guess.

Before you start

Before diving in, complete Edit Without Rewriting so you have the file-sharing instinct this lesson extends from single documents to full codebase references.

The idea

You ask Claude to fix an auth bug. It asks which file. Three minutes of back-and-forth. Or: you type @auth.ts and @types/api.ts before your question, and Claude opens with "I see you're using JWT validation in line 23, and the refreshToken field on line 47 doesn't match what the API returns." That's the unlock.

Cursor, Claude Code, and Windsurf all support @ references: type @filename, @foldername, or @symbol and the IDE injects that content directly into the context window. The model does not guess. You decide what it sees.

Here is the before and after: A developer was seeing a confusing auth bug and opened chat without any @ references. The model gave a generic answer about JWT expiry. Then they typed: "@src/types/api.ts @src/services/auth.ts Can you trace why refreshToken is returning undefined?" The model now had the actual type definitions and the implementation in front of it. It found the bug in 30 seconds: a field name mismatch between what the API returned and what the service expected.

The habit shift is simple but requires deliberate practice. Before you ask anything about a bug, a refactor, or an unfamiliar function, ask yourself: what does the model need to see to answer this well? Then @ those files before you type your question. A generic answer almost always means missing context, not a bad model.

Try it (14 min)

Watch out for

Asking questions without @ references and then wondering why the answer is generic. Generic in, generic out.
@ referencing every file in the project for every question. More is not better. Point at what is relevant to this specific question.
Forgetting that @ references do not persist between sessions. Re-add them each time.
Using @folder on a large src/ directory when @specific-file would be sharper. Broad references add noise alongside signal.
Relying on codebase indexing to substitute for explicit references. Indexing helps with search; it does not replace deliberate context injection.

Paste this into Claude:

I have a question about my codebase: [describe a bug or feature question you currently have]. Before I ask it, I want to use @ references correctly. Help me decide: which specific files should I reference to give you the best context to answer this? Once you tell me, I will add those @ references and re-ask the question. Then compare both answers, the one without context and the one with, and tell me what changed.

What good looks like:

You asked the same question twice: once without @ references and once with the files the model asked for
The second answer used your actual type names, function signatures, or variable names from your codebase
You can name the two or three files you would always @ reference when debugging in your project
You caught at least one case where the model's first answer was a plausible-sounding guess that did not match your code
You now open relevant files before asking, not after getting a wrong answer

What a good response looks like:

Before @ references, your question was: "Why is my auth breaking?" My answer was generic: JWT tokens expire after the default 1-hour window, check your expiry settings.

After you added @src/types/api.ts and @src/services/auth.ts, I can see the actual issue. Your ApiUser type on line 14 has `refresh_token` (snake_case), but your AuthService on line 47 reads `user.refreshToken` (camelCase). The field name mismatch means `refreshToken` is always undefined, which triggers the fallback path and logs the user out.

Files to always @ reference when debugging auth in this project: src/types/api.ts (your API response shapes), src/services/auth.ts (the implementation), and src/middleware/requireAuth.ts (the validation logic). Those three files together cover 90% of auth questions. Without them, I'm guessing at your field names and I'll guess wrong.

Go deeper (20 min)

Paste this into Claude:

Take a multi-file change you made last week (or one you need to make this week). Before you ask the model to implement it, write out every file that needs to change and @ reference each one. Then ask the model: "Given these files, what is your plan for making this change? What do you need to know before you start?" Compare the plan you get with @ references to what you would have gotten with a plain text description of the task. What did the model catch that you did not mention?

What good looks like:

You listed every file involved before starting the task, not mid-way through
The model's plan referenced specific function names, types, or imports from your actual files
The model asked at least one clarifying question that revealed a gap in your original description
You made the change with fewer back-and-forth turns than a typical session without pre-loaded context

What a good response looks like:

With your @ references loaded (@src/models/User.ts, @src/api/users.ts, @src/components/UserForm.tsx, @tests/api/users.test.ts), here is my plan for adding the email field.

Step 1: Add `email: string` to the User interface in src/models/User.ts at line 8, after the existing `username` field. I'll also mark it required since the registration flow always collects it.

Step 2: Update the POST /api/users endpoint in src/api/users.ts. The `createUser` function on line 34 already validates required fields via the `validateUserInput` helper. I'll add email to that validation list and to the database insert on line 51.

Step 3: Add the email input to UserForm.tsx. The form currently uses a controlled input pattern with `useState` for each field. I'll follow that exact pattern for consistency.

Step 4: Update the test on line 22 of users.test.ts that asserts on the user shape. One test will fail without this update.

Something you did not mention: there is a `sanitizeUser` function on line 67 of src/api/users.ts that strips fields before the API response. Email is not in its allowlist, so it would be silently dropped from responses. Do you want me to add it there too?

When this breaks

Breaks when the bug crosses a system boundary the @ reference does not cover (a backend type and a frontend handler) because the model still guesses about the half it cannot see.
Degrades when @folder grabs a directory with hundreds of files because the relevant lines drown in unrelated context and retrieval-style noise reappears inside your window.
Breaks when you treat @ references as permanent context and assume the next session inherits them, since every new chat starts blank and the file set must be re-declared.

Claude can do it for you

Before any debugging session, tell Claude: "I am going to ask you about [topic]. What files or types would you need me to reference to answer this well? List them." Then add those @ references to your next message. Claude will tell you exactly what to pre-load.

You can now

Demonstrate the same question answered twice (once without and once with @ references) where the second answer cites real symbols from your codebase that the first one missed.

Key takeaways

You decide what the model sees. @ the files before you ask the question, not after you get a wrong answer.

@ references inject specific files, folders, or symbols into context so the model stops guessing
Pre-load context before the question, not after the wrong answer. A generic reply usually means missing files, not a weak model
Sharper is better. @ the two or three files that matter, not the entire src/ directory
References do not persist across sessions. Re-declare them every time you open a new chat

Go deeper

I have a question about my codebase: [describe a bug or feature question you currently have]. Before I ask it, I want to use @ references correctly. Help me decide: which specific files should I reference to give you the best context to answer this? Once you tell me, I will add those @ references and re-ask the question. Then compare both answers, the one without context and the one with, and tell me what changed.

Before @ references, your question was: "Why is my auth breaking?" My answer was generic: JWT tokens expire after the default 1-hour window, check your expiry settings. After you added @src/types/api.ts and @src/services/auth.ts, I can see the actual issue. Your ApiUser type on line 14 has `refresh_token` (snake_case), but your AuthService on line 47 reads `user.refreshToken` (camelCase). The field name mismatch means `refreshToken` is always undefined, which triggers the fallback path and logs the user out. Files to always @ reference when debugging auth in this project: src/types/api.ts (your API response shapes), src/services/auth.ts (the implementation), and src/middleware/requireAuth.ts (the validation logic). Those three files together cover 90% of auth questions. Without them, I'm guessing at your field names and I'll guess wrong.

Take a multi-file change you made last week (or one you need to make this week). Before you ask the model to implement it, write out every file that needs to change and @ reference each one. Then ask the model: "Given these files, what is your plan for making this change? What do you need to know before you start?" Compare the plan you get with @ references to what you would have gotten with a plain text description of the task. What did the model catch that you did not mention?

With your @ references loaded (@src/models/User.ts, @src/api/users.ts, @src/components/UserForm.tsx, @tests/api/users.test.ts), here is my plan for adding the email field. Step 1: Add `email: string` to the User interface in src/models/User.ts at line 8, after the existing `username` field. I'll also mark it required since the registration flow always collects it. Step 2: Update the POST /api/users endpoint in src/api/users.ts. The `createUser` function on line 34 already validates required fields via the `validateUserInput` helper. I'll add email to that validation list and to the database insert on line 51. Step 3: Add the email input to UserForm.tsx. The form currently uses a controlled input pattern with `useState` for each field. I'll follow that exact pattern for consistency. Step 4: Update the test on line 22 of users.test.ts that asserts on the user shape. One test will fail without this update. Something you did not mention: there is a `sanitizeUser` function on line 67 of src/api/users.ts that strips fields before the API response. Email is not in its allowlist, so it would be silently dropped from responses. Do you want me to add it there too?

Before any debugging session, tell Claude: "I am going to ask you about [topic]. What files or types would you need me to reference to answer this well? List them." Then add those @ references to your next message. Claude will tell you exactly what to pre-load.