Phase 2: Context Engineering for Builders · 45 min · Claude Code · Python

Context Failure Modes

The fix depends entirely on which failure mode you're hitting — and 'the agent seems confused' names a symptom, not a diagnosis.

Hiring signal: Diagnosing which specific context failure mode is occurring — rather than reaching for a generic 'add more context' or 'try a bigger model' fix — is precisely the debugging judgment this course's struggle principle is built to develop.

What you will learn

Define and distinguish the four context failure modes: poisoning, distraction, confusion, clash
Diagnose which failure mode a given symptom most likely reflects before choosing a fix
Detect a poisoned claim being carried forward through a context log
Detect a clash between two contradictory pieces of context on the same subject

Introduction

Context Failure Modes

An agent working a customer refund case confidently states the refund cap is 150% of the original order — a number that appears nowhere in the actual policy. Later in the same session, when asked to reconcile two different documents that both claim to define the current refund policy, it picks one arbitrarily and doesn't flag that they disagree. A different session, working a completely unrelated bug, starts producing generic, unfocused suggestions once the transcript grows past a certain length, even though nothing in that transcript is factually wrong. A third session gets thrown off by an old code example left in context from an earlier, unrelated task, and starts applying that example's pattern where it doesn't belong.

These are four different problems. Each one looks, from the outside, like "the agent is behaving strangely," and each one requires a different fix. Calling all four "the agent got confused" and reaching for the same generic response — usually "just give it more context" — makes some of them worse. Drew Breunig's framework names them precisely, and naming them precisely is the entire value: you can't fix what you can't diagnose.

Poisoning: a hallucination becomes a fact

Poisoning happens when a false claim enters the context — usually a hallucination the model itself generated earlier — and then gets treated as established truth in subsequent turns, sometimes by the same agent reasoning from its own earlier error. The 150% refund cap wasn't in any real document; the agent generated it once, and once it's sitting in the context as a stated fact, nothing distinguishes it from a genuinely verified one. Every subsequent turn that references it inherits the error, and the error compounds instead of dissipating. The fix is structural: track provenance (is this claim grounded in a verified source, or did the model state it?) and be suspicious of claims that originated from generation rather than retrieval.

Unlock the full lesson

You've read the first 2 sections. The rest of this lesson covers Distraction: overwhelmed, not wrong, Confusion: irrelevant but influential, Clash: two truths that disagree, Diagnose before you fix, Build It — plus a hands-on lab, quiz, and project artifact.

Create a free account to unlock Phase 0 and Phase 1 of every course — no credit card.