The field guide

Context engineering

A practical guide to the discipline that decides what a model sees. Retrieval, agent patterns, reliability, evaluation, and the failure modes that break long-context systems, each with a runnable example.

A field guide by James Phoenix

The models got good at following instructions. That quietly moved the bottleneck. The hard part of building with an LLM is no longer wording a clever prompt, it is deciding what information the model gets to see at all. That job is context engineering, and it is most of the work in any serious system.

A model has no memory of you and no window onto your world beyond the text in front of it. So every answer is capped by the context you assemble: the files, the examples, the history, the tool results, in a finite window where everything you add crowds out something else. Get the right things in, keep the wrong things out, and shape what remains. That is the whole game, and this guide is a map of the moves.

Most of it arrives in a predictable order. You get retrieval working, then discover it returns the wrong passages and reach for reranking and hybrid search. Then output shape becomes the problem, so you add structured outputs and a guardrail. Then you realise you have been changing prompts on feel and need an eval set to know whether anything improved. And eventually sessions run long enough that context rot shows up. The reading paths below follow that order.

The map below breaks the field into its main areas, from retrieval to the ways long context breaks, each linking through to a definition with a tested example you can run. Below that are the field notes, where I work the same ideas through on real systems.

Browse all 36 terms in the Context Engineering Dictionary

Every entry is typed, so you can tell a practice from a failure mode at a glance: 21 patterns, 5 antipatterns, and 10 concepts.

The dictionary

The areas it covers

The full vocabulary is organised into these areas. Skim them for the shape of the field, then open any one for its definitions.

Reading paths

Where to start

Context engineering is wide, and most of it only matters once you hit the specific problem it solves. These paths go in the order the problems actually arrive: get something retrieving, make it reliable, find out whether it works, then deal with what breaks over time.

Start here: deciding what the model sees

For: Building with an LLM and want the fundamentals

  1. Context engineeringThe discipline, and why it is most of the work.
  2. Context windowThe finite budget everything competes for.
  3. RAGThe workhorse pattern: retrieve, then generate from what you retrieved.
  4. EmbeddingsHow similarity gets computed, and what it is bad at.
  5. ChunkingThe quiet decision that makes or breaks retrieval.
  6. Progressive DisclosureLoad only what the task needs, when it needs it.

Making retrieval actually work

For: RAG is running and the answers are not good enough

  1. ChunkingStart here, because most retrieval problems begin at the cut.
  2. Contextual retrievalChunking strips the context a chunk needs to be findable. This puts it back.
  3. Hybrid searchEmbeddings miss exact strings. Keyword search misses meaning. Run both.
  4. RerankingRetrieve widely and cheaply, then reorder with something accurate.
  5. Vector databaseAnd why you very often do not need one.
  6. Vectorless RAGLetting a model navigate a tree instead of embedding anything.

Knowing whether it works

For: Changing prompts on feel and want to stop

  1. Eval setFixed inputs, so the only thing varying is your system.
  2. RubricWhy "rate this 1 to 10" produces numbers that mean nothing.
  3. LLM-as-judgeScoring fuzzy, open-ended work at scale.
  4. Pairwise comparisonRelative judgements are far steadier than absolute ones.
  5. GoodhartingHow the score climbs while the product gets worse.

When long sessions break

For: Quality degrades the longer a session runs

  1. Lost in the middleA bigger window does not mean better recall.
  2. Context rotGradual decay as stale text accumulates. Nothing fails at any single step.
  3. Context pollutionOne wrong passage steering everything after it.
  4. Prompt injectionPollution with intent behind it.
  5. Context Rot PreventionCompacting the sediment before it degrades the session.
  6. Externalized stateThe structural fix: if the durable facts are on disk, a bloated window stops being a loss.
  7. CheckpointSo you can stop a session you no longer trust instead of nursing it along.
Field notes

From the notes

The dictionary tells you what each term means. These are the essays behind them: longer pieces where I work the same ideas through on real systems, and note what held up and what broke. Read whichever one matches the problem in front of you, or follow them from foundations down to the ways long context falls apart.

Deciding what the model sees

The first job in any system: choosing what goes into the window and what stays out.

Keep reading

AI Native Software Engineering

The other half of the picture: the vocabulary and workflow of building software with AI agents, from tokens and context windows to tools, subagents, and review discipline.

Go to the guide →
FAQ

Common questions

What is context engineering?

It is the discipline of deciding what a model sees. A model can only work from the text in front of it, so the quality of any answer is capped by the context you assemble: the files, examples, history, and tool results you fit into a finite window. Getting that right is most of the work in any serious LLM system.

Is context engineering just prompt engineering with a new name?

