Giving the AI Context
File references, @-mentions, screenshots, and pasted docs — what to include and what just wastes the window.
Read first: What the AI Can and Can't See
You already know the model answers using only what it can see. This chapter is the practical follow-up: how to decide what to show it, and — just as important — what to leave out.
Reference, don't describe
The instinct is to explain your code in prose. Do not. Point at it. A file reference costs you five characters and gives the model the actual truth instead of your summary of it.
Describing
“We have a user type with an email and some profile fields, I think there’s a role on there too.”
Referencing
“See @src/types/user.ts.”
Every tool has a syntax for this — @filename in Cursor, referencing paths directly in Claude Code, the attachment picker in Copilot Chat. Learn the one your tool uses on day one.
What to attach
For most tasks, three things are enough, and they map onto three different questions the model has to answer:
- 1
The file you want changed
Answers “where does this go?”
- 2
A similar file that already does it right
Answers “what should it look like?” A similar-file example gives the model a concrete convention to follow.
One good example teaches conventions better than a paragraph describing them.
- 3
The type or schema it must conform to
Answers “what shape is the data?” — and stops invented field names dead.
What not to attach
More context is not better. The window is a budget, and filling it with noise pushes out the parts that mattered.
- ×Your whole repo, when the change touches one module
- ×Generated files, lockfiles, and build output
- ×Long files where only one function is relevant — quote the function
- ×Documentation the model already knows (it does not need React's docs pasted in)
Screenshots and errors
Most tools now accept images, and for UI work a screenshot outperforms any description you could write. “The spacing under the header is too tight on mobile” plus a screenshot is a complete brief.
For errors, paste the whole thing. The instinct to tidy it up is the exact wrong move: the stack frames you trimmed are the part that named the file.
The checkout total is wrong when a coupon is applied. Relevant files:- src/lib/pricing.ts (where the total is computed)- src/lib/pricing.test.ts (existing tests, all passing)- src/types/cart.ts (the shapes involved) Steps to reproduce: add two items, apply SAVE10, total showsthe discount twice. Full error from the console:[paste it all, unedited]What you attach is not all that's in there
Everything so far assumes the window has room for what you deliberately attach. It has to share that room with something you are not managing directly: the conversation itself.
Every prior message, every file the model already read, every failed attempt sits in the window whether you meant to keep it there or not. A session that has gone through three wrong approaches to the same bug is carrying all three, and by the fourth attempt the model is reasoning with a full history of dead ends crowding out the actual fix.
The cheapest check there is
Before any substantial request, one line of prompt saves entire rounds of confusion:
Do you have everything you need to do this? If anything ismissing or ambiguous, ask before starting.Models are surprisingly willing to say what they are missing when you invite it. They just never volunteer it, because the default behaviour is to answer.
Key takeaways
- Point at files instead of describing them. Your summary is lossy; the file is not.
- Attach three things: the target, a good example to imitate, and the relevant types.
- A similar-file example gives the model a concrete convention to follow, but people often skip it.
- Do not attach everything — noise pushes the useful parts out of the budget.
- Never attach secrets or customer data. It leaves your machine and does not come back.
- The conversation itself fills the window over time. A session with several wrong turns is often worth restarting rather than correcting again.
- Ask “do you have what you need?” before big requests.
Quick check
Answer these to unlock the next chapter — 3 of 4 to pass. You can retake it anytime.
Answer every question to check.
Make a free account to read on
Every chapter is free — an account is how your progress, XP, and streak follow you from your laptop to your phone, and how you show up on the leaderboard. No payment, no trial.