04 · Context Engineering Basics

Prompting is what you say. Context engineering is everything the model can see when it answers. In modern AI development it is the skill that separates average results from excellent ones.

Level 135 minTrack 4 · Context & memory

By the end of this page you can

List the sources of context in an AI-enabled IDE and how each gets into the model.
Decide what to include, what to leave out, and when to start a new session.
Use @-mentions, selections, rules files and docs to ground the model.
Recognise context rot, "lost in the middle" and context pollution, and fix them.

What is context?

Context is the complete set of tokens the model receives for a single response. In a modern coding assistant, that is much more than your message:

Left: instructions and history. Right: information gathered from your workspace and tools. All of it competes for the same token budget.

The central insight The model only knows (1) what it learned in training and (2) what is in the context right now. It cannot see your repository, your team's conventions, yesterday's chat, or the library version you use unless something puts that information into the context.

Why "more" is not "better"

Large windows tempt people to paste everything. That causes problems:

Problem	What happens	Remedy
Lost in the middle	Details buried in a long context get less attention than those at the start or end.	Put the key instructions and the most relevant code near the end, close to the question.
Context pollution	Irrelevant files, old failed attempts and wrong turns distract the model.	Include only what is relevant. Start fresh sessions for new tasks.
Context rot	Quality degrades as a long session accumulates.	Summarise and restart, or let the tool "compact" history.
Conflicting instructions	Old rules and new requests contradict each other.	Keep rules files current and remove stale ones.
Cost & latency	Every token is processed (and billed) on every turn.	Be selective. Use references instead of pasting whole files.

The four moves of context engineering

Write durable context once: rules files and AGENTS.md describing the project, stack, commands and conventions (page 07).
Select the right context per task: @-mention specific files, symbols, docs or a selection, rather than the whole repo.
Compress what is long: summarise previous work, keep a short "progress notes" file, or ask the tool to compact.
Isolate unrelated work: one task per session. Let sub-agents explore in their own context and return only a summary (page 08).

Practical tools in the IDE

Mechanism	What it does	When to use
Selection	Highlight code, then ask. The selection goes into context.	Explaining or editing one function.
@-mentions / #-references	Explicitly attach files, folders, symbols, docs, terminal output or git changes. The syntax varies by tool.	When the answer depends on specific files.
Codebase indexing / search	The tool searches your repo (text and/or semantic) and pulls in relevant snippets.	"Where is X handled?" questions.
Rules / instructions files	Always-on project knowledge.	Conventions, commands, architecture.
Skills	Packaged know-how loaded only when relevant.	Repeatable procedures (release, migration, review).
MCP servers	Live data from external systems: docs, tickets, databases, build tools.	Context that lives outside the repo.
Images	Screenshots of UIs, diagrams or errors.	UI bugs, whiteboard designs.

Good context checklist

Goal: what you want and why. The "why" helps the model make good judgement calls.
Environment: language and versions (Scala 3.x / Python 3.12), build tool, framework, OS.
Relevant code: the function, its callers or types, an existing example of the pattern to follow.
Evidence: exact error messages, logs and failing test output. Paste them, don't paraphrase.
Constraints: performance, compatibility, style, what must not change.
Definition of done: how you will verify the result.

Grounding with documentation

Models have a training cutoff, and libraries change. If you use a new version of a library (for example a recent release of a Scala effect library), the model may confidently use old APIs. Fix it by grounding:

Paste the relevant section of the official docs or the changelog.
Point the agent at the library's source or .d.ts/.scala signatures in your dependencies.
Use a docs MCP server or web search tool if your tool supports it.
Let the agent compile. The compiler is the best grounding tool, especially in Scala.

Strong types are context In statically typed languages like Scala, type signatures carry a lot of meaning in very few tokens. Showing the model def transfer(from: AccountId, to: AccountId, amount: Money): IO[Either[TransferError, Receipt]] tells it more than a paragraph of prose. Agents that can compile get immediate feedback when they are wrong.

Session hygiene

One task, one session. Starting a new chat is free. Polluted context is expensive.
Hand-off notes. At the end of a long session ask: "Summarise what we did, decisions made, and what remains, as a note I can paste into a new session." Paste it into the next session.
Progress files. For multi-day agent work keep a NOTES.md or PLAN.md in the repo that the agent updates. It survives restarts.
Delete stale instructions. Outdated rules mislead every future session.

Memory: what products mean by it

Some assistants have "memory" features. Technically this is context engineering done by the product: it saves facts ("prefers Scala 3, uses MUnit") and inserts them into future prompts. Treat memories like rules files. Review them, keep them accurate, and know they can be wrong or stale.

Try it (10 min) In your IDE assistant, ask "How are errors handled in this project?" twice: once with no files attached, and once after @-mentioning two relevant files. Compare the specificity. Then add one line to a rules file (for example "We use Either for recoverable errors, never exceptions") and ask again in a new session.

Key takeaways

The model sees only its context. Your job is to curate it.
Write, select, compress, isolate.
Relevant beats more. Put key information close to the question.
Ground the model with docs, types, errors and the compiler.
Use fresh sessions and hand-off notes to avoid context rot.