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.