Skip to main content

6.1 Context engineering

Prompt engineering is what you say. Context engineering is what is in the window at the moment you say it — and what is not.

The budget​

Everything competes for the same window: system prompt, tool definitions, conversation history, tool results, documents, and the model's own reasoning. Two failure curves:

FailureSymptomCause
BloatCost and latency climb turn over turn; quality flat or fallingHistory and tool output accumulate unpruned
DriftThe model forgets a constraint stated 40 turns ago, or contradicts itselfEarly instructions lose against a wall of later content; a summary dropped the fact
The window is not the fix

A larger window postpones the wall; it does not restore attention. Facts in the middle of a very long context are the ones that get missed, and contradictory instructions spread across it do not resolve. When output is inconsistent across many inputs, decompose into focused passes with a check between them.

Tool output pruning​

The single highest-leverage technique, because tool results are usually the largest and least curated thing in the window.

PracticeDetail
Return fields, not payloadsThree fields the model needs, not a 200-field API response
Prune at the boundaryShape the result in your handler, before it is appended — a post-tool hook can do this deterministically
Normalise formatsOne timestamp format, one status vocabulary, so the model is not converting on every read
Cap sizeTruncate with an explicit marker plus a handle for the rest, so the model knows something was omitted
Externalise big artifactsWrite to a file or store; pass the path or ID
Summarise verbose output structurallyExtract facts as fields; do not paste a log

Compaction, clearing, and check-pointing​

MechanismEffectCost
Clear (context editing)Removes old tool results or thinking blocks outright — beta context-management-2025-06-27, clear_tool_uses_20250919 / clear_thinking_20251015Whatever was cleared is gone; keep the facts elsewhere first
CompactSummarises earlier context server-side — beta compact-2026-01-12, compact_20260112Detail is lost to a summary; append response.content verbatim or the compaction state is lost
Manual summaryYou write the summary and start a fresh contextFull control, and you decide what survives
Cache check-pointA cache_control breakpoint at a stable point in historyCheaper re-reads, not a smaller window

The rule that survives every mechanism: durable facts live outside the transcript. Before any compaction, extract the case facts — IDs, decisions, constraints, open questions — into a memory store, a scratchpad file, or a structured state object. A summary is prose; state is data.

Context isolation​

TechniqueWhat it isolatesUse
Subagent delegationThe whole exploration; only the conclusion returnsVerbose codebase reading, research fan-out, anything whose intermediate output is noise
Multi-step workflowEach step gets only its own inputsA pipeline where step 3 does not need step 1's raw material
Fresh session per taskUnrelated tasks stop interferingA new task after a long unrelated one
Scoped tool setsIrrelevant tool definitions leave the windowMany tools available, few relevant per role
Forked skill contextA skill's verbose output stays out of the main conversationAnalysis skills in Claude Code

Passing context into an isolated worker is explicit and lossy by default: a subagent inherits nothing. Give it the goal, the quality criteria, the facts it needs, and the metadata (source, URL, date, document name) — without which its output cannot be reconciled with its siblings'.

Placement inside the window​

PositionPut there
Top of the prefixFrozen system rules, tool definitions — cacheable and highest-authority
Middle of the prefixLarge stable corpora, few-shot examples — behind the cache breakpoint
Just before the questionThe specific document or record under discussion
LastThe actual question, plus anything volatile (timestamps, request IDs)

For long documents, state the task after the document rather than before it: the instruction is then adjacent to where the reasoning starts.

Quiz​

  1. Question 1

    An agent’s cost per task has tripled over a long session while quality is flat. Traces show each tool returns a 200-field API payload that is appended verbatim and then re-sent on every subsequent turn. What is the most effective change?

  2. Question 2

    A long support conversation will be compacted. What keeps the case facts — amounts, dates, order IDs, commitments already made to the customer — intact?