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:
| Failure | Symptom | Cause |
|---|---|---|
| Bloat | Cost and latency climb turn over turn; quality flat or falling | History and tool output accumulate unpruned |
| Drift | The model forgets a constraint stated 40 turns ago, or contradicts itself | Early instructions lose against a wall of later content; a summary dropped the fact |
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.
| Practice | Detail |
|---|---|
| Return fields, not payloads | Three fields the model needs, not a 200-field API response |
| Prune at the boundary | Shape the result in your handler, before it is appended — a post-tool hook can do this deterministically |
| Normalise formats | One timestamp format, one status vocabulary, so the model is not converting on every read |
| Cap size | Truncate with an explicit marker plus a handle for the rest, so the model knows something was omitted |
| Externalise big artifacts | Write to a file or store; pass the path or ID |
| Summarise verbose output structurally | Extract facts as fields; do not paste a log |
Compaction, clearing, and check-pointing
| Mechanism | Effect | Cost |
|---|---|---|
| Clear (context editing) | Removes old tool results or thinking blocks outright — beta context-management-2025-06-27, clear_tool_uses_20250919 / clear_thinking_20251015 | Whatever was cleared is gone; keep the facts elsewhere first |
| Compact | Summarises earlier context server-side — beta compact-2026-01-12, compact_20260112 | Detail is lost to a summary; append response.content verbatim or the compaction state is lost |
| Manual summary | You write the summary and start a fresh context | Full control, and you decide what survives |
| Cache check-point | A cache_control breakpoint at a stable point in history | Cheaper 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
| Technique | What it isolates | Use |
|---|---|---|
| Subagent delegation | The whole exploration; only the conclusion returns | Verbose codebase reading, research fan-out, anything whose intermediate output is noise |
| Multi-step workflow | Each step gets only its own inputs | A pipeline where step 3 does not need step 1's raw material |
| Fresh session per task | Unrelated tasks stop interfering | A new task after a long unrelated one |
| Scoped tool sets | Irrelevant tool definitions leave the window | Many tools available, few relevant per role |
| Forked skill context | A skill's verbose output stays out of the main conversation | Analysis 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
| Position | Put there |
|---|---|
| Top of the prefix | Frozen system rules, tool definitions — cacheable and highest-authority |
| Middle of the prefix | Large stable corpora, few-shot examples — behind the cache breakpoint |
| Just before the question | The specific document or record under discussion |
| Last | The 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
- 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?
- 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?