The Agent Is Built To Fail Well
Every break in a coding agent gets a named repair. A blip gets a retry, a long answer gets more room, an overflowing prompt gets trimmed. When every repair fails, the turn stops and says why. Trust lives in that clean stop.
You judge an agent by its worst answer, at the worst time, for the person who needs it most. Everything below is built for that answer.
Failure model
Things break. A service gets busy, a step stutters. Most of that is weather. So the first move is another try.
An agent that tries forever is broken in its own way. So it bounces a few times, like a ball on a trampoline, each try lower than the last. When it still does not land, it stops on purpose and tells you plainly.
A spin that never ends leaves you nothing to work with. A stop with a named reason is a good ending.
Four things break a turn in Claude Code. Networks hiccup, answers run past the size limit, prompts overflow mid turn, streams cut out after a tool call. Each break gets a rung under it that catches the fall.
Below, one turn hits trouble and falls down the net. Step through all three cases.
01The model is the 20 percent
A demo makes an agent look like a model problem. Past the demo it is a plumbing problem, and the model is a fifth of the work. The other four fifths keep the turn alive when the network and the tools act up. The model is the part you swap. The machinery around it is the part you own. Nobody puts that in a launch video, and it separates a thing that demos from a thing you trust.
02Most failures are transient, so the first move is to try again
A plain retry is the first rung of the net. The hard part is telling weather from a wall. Weather passes if you wait. A wall does not move, and hitting it again costs a call for nothing. So every retry step carries a limit: a few tries, then the ladder moves to a smarter rung.
03Some failures have a specific, smarter fix
Below the plain retry, each of the next three rungs handles one break.
- The answer hit its size limit, and a plain retry hits the same ceiling. So the agent raises the limit, retries a few times, then gives up rather than burn tokens forever.
- The prompt grew too big to hold partway through. The agent trims it first, then retries. That trimming machinery comes from earlier in the guide, and it works as a repair here.
- The stream cut out after a tool call. That leaves a half-done piece dangling in the conversation. The agent throws the leftover away and puts the conversation back into a shape that runs.
A failure falls down the ladder until a rung matches it. Each rung it passes rules out one repair. The stop at the bottom arrives with the reason already narrowed.
04Knowing when to stop is part of the design
If a trim fails several times in a row, a switch flips and the retries stop. Another try does not fix what is wrong. If a turn goes around too many times, a hard limit ends it. Both limits are numbers chosen in advance, which turns the bottom of the ladder into a decision. Press send below and count the tries before the breaker opens.
The bar
Good means failing small and explained. The worst case is engineered too, and it ends in something a person can act on.
05A clean failure beats a confident wrong answer
The loop ends in a fixed list of ways, and the failures on that list get made here. Each one names what broke.
The prompt was too big, so shorten the task or split it. Every retry hit the same timing-out service, so wait or route around it. A broken stream after a tool call means running that step again on a clean thread. That same dead turn can come back as a confident answer or a blinking cursor. Compare the three endings below.
Pick a real dead end. The same broken turn can be handed back three different ways. Watch what each one leaves in your hands.
The cost
The net is invisible when it works, which makes it thankless to build and easy to skimp on. It adds weight: more paths and more states. A retry that saves the turn also hides the broken part underneath it. So write down why each turn failed, and count the saves. A count that climbs week over week is the test that something under the net needs fixing.
Decision
Write down four answers for your own agent. Cover the passing blip, the answer too big, the broken stream, and the real dead end. Build those paths first.
If any answer reads "it crashes" or "it guesses," you have a demo. The next piece takes the good day: how an agent earns trust on every turn by showing its work.