Context is a budget
Everything a model considers, your instructions, the files you pasted, the tool output, its own previous replies, occupies one finite window. Context engineering is deciding what goes in it. On real codebases this is the difference between a tool that helps and one that confidently edits the wrong file.
Two constraints make it a genuine budget rather than a checklist. It's finite, so adding one thing eventually removes another. And relevance density matters: a window filled with mostly irrelevant material produces worse answers than a smaller window of relevant material, because the signal is diluted.
What to include
| Include | Leave out |
|---|---|
| The file being changed | Files that merely import it |
| Type definitions it depends on | Generated types and lock files |
| One existing example of the pattern to follow | Five more examples of the same pattern |
| The actual failing test or error | The full log surrounding it |
| Conventions the code must obey | The whole style guide |
| Real sample data, anonymised | The entire dataset |
The most valuable single addition is usually one existing example of the pattern you want followed. It communicates naming, error shape, file layout, and test style in one go, far more efficiently than describing any of them.
A conventions file
Rules stated once at the start of a session fall out of context an hour later. Rules kept in a file the tool reads each time do not. Most coding tools support a project file for exactly this.
# Conventions - TypeScript strict. No `any`, no non-null assertions.- No new dependencies without asking first.- Money is integer paise, never floats.- Errors return a discriminated union, never throw across a module boundary. See src/lib/result.ts for the shape.- Tests live next to the file, named *.test.ts.- Don't edit files in src/generated/, they're built.- Keep it short. A thousand-line document consumes the budget it was meant to protect
- Write rules, not aspirations, each line should be checkable against a diff
- Point at one real file per rule rather than describing the pattern
- Update it when you notice yourself giving the same correction twice
Symptoms of a context problem
| Symptom | Likely cause |
|---|---|
| Reverses a decision made earlier in the session | The decision fell out of the window |
| Invents a helper you already have | The existing one was never in context |
| Edits a file with a similar name | It searched, matched loosely, didn't verify |
| Ignores a rule you stated once | Stated in conversation, not in a file it re-reads |
| Quality drops after a long session | The window is now mostly old tool output |
The general fix for all five is the same: start a fresh session with a tight, deliberate context rather than continuing to add to a crowded one. A new context is a feature, not a restart penalty.
A working method
- Scope the task so its files fit comfortablyIf a task needs fifteen files, it's two or three tasks.
- Include one example of the pattern to followThe highest-value item per token you'll add.
- Put durable rules in a conventions fileAnything you'd have to repeat next session belongs there.
- Commit at each working pointSo a fresh session can start from a known-good state with a short summary.
- Start over when quality drops, rather than pushing onTen minutes of re-establishing context beats an hour of correcting drift.
Common mistakes
- Pasting the whole repository and hoping relevance is inferred
- Stating rules in conversation instead of in a file that's re-read
- Continuing a long session after quality has visibly dropped
- Including five examples of a pattern where one would do
- A conventions file so long it becomes the context problem
Key takeaways
- Context is a finite budget, and relevance density beats volume
- One real example of the target pattern is the highest-value inclusion
- Durable rules belong in a file the tool re-reads, not in the conversation
- Drift, reversals, and duplicated helpers are context symptoms, start fresh
Try it yourself
Write a ten-line conventions file for your project from the corrections you've given most often. Use it for a week and add a line every time you repeat yourself.
CHECK YOUR UNDERSTANDING
Pass the quiz below to unlock this.