Giving the AI Context
File references, @-mentions, screenshots, and pasted docs — what to include and what just wastes the window.
Worth reading 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?” This is the one people skip, and it is the highest-value attachment you can make.
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]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.
- The similar-file example is the highest-value attachment and the one most people skip.
- 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.
- Ask “do you have what you need?” before big requests.