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.

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.

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.

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.

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.

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