Chapter 10: Context Engineering, Output Handling, and Debugging

1. Context Engineering

Context engineering is the discipline of curating the optimal set of tokens the model sees at inference time — "the smallest possible set of high-signal tokens that maximize the likelihood of some desired outcome." Context is not just the current user message; it is the whole state the model sees. Think of the window as a workbench, not a warehouse: keep it clear of clutter so the tools that matter stay within reach.

Two failure modes threaten a long-running context. Context bloat is the accumulation of low-value tokens; context drift is the subtler wandering of focus from the original task. The root cause of degradation is context rot: as tokens grow, recall drops — and it drops before the hard limit is reached. The transformer's n² pairwise relationships stretch the model's "attention budget," so "more tokens makes agents worse." The defense is progressive disclosure with just-in-time retrieval: keep lightweight identifiers (paths, IDs, URLs) and load content only when needed.

Anthropic's cookbook documents three complementary levers, applied diagnosis-first. Compaction (compact_20260112) summarizes a conversation nearing the limit and reinitializes the window; it costs inference but preserves decisions, key facts, and task state. You must append the full response.content (including the compaction block) each turn or the state is silently lost. Tool-result clearing (clear_tool_uses_20250919) mechanically replaces old tool_result bodies with a placeholder at no inference cost (a ~67% reduction in Anthropic's example) but invalidates the prompt cache on each firing. The memory tool (memory_20250818) stores notes in external files outside the window — the only lever that persists across sessions.

Figure 10.1: Diagnosis-first decision flow for choosing a context-management lever

2. Context Isolation

Context isolation gives separate parts of a workload separate context windows. The canonical mechanism is a multi-agent architecture: a lead (orchestrator) delegates sub-tasks to subagents, each with its own isolated window. The design property that makes it work is the return contract — a subagent reads many files or runs many tool calls in its own window but returns only a condensed summary, typically 1,000–2,000 tokens. The orchestrator accumulates distilled results, not raw exploration. Many isolated agents outperform one monolithic agent for three reasons: higher signal density, no single window holding everything (countering rot), and parallelism. One caution: subagents inherit every parent MCP tool definition, so disable unused MCP servers before spawning them.

Figure 10.2: Subagent context isolation — deep work in isolated windows, thin summaries returned

Isolation matters for security too. Trusted context is content you control — your system prompt, tool definitions, operator instructions. Untrusted context is anything from outside your control — a fetched page, an uploaded document, a third-party tool result — which may carry prompt-injection attempts. Deliver mid-conversation operator instructions as a {"role": "system", ...} message: that is a non-spoofable operator channel that injected text cannot forge. The practical rule: treat every tool result, fetched page, and uploaded document as data to reason about, never as instructions to obey — and route untrusted processing into a narrow-tool subagent to limit blast radius.

3. Output Handling

Structured output constrains Claude's responses to a JSON schema through two features: JSON outputs (output_config.format) control what Claude says, and strict tool use (strict: true) validates how Claude calls your functions. Both rely on grammar-constrained sampling — the schema is compiled into a grammar that actively prevents emitting a schema-breaking token, unlike merely prompting "please return valid JSON." Every object must set "additionalProperties": false and list every property in required. Not supported: recursion, numeric constraints (minimum/maximum), string-length constraints, and complex regex. Note that strict: true is a sibling of name/description/input_schema on the tool — not on tool_choice.

Grammar-constrained sampling removes most parse failures — not all. Defensive parsing never assumes the schema held. Three cases matter: refusals (stop_reason: "refusal", content may be empty/partial), truncation (stop_reason: "max_tokens", output incomplete), and enum casing differences. The rule: always branch on stop_reason before touching content, and catch typed exceptions (e.g., anthropic.RateLimitError) rather than string-matching messages.

Figure 10.3: Defensive parsing — branch on stop_reason before touching content

Structured, well-formed output can still be wrong. A schema guarantees the shape of an answer, never its truth — a beautifully typeset invoice is not proof the amounts are correct. Five techniques reduce and audit hallucination: (1) allow uncertainty (permit "I don't know," which alone drastically reduces fabrication); (2) ground in direct quotes for long documents; (3) verify with citations (the Citations API ties responses to source chunks); (4) chain-of-thought verification; and (5) best-of-N verification. Cross-check load-bearing numbers, dates, and citations against trusted sources.

4. Debugging and Error Handling

When a request fails, first identify what kind of failure it is. The API returns a JSON error object with a type and message, plus a request_id, mapped onto HTTP status codes. Recovery follows the "retryable?" column: non-retryable 4xx errors are yours to fix; retryable errors (429, 5xx, 529) call for exponential backoff, which the official SDKs do automatically (twice by default, honoring retry-after).

Figure 10.4: Error recovery decision tree driven by the retryable column

Trace analysis reconstructs what happened from a request's artifacts. The most important is the request-id header (e.g., req_018EeWyXxfu5pfWkrYcMdjWG), mirrored as request_id in error bodies and exposed in Python/TypeScript as _request_id. Log it on every failure and include it in support tickets. Catch typed exceptions most-specific-first (e.g., NotFoundError before APIStatusError). Context-state diagnostics like /context tell you why a window is bloated so you can pick a remedy (/compact, /clear, /mcp disable).

The most important judgment is where a problem lives. The 429 vs. 529 distinction is the sharpest expression: a 429 is your responsibility (tier limit or a usage spike — honor retry-after, ramp traffic gradually); a 529 is not your fault (Anthropic-wide capacity, usually resolving in ~30–300 seconds — retry with jitter, a ~60s circuit breaker, and model fallback). A third origin — quality degradation with no error — is almost always conversation state; Claude Code does not silently change models.

Figure 10.5: Isolating the origin of a failure — integration-layer vs. provider-side vs. model-output

One recovery technique deserves emphasis: when a response goes wrong, rewinding (Esc twice or /rewind) beats correcting in-thread, because correcting keeps the wrong attempt in context and anchors later answers to it. Claude Code retries transient failures up to 10 times with exponential backoff, but deliberately does not retry TLS certificate-validation failures or server errors that arrive after visible output has streamed (a retry could double-execute tools).