Context Engineering Introduction

Deciding what goes with every request, and what gets looked up

Animated steps and three labs you can run. Each lab tries every way of sending or looking up its pieces of text.

Decision Q&A

Four questions this volume answers

1Why does this matter?

A model remembers nothing between requests, so your code builds everything it reads. Each piece of reference text is either sent with every request, where you pay for it even when it isn't needed, or looked up when a trigger word appears, where it goes missing whenever the trigger doesn't fire. Neither problem shows up as an error. If everything fits and the extra cost is fine, sending it all is a good place to stop.

Shown in step 1 · 3 · 7
2How would I design it?

Build every request in one place, which records what went in and, when the request is too big, drops text by a rule you wrote. For each piece of text, count its size, how often it's needed, and how often your trigger finds it when it is needed. In the labs, that last count decided what to send every time, not how often a piece was needed. Then send a piece every time when that costs less than looking it up, plus the price of the times the lookup misses.

Shown in step 2 · 4 · 5 · 11
3How would I debug it?

Read the record of the request that went wrong. Was the needed text missing because no trigger fired, or because the text sent every time left no room for it? The two need opposite fixes. Triggers miss because people don't use your words: “put it back the way it was” needed the rollback rule and used none of its trigger words. Also look for out-of-date copies of the text, and text cut off without warning, in code that builds its own requests.

Shown in step 2 · 5 · 6
4How would I take it to production?

Decide what a wrong answer costs you. No measurement can tell you, and changing it changed the best choice on all three jobs. Check again whenever your size limit changes, because the one-line rule stopped working at smaller limits. Find out whether the text you send every time can be cached: if it can, sending it is cheaper than these labs assume. Keep the request records, so you can reproduce any answer.

Shown in step 2 · 10 · 11 · 12

Introduction

You have several pieces of reference text: a style guide, a how-to guide, an API reference, a policy for escalating problems. You have no clear rule for which ones to send with every request and which ones to look up only when needed. So teams send all of them, or none of them, and both choices go wrong.

The model only sees what you send

  • A model remembers nothing between requests.
  • It can't read your files or your systems.
  • It knows nothing about your product.

Your program builds everything the model reads, on every request. Wording the prompt well doesn't fix that. You have to decide, piece by piece, what goes in.

What context engineering is

Context engineering means choosing, on purpose, what text you send to the model with each request, and checking that your choice works.

Each piece of text gets one of two treatments:

  • Carried: sent with every request, whether that request needs it or not.
  • Fetched: looked up only when the request contains one of its trigger words. A trigger is the rule in your code that decides when to look a piece up.

The two go wrong in opposite ways.

treatmentin the requesthow it goes wrong
carriedevery requestwaste: you pay for it on requests that didn't need it
fetchedonly when its lookup firesmissing: a request needed it, the lookup didn't fire, and nothing tells you

Cutting one problem makes the other bigger. That's why “send less” and “look up more” don't work as plans on their own.

Is this for you?

It depends on how much text you have, and how unevenly it's needed.

if…then
everything fits in the size limit with room to sparesend it all and stop. You don't need this volume.
one piece is a large share of all your textyou have a real choice to make. Read step 9.
some text is rarely needed, but costly to be withoutyou have a real choice to make. Read step 10.
you can't say which pieces your lookups reliably findstart at step 5. On one job here, that alone decides everything.

What you'll get

  • A list of questions to work through in order. If everything fits, you can stop at the third one.
  • A one-line rule you can use without running anything, and the point where it stops working.
  • Three labs you can run on your own computer. The next section explains them.
Two of the three jobs let you send everything and stop. The pages say so, and show what that costs. If your whole bill is small, you can stop at the third question.

The labs: what they are

Each lab is a small Python program you download and run yourself. Once you own the volume, the Download the labs button at the top of this page gives you all three in one zip. Each lab plays out one job:

  • Code review: an AI reviews pull requests against a team's rules.
  • Support desk: an AI answers customer questions.
  • Deploy runbook: an AI handles requests to ship code.

Each job has 30 requests and six pieces of reference text, such as a style guide or a list of who approves what. For every piece, the lab tries both choices: send it with every request, or look it up only when the request seems to need it. It runs every combination and counts:

  • how many answers came out right;
  • how much text the model had to read, which is what you pay for;
  • which requests went out without a piece they needed, and why.

What you do in the labs

  • Follow one request through, and watch a lookup miss the text it needed.
  • Send it again with that text carried, and see what that costs on every request.
  • Run the whole job three ways, and compare the answers and the bill.
  • Afterwards, change the size limit or the price of a wrong answer, and watch the best choice change.

The guided lab is lab.py. The labs folder also has run.py, which prints detailed tables, and some steps ask you to run it.

What you'll learn

  • When it's fine to send everything, and what that costs.
  • Why a piece needed on most requests can be the one to look up, and a piece needed rarely can be the one to send every time.
  • Why lookups miss: people don't use the words a lookup is waiting for.
  • A one-line rule for deciding, and how to tell when it stops working.

Two ways to run them

waythe modelwhat it coststhe numbers
scripteda stand-in rule: right whenever it has every piece it needsfree, and works offlinethe same every run. These pages quote them.
livea real model: Claude through the API, Claude Code, or an OpenAI modelreal calls: you pay per call, or it uses your Claude Code plandifferent from these pages, and a little different each run

All three labs can run either way.

Before a live run

  • Run the setup script in the labs folder. It installs everything a live run needs.
  • Pick a model and put its key in the settings file, labs/.env. For Claude Code you need no key. The labs' README shows every line.
  • Check the connection with one tiny call. It costs well under a cent.
  • Start the run. Before sending anything, it shows how many calls it will make and what they should cost, and waits for you to type yes. A spending cap stops the run if costs go over, and every answer is saved, so you never pay twice for the same request.
Your live numbers will differ from these pages. The scripted model never misses a rule it was given, and never knows one it wasn't. A real model does both, and a little differently each time. When an answer goes wrong, the live run tells you which of the two happened: the rule wasn't sent, or it was sent and the model missed it.

The scripted lab is also stricter than a real reviewer. It marks an answer wrong if any document the request could use is missing, even one that only covers a side point. A live run marks only what the question asked, so the same choice can score higher there.

How to read the labels

Each step has a label that tells you where its content comes from.

labelmeans
conceptexplained from first principles; no lab numbers
measureda lab compares choices and reports the difference
laba guided lab you run yourself, step by step
your own texthow to use the method on your own documents
These labs are not a benchmark. They use three jobs, a scripted model, and prices that are realistic but made up. Step 12 lists every limit, starting with the one that could change every conclusion here.