No. Prompt engineering is about wording a single instruction well. Context engineering is the larger job of choosing what information reaches the model at all: what to retrieve, what to leave out, how to compress history, and how to keep the window useful as a task grows. The prompt is one small part of the context.

What is the context window?

The context window is the maximum amount of text, measured in tokens, that a model can consider for a single request. It is a hard ceiling and a shared budget: the system prompt, the history, the files, and the tool results all compete for the same space, so every token you add crowds out another.

What is RAG and do I need it?

RAG, retrieval-augmented generation, means pulling the material relevant to a request into the context so the model answers from it rather than guessing from memory. You need some form of retrieval whenever the answer depends on information the model was not trained on, like your own docs or code.

Do I always need embeddings to do retrieval?

No. Embeddings and vector search are one option, good for fuzzy matching across a large corpus. But you can also let a model navigate a document tree, follow links in a knowledge graph, or read a file you point it at directly. The right retrieval is whatever puts the correct material in the window most reliably.

What is chunking and why does it matter?

Chunking is splitting a long document into smaller pieces before you embed and retrieve them. The size and overlap of the chunks decide what can be found as a single unit, so it quietly makes or breaks a retrieval system. Chunk too big and you waste the window, too small and you lose the meaning.

What is the difference between memory and the context window?

The window is what the model can see right now, and it resets every session. Memory is an external store the system keeps and reloads into the window when it is relevant. The model itself remembers nothing between requests, so anything that has to persist lives in memory, not in the model.

Why do long conversations get worse over time?

Two reasons. Context accumulates like sediment, so old and irrelevant text crowds out what matters, which is context rot. And models attend best to the start and end of a long window while missing the middle. Compaction, clearing, and careful budgeting are how you fight both.

What is the lost in the middle problem?

It is the tendency of a model to use information at the start and end of a long context well while missing what sits in the middle. It means a bigger window does not automatically mean better recall. If a fact matters, put it where the model actually looks rather than burying it halfway down.

What is compaction?

Compaction is condensing older conversation history into a summary to reclaim window space while keeping the important gist. It is lossy by design, so the art is in summarising the trajectory and the decisions, not just the last few messages, so the agent can keep going without relearning everything.

What is progressive disclosure?

Progressive disclosure is revealing detail to the model only when it is needed, through pointers and on-demand loading, instead of dumping everything into the window up front. You show what exists and its cost, then load the specific piece when the task calls for it. It saves both space and attention.

How do I stop an agent running out of context?

Treat the window as a budget. Load information only when a task needs it, point to large files instead of pasting them, compact or summarise old history, and hand off to a fresh session with a short state document when the window fills. The goal is to keep the highest-value tokens in and everything else out.

My retrieval returns the wrong passages. What do I fix first?

Chunking, almost always. Most retrieval problems start at the cut: pieces too small to be meaningful, too large to be precise, or severed from the context that made them findable. Fix that first, then add contextual retrieval so each chunk carries where it came from. Only after that is hybrid search or reranking worth reaching for. Swapping vector databases is almost never the answer.

Why does the answer look confident but wrong?

Usually one bad passage in the context rather than anything wrong with the model. Context pollution is a single wrong or outdated item steering everything downstream of it, and the model reasons from it correctly, which is what makes the output so plausible. When something looks wrong, read the context that was actually assembled before touching the prompt. The false premise is usually sitting there in plain text.

How do I stop my eval score improving while quality gets worse?

That is goodharting, and it arrives faster in LLM systems than people expect because a prompt can be reshaped in seconds against a fixed score. The defences are holding out cases you never tune against, keeping metrics that trade off against each other so you cannot inflate both, and reading actual outputs by hand. A rising score with flat user-reported quality is the diagnostic, and you should believe the users.

How do I tell whether my context is actually good?

You measure it. Build a set of real cases with known good answers and score your system against them, using a model as a judge for the fuzzy ones. Evaluation turns context engineering from guesswork into something you improve on purpose, one change at a time.

When should I use an agent instead of a fixed workflow?

A workflow follows a path you designed in advance; an agent decides its own path at run time by calling tools in a loop. Use a workflow when the steps are known and you want reliability, and an agent when the path genuinely depends on what it finds along the way. Choosing correctly is the first context-engineering decision.

Is context engineering only relevant for RAG chatbots?

No. Any time you work with a model, from a coding agent to a data pipeline, you are deciding what it sees. Retrieval is one part. Memory, history management, tool results, specs, and handoffs are all context engineering. It is the substrate under every serious LLM application, not a single feature.

Want this applied to your product?

The dictionary is how I think out loud. If you want that thinking turned into a working system for your team, that is what I do.

See how I can help