Context Engineering

Prompt engineering taught you to write a clear instruction. Function calling and the Model Context Protocol (MCP) added tool schemas, tool results, and external resources. Once an agent works through several steps, its request contains much more than a prompt: instructions, tool definitions, retrieved text, conversation history, intermediate results, and saved state.

A model's context window is the token capacity available for that request. Context engineering decides which tokens deserve a place in it at each step. Capacity asks whether the request fits; context engineering asks whether each included item helps the model make the next decision.

More tokens don't guarantee better answers. A request may sit far below its limit yet perform worse than a smaller curated packet because irrelevant tools, stale results, or wrong intermediate claims remain active. Compare curation policies on answer quality, latency, and cost instead of treating available capacity as permission to include everything.

How does context engineering differ from prompt engineering and context capacity?

Answer

Prompt engineering improves one instruction. Context capacity sets how many tokens a request can hold. Context engineering curates the instructions, tools, evidence, history, and state that enter each request so the model reasons on a small high-signal set.

A longer trace can make the agent worse

Picture an incident agent investigating why deploy RUN-842 failed its canary. It reads the deploy record, checks CI logs, searches rollback runbooks, and follows request traces. Every tool call dumps its raw output back into the conversation. After forty turns the context holds: the original alert, four full runbooks (most of which were a dead end), six multi-thousand-token trace exports, three issue-search results, and one early hallucinated guess that a database migration lock caused the outage.

The agent now performs worse than it did at turn five. It re-runs the dead-end issue search, cites a migration lock that doesn't exist, and picks a verbose, irrelevant rollback paragraph over the trace span that matters. The window is nowhere near full, yet the agent is failing.

This isn't a tool-protocol or prompt-wording problem. Every tool returned a valid payload, and the request fits. The active context has accumulated low-signal and even wrong tokens, and the model is attending to all of them. Context engineering is the set of techniques that would have prevented this failure. The failed-canary agent will anchor the rest of the chapter.

Context includes more than the instruction

For a few years the applied-AI conversation was dominated by prompt engineering: finding the right words and phrasing for a single instruction. Anthropic frames context engineering as the natural successor to that practice.^{[1]Reference 1Effective context engineering for AI agentshttps://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents} Prompt engineering is about writing one good instruction. Context engineering is the broader discipline of curating and maintaining the entire set of tokens present during inference: the system prompt, tool definitions, retrieved documents, conversation history, tool results, and any memory loaded back in.

Anthropic's framing is a useful operating objective because it gives you a single guiding principle:

Find the smallest set of high-signal tokens that maximize the likelihood of your desired outcome.^{[1]Reference 1Effective context engineering for AI agentshttps://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents}

Every technique below tests a way to approach that minimal, high-signal set. A 2025 survey organizes the same strategies into a formal taxonomy.^{[2]Reference 2A Survey of Context Engineering for Large Language Models.https://arxiv.org/abs/2507.13334}

Why is "context engineering" framed as the successor to "prompt engineering" rather than a replacement?

Answer

Prompt engineering optimizes the wording of one instruction. Context engineering keeps the prompt-writing skill but expands the scope to the entire token set entering the model at inference: tools, retrieved docs, history, tool results, and memory. The goal becomes curating the smallest high-signal set, rather than phrasing one message well.

Why curation needs evaluation: context rot

The reason you shouldn't assume "just add more" is empirical, not stylistic. Chroma's Context Rot report evaluated 18 models across increasing input lengths and reported non-uniform performance as input grew, including on simple retrieval and copying tasks.^{[3]Reference 3Context Rot: How Increasing Input Tokens Impacts LLM Performancehttps://research.trychroma.com/context-rot} The magnitude and shape depend on model, task, and distractors; additional tokens are a hypothesis to evaluate, not free signal.

Anthropic describes the same engineering concern with an "attention budget" mental model and recommends seeking the smallest high-signal token set that supports the desired outcome.^{[1]Reference 1Effective context engineering for AI agentshttps://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents} Padding a window with low-signal tokens always increases input cost and can lower workload quality; a paired evaluation should determine when.

Context rot is one reason behind the techniques below. Cost, latency, stale state, and contradictory evidence are others. Curation should be an explicit candidate policy with quality checks, not an article of faith.

Define context rot and explain why it makes curation worth evaluating.

Answer

Context rot is the reported pattern that reliability can degrade as input token count grows, including before the hard limit is hit. It means an engineer should measure whether adding context helps a workload, and compare it with a curated high-signal alternative.

Four failure modes of an overloaded context

Before fixing context, you need vocabulary for how it breaks. Drew Breunig describes four useful failure-mode labels for long contexts.^{[4]Reference 4How Long Contexts Failhttps://www.dbreunig.com/2025/06/22/how-contexts-fail-and-how-to-fix-them.html} They are diagnostic categories, not a formal completeness proof. Each one can show up in our failed-canary agent.

Don't turn reported examples into universal thresholds. Breunig cites an agent anecdote where long history encouraged repeated actions and a tool-use experiment where reducing tool count improved one model's benchmark result.^{[4]Reference 4How Long Contexts Failhttps://www.dbreunig.com/2025/06/22/how-contexts-fail-and-how-to-fix-them.html} Those observations justify testing history pruning and tool gating on your model, tools, and task distribution.

The write, select, compress, isolate taxonomy

Naming failure modes tells you what went wrong. LangChain organizes agent context strategies into four useful buckets: write, select, compress, and isolate.^{[5]Reference 5Context Engineering for Agentshttps://blog.langchain.com/context-engineering-for-agents/} The LLM acts like a CPU, and its context window acts like RAM: a working set to manage deliberately. The buckets classify many common tactics without claiming they exhaust every design.

Write: keep state outside the window

The cheapest token is the one you never put in the window. Write means persisting information outside the context so it doesn't consume the attention budget until it's needed.^{[5]Reference 5Context Engineering for Agentshttps://blog.langchain.com/context-engineering-for-agents/} The classic pattern is a scratchpad: the agent writes notes, plans, or intermediate findings to a file or a state field, then reloads only the relevant note later. Agentic memory works the same way, persisting durable facts across sessions.^{[6]Reference 6Agent Memory: How to Build Agents that Learn and Rememberhttps://www.letta.com/blog/agent-memory/}

For the failed-canary agent, a write strategy means: instead of leaving four full runbooks in the conversation, the agent records "auth callback errors confirmed; migration lock ruled out" as a one-line note and drops the raw tool results. The finding survives; the tokens don't.

Select: pull in only what this step needs

Select means retrieving only the tokens relevant to the current step.^{[5]Reference 5Context Engineering for Agentshttps://blog.langchain.com/context-engineering-for-agents/} Retrieval-augmented generation (RAG) applies that idea to documents: a retriever surfaces a small set of relevant chunks instead of dumping the whole corpus into one request. Selection also applies to tools. The confusion failure mode above appears when an agent loads all 50 tools instead of the 5 needed for its current phase.

Prompt caching is a separate efficiency tactic: when requests reuse a stable prefix, a provider may avoid repeating part of the work needed to process it.^{[7]Reference 7Prompt caching.https://docs.anthropic.com/en/docs/build-with-claude/prompt-caching} Caching does not select better evidence or reduce the number of tokens the model reasons over. It improves eligible repeated-prefix economics only when the provider and cache policy support it.

Compress: shrink what must stay

When information has to stay in the window, compress reduces it to the required tokens.^{[5]Reference 5Context Engineering for Agentshttps://blog.langchain.com/context-engineering-for-agents/} Two common candidate patterns follow.

The first is compaction: when a conversation approaches the budget, summarize it and start a fresh window seeded with that summary.^{[1]Reference 1Effective context engineering for AI agentshttps://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents} The agent keeps its working knowledge but sheds the verbose transcript that produced it.

The second is tool-result pruning, a low-risk candidate fix for our failed-canary agent. Anthropic describes clearing old tool results as a light-touch form of compaction: once the relevant finding has been captured, old raw results can often leave the active context.^{[1]Reference 1Effective context engineering for AI agentshttps://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents} Preserve evidence that the next decision still needs, and compare quality before adopting an aggressive pruning policy.

Isolate: split work across focused windows

Isolate means splitting context across focused workers so no single window has to hold every exploratory trace.^{[5]Reference 5Context Engineering for Agentshttps://blog.langchain.com/context-engineering-for-agents/} A lead agent delegates a focused subtask, such as "check linked issues and rollback notes for every failed-canary exception", to a worker with its own clean context window. The worker does noisy exploration in isolation and returns a bounded evidence summary to the lead.^{[1]Reference 1Effective context engineering for AI agentshttps://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents}

Isolation can reduce distraction and confusion because the lead doesn't need every intermediate search result. It also adds coordination overhead and creates clash risk when worker outputs disagree, so isolate is a candidate for separable exploration, not a default.

Map each of the four context-engineering moves to a concrete technique, then to the failure mode it most directly fights.

Answer

Write (scratchpad or memory file) keeps tokens out of the window entirely. Select (RAG, tool gating) pulls in only relevant items and fights confusion. Compress (compaction, tool-result pruning) shrinks history and fights distraction and poisoning. Isolate (sub-agents) splits work into clean windows and fights distraction and confusion.

Package repeatable procedures as Agent Skills

A tool gives an agent an action such as reading a file or querying a trace. A prompt gives instructions for one conversation. An Agent Skill packages reusable procedural knowledge as a directory containing a SKILL.md file and optional scripts, references, and assets.^{[8]Reference 8Agent Skills Specificationhttps://agentskills.io/specification} The agent can discover the Skill from its metadata, load its instructions when relevant, and fetch deeper resources only when the task calls for them.^{[9]Reference 9Agent Skillshttps://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview}

That loading pattern is progressive disclosure. Instead of placing every runbook in every prompt, the runtime first exposes a small name and description. A matching task activates the full SKILL.md; a specialized reference or script stays outside the window until the instructions point to it. This is context selection implemented as a reusable package.

Skills, tools, and harness state solve different problems:

Build a small Skill package

Suppose the incident agent repeatedly performs the same triage procedure. Package that procedure instead of pasting a long runbook into every task. The Agent Skills specification requires name and description in SKILL.md frontmatter. It also defines conventional scripts/, references/, and assets/ directories whose contents can be loaded when needed.^{[8]Reference 8Agent Skills Specificationhttps://agentskills.io/specification}

The description is part of the routing surface. It needs both capability and trigger language, while the body should keep only steps needed on most runs:

The skill doesn't need a full rollback runbook in its main file. references/handoff-contract.md can define the worker response schema, while validate-handoff.py can check it deterministically. Only the validator's output needs to enter the model context when the script runs. Anthropic's Skills documentation describes this split between instructions, executable code, and resources as the mechanism behind progressive disclosure.^{[9]Reference 9Agent Skillshttps://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview}

Test routing, procedure, and trust separately

A well-formed directory can still produce poor behavior. Evaluate at least three layers: whether the Skill activates for relevant requests, whether it stays inactive for unrelated requests, and whether following it produces a valid artifact. Keep these cases beside the Skill so a description edit can't silently change routing.

Treat installed Skills as code. Review and version their instructions, scripts, dependencies, network access, and expected outputs. A Skill can recommend a write or run a bundled script, but trusted application code still owns identity, authorization, sandboxing, and confirmation. A Skill-bundled script inherits the same PreToolUse hooks, sandbox, rate limits, and confirmation stack as any ordinary tool: progressive disclosure loads instructions into context but can't bypass the tool runtime. Progressive loading reduces context use; it doesn't create a security boundary.

Why is an Agent Skill a context-engineering primitive rather than a larger system prompt?

Answer

A Skill exposes small discovery metadata first, loads its reusable workflow only when the request matches, and reads or runs deeper resources only when needed. A larger system prompt pays the full token and distraction cost on every call. The Skill still needs routing, behavior, and security evaluation.

Make long-running work resumable

Compaction can preserve a conversation, but a task that lasts hours or days needs durable execution state outside that conversation. When a fresh context starts, it should reconstruct scope, completed work, current evidence, and the next safe action from files or records. Guessing from a summary invites duplicate work and premature completion.

Anthropic's long-running-agent experiments used an initializer, a feature list, a progress file, repository history, and repeatable startup checks so later sessions could make incremental progress from a known state.^{[10]Reference 10Effective harnesses for long-running agentshttps://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents} A later harness design added planner, generator, and evaluator roles plus a written sprint contract that defined acceptance evidence before implementation began.^{[11]Reference 11Harness design for long-running application developmenthttps://www.anthropic.com/engineering/harness-design-long-running-apps} These are reported designs, not universal requirements, but the durable-state principles transfer to research, incident response, and data work.

A resumable harness needs five artifacts:

The task manifest is machine-readable scope, while the progress log is a human-readable explanation. Neither should silently overwrite the other. A task marked complete needs a receipt, and a receipt needs a stable path or identifier that a fresh session can verify.

Mini-lab: resume from verified receipts

The script below simulates a new context choosing the next ready task. It refuses to treat a done item as complete unless the checkpoint names its evidence. Dependencies prevent the final report from starting before source verification finishes.

At session start, read manifest and checkpoint, inspect version history, run bootstrap smoke check, then select one ready task. At session end, run its acceptance check, write receipt, update status, and leave workspace recoverable. Cancellation should stop new work without deleting receipts; resume should verify them before continuing.

Separate generation from evaluation

For quality-critical work, define a small contract before generation. Producer proposes artifact and expected checks; evaluator reviews contract, then independently tests resulting artifact. The 2026 Anthropic harness used a comparable generator-evaluator agreement before each sprint.^{[11]Reference 11Harness design for long-running application developmenthttps://www.anthropic.com/engineering/harness-design-long-running-apps}

The evaluator shouldn't rely on the producer's claim that checks passed. It should open artifact, run named validation, and write its own receipt. This split controls premature completion and keeps acceptance criteria stable across context resets.

An Agent Skill can teach each session the procedure for incident triage. The harness owns which incident task is active, what already passed, and how to resume safely. Keeping those responsibilities separate lets instructions evolve without corrupting live progress.

What must survive a context reset for a long-running task to resume safely?

Answer

Stable scope and task IDs, dependency and status data, receipts for completed work, current failures, a repeatable bootstrap check, and retry or cancellation rules must survive outside model context. A narrative summary can explain progress, but it can't replace machine-checkable state and evidence.

Rebuild the failed-canary working set

With the taxonomy in hand, the running example fixes itself. Instead of letting the window grow monotonically, the agent runs a curation step before each model call:

1. Select only the tools relevant to the current phase (an investigation needs deploy lookup and traces, not cluster administration), then evaluate whether tool-call accuracy improves.
2. Write durable findings to a scratchpad ("auth callback errors confirmed; migration lock ruled out") and drop the raw tool results.
3. Compress by pruning trace exports older than a few turns and compacting the transcript once it grows large.
4. Isolate the noisy "check every linked issue" exploration into a sub-agent that returns a one-paragraph summary.
5. Detect poisoning: when the early migration-lock guess is identified as wrong, remove it from history so it stops being cited.

The window now holds the alert, current evidence, a short notes block, and a clean tool set. In the concrete script below, it shrinks an illustrative 12.4K-token raw set to a 3.2K-token active window plus short external notes. Lower input cost is immediate; better task performance still requires evaluation.

The logic is simple enough to simulate with a tiny script. This version turns the failed-canary agent's messy transcript into a compact working set by keeping the current alert and evidence, writing durable findings to notes, and dropping poisoned or irrelevant tokens.

Suppose a production incident trace reaches 120K tokens of mostly stale logs and one referenced hallucination, while the selected model advertises a much larger window. Why is "we have headroom, leave it" the wrong call?

Answer

Headroom is a capacity fact, not a quality result. Stale logs and a referenced hallucination create plausible distraction and poisoning failures. Compare a pruned or compacted candidate against the raw trace rather than relying on spare capacity.

Context thrashing: management work exceeds useful work

An agent can also over-manage a bounded window. Context thrashing is the operating pattern where it spends more tokens and tool calls retrieving, summarizing, evicting, and reloading context than advancing the task. One turn fetches a trace, the next compacts it, the next retrieves the same trace because the summary omitted a field, and the loop repeats without a new verified finding.

Don't diagnose thrashing from one large retrieval. Look for repeated churn with little progress:

Use a stable working-set contract instead of a bigger window. Pin the task, current evidence, and next acceptance check for the phase. Cap retrieval and compaction cycles, require each cycle to add a named fact or resolve a decision, and isolate broad exploration behind a bounded handoff. If required evidence still doesn't fit, split the task or persist a structured checkpoint instead of paging the same material repeatedly.

How does context thrashing differ from ordinary context bloat?

Answer

Bloat means too much low-signal material remains active. Thrashing means the agent repeatedly spends retrieval and compaction work moving context in and out without producing new evidence or completing task steps. Bound the working set and require measurable progress per context operation.

Larger windows don't remove curation

Large-window model offerings make it tempting to treat curation as obsolete.^{[12]Reference 121M context is now generally available for Opus 4.6 and Sonnet 4.6https://claude.com/blog/1m-context-ga} Bigger windows raise the capacity ceiling; they don't establish quality for an overloaded agent trace. Frameworks such as LangGraph expose short- and long-term memory plus summarization or deletion patterns because state management remains an application responsibility.^{[13]Reference 13LangGraph Memory Overviewhttps://docs.langchain.com/oss/python/concepts/memory}

When an agent underperforms, inspect the transmitted context alongside model and window choices. Name a suspected failure mode, apply a bounded candidate change, and measure whether it improves the task.

When context curation breaks down

Use this checklist before shipping an agent that handles long sessions:

• Does the context shrink or stay bounded across turns, or does it only grow? Unbounded growth invites distraction and rot.
• Are tool results pruned or compacted once they are no longer needed for the next step?
• Does a phase-gated active tool set outperform loading every available tool on your evaluation cases?
• When a sub-agent is used, does it return a distilled summary rather than its full transcript?
• Do repeated retrieval or compaction calls produce a new accepted fact, receipt, or completed task step?
• Do you have an eval that catches poisoning: a wrong fact persisting and being re-cited across turns?

An agent that worked in short demos degrades in long production sessions. What is the systematic first step before changing models?

Answer

Inspect the actual context being sent. Name a suspected failure mode (poisoning, distraction, confusion, or clash), then test a matching move: prune or compact for distraction and poisoning, gate tools for confusion, reconcile or isolate for clash. Compare the candidate on quality and cost before escalating architecture.

Diagnostic playbook

When a long-running agent underperforms, use this sequence:

1. Inspect the actual context, not the window size or cost alone.
2. Name the failure mode: poisoning, distraction, confusion, or clash.
3. Choose the matching move: write, select, compress, or isolate.
4. Rebuild the next call around the smallest high-signal working set.
5. Compare baseline and curated calls on accuracy, latency, token cost, and failure recurrence.
6. Only after that ask whether you still need a different model, window, or architecture.

Context engineering gives an agent a bounded, inspectable working set even as tools and history accumulate. The next chapter studies prompt injection, where untrusted content tries to turn retrieved evidence or tool output into instructions. Curation and source labels provide the context boundary that those defenses need.

State the one-sentence guiding principle of context engineering and explain why it subsumes the four-move taxonomy.

Answer

Find the smallest set of high-signal tokens that maximizes the chance of the desired outcome. Write, select, compress, and isolate are simply the four mechanisms for pushing toward that minimal high-signal set, each removing or avoiding low-value tokens in a different way.