Patterns & Anti-Patterns Field Guide
A cross-cutting reference collecting every pattern this course has argued for — and the anti-pattern each one guards against. Bookmark this page rather than reading it once, and open it again right before you ship anything new.
Think of this page like a field guide to mushrooms. Two kinds can look almost the same from a few feet away — one is dinner, the other sends you to the hospital — and the only way to tell them apart is knowing the one detail to check, like the color of the spores. Every row in this guide is the same kind of look-alike pair: a solid pattern and its anti-pattern often look like reasonable engineering choices from a distance, and the detail that separates "works in production" from "breaks under real load" is exactly what each row spells out.
One page, all the patterns
☺ Like you're 10: think of it like the checklist a chef pins to the kitchen wall — not read once on day one, but glanced at before every dish goes out.
Every earlier module in this course argued for one specific technique in its own narrow context — how to structure a prompt, how to describe a tool, how to retrieve context, how to deploy safely. This page collapses all of them into one table you can scan in under a minute: what the pattern is, when it earns its keep, and — just as important — what actually breaks when you skip it.
None of these are universal rules. Anthropic's own agent-design guidance makes the point directly: success with LLM systems isn't about building the most sophisticated system, it's about building the right one for the job in front of you. Read every row below in that spirit — a tool to reach for when the problem calls for it, not a checklist to apply all at once.
Treat the middle column of the table as your decision criteria and the right column as the failure mode you're trading against. If a row's "when to use it" doesn't match your task, applying the pattern anyway is over-engineering — Anthropic's own prompt-engineering guidance warns explicitly against "stacking every technique at once."
The reference table
Sixteen patterns, one per row. Read the middle column as "does my task actually look like this," and the right column as what quietly goes wrong if you skip it anyway.
| Pattern | When to use it | What goes wrong without it (the anti-pattern) |
|---|---|---|
| Clear, direct instructions | Any prompt where output format, scope, or constraints matter — which is nearly all of them. Apply the golden-rule test: show the prompt to a colleague with no context and see whether they'd know exactly what to produce. | Vague prompts — for example, simply asking for an analytics dashboard — get a technically valid but underspecified answer. Claude fills the gaps with its own guesses, and you spend more time re-prompting than you saved. |
| XML-structured prompts | Prompts that mix instructions, context, examples, and variable input in the same call — long documents, multi-part instructions, or anything templated with {{VARIABLE}} placeholders. | An unstructured wall of text forces Claude to guess where instructions end and content begins, increasing misreads — especially once the prompt is long enough that a document could be mistaken for an instruction. |
| Prompt chaining | Tasks that decompose cleanly into fixed sequential steps where you need to inspect, log, or gate an intermediate output (draft, then review against criteria, then refine). | A single mega-prompt asks Claude to do everything in one pass. There's no checkpoint to catch a bad intermediate step, so errors from step two silently compound into step four with no way to diagnose where it went wrong. |
| Routing | Inputs that fall into distinguishable categories needing different handling — cheap, simple queries to a fast model, complex ones to a more capable model, or different query types to specialized prompts. | A one-size-fits-all prompt (and model) handles every request identically, either overpaying in cost and latency for simple queries or underserving hard ones that needed more capability. |
| Parallelization (sectioning / voting) | Subtasks that are genuinely independent of each other, or where running the same task multiple times and comparing outputs increases confidence — several review passes on the same input, for example. | Independent work still runs one call after another. Latency stacks up for no accuracy benefit, and you never get the diverse-attempts signal that voting would have given you. |
| Orchestrator-workers | Complex, unpredictable tasks where the subtask breakdown can't be fixed in advance — multi-file code changes, multi-source research — so a central LLM needs to decide the decomposition per input. | One agent tries to hold the entire multi-part task in a single context window. It loses track of earlier subtasks as context grows, and there's no synthesis step pulling partial results back together. |
| Evaluator-optimizer loop | Tasks where responses demonstrably improve with iterative feedback and a second LLM pass can give meaningful, specific critique — literary translation refined against nuance feedback, for example. | Ship-on-first-try: the first draft goes straight to production. Subtle quality issues that a critique pass would have caught reach the user instead. |
| Matching agent complexity to task complexity | Well-defined tasks fit a workflow pattern (chaining, routing, parallelization, orchestrator-workers, evaluator-optimizer); reserve open-ended autonomous agents for tasks where the number of steps genuinely can't be predicted up front. | Reaching for a fully autonomous tool-loop agent by default, even for predictable tasks — inheriting the higher cost and the compounding-error risk that a fixed workflow would never have exposed you to. |
| Tool descriptions written like documentation | Every tool you hand to Claude — the description is, per Anthropic's own guidance, the single most important factor in how well a tool gets used, so write 3–4+ sentences covering what it does, when to use it, what each parameter means, and any caveats. | A one-line vague description leaves Claude guessing when to call the tool and how to fill its parameters, producing misfires, malformed input, and retry loops that a better description would have prevented outright. |
| Schema-backed structured extraction | Anywhere you need guaranteed-valid JSON or a specific shape — use output_config.format with a JSON Schema, or a strict: true extraction tool with tool_choice forcing it. | Just asking for JSON in the prompt gives no guarantee. Claude can return incompatible types (a string "2" instead of a number) or omit required fields, and your parser breaks in production. |
| Targeted RAG retrieval | Knowledge bases larger than fits comfortably in context — retrieve only the top-k relevant chunks (optionally with contextual retrieval and reranking) for each query. | Dumping the whole knowledge base into every call burns tokens and money, dilutes the signal with irrelevant chunks, and stops scaling the moment the corpus grows past a handful of documents. |
| Prompt caching for static content | System prompts, large reference documents, tool definitions, or few-shot examples that stay identical across many calls. | Repeatedly repaying full input price for the same tokens on every call — and losing the extra throughput headroom caching gives you, since only uncached tokens count toward per-minute token limits. |
| Human confirmation before irreversible tool actions | Any tool call with real-world consequences — sending a message, deleting data, spending money, merging code — especially in regulated or high-risk domains. | Unscoped autonomous tool access lets a single hallucinated or misled step execute an irreversible action unattended, with no human positioned to catch it before it happens. |
| Eval-gated prompt changes | Before shipping any prompt or model change to production — build a test set with SMART success criteria and automated grading, and require it to pass before rollout. | Shipping on vibes: eyeball a couple of outputs, decide it looks fine, and ship live. Regressions on edge cases go undetected until a real customer hits them. |
| Exponential backoff on 429s | Any production integration against the Messages API — retry rate_limit_error (429) and server-side overloaded_error/api_error (5xx) responses with exponential backoff, honoring the retry-after header. | No retry logic means a single transient rate limit or momentary server hiccup crashes the whole job, instead of resolving itself after a few seconds' delay. |
| Treating fetched content as data, not instructions | Anywhere Claude reads content it didn't author — web pages, tool results, documents, emails — via tool_result blocks, with an explicit system-prompt statement that this content is untrusted. | Blindly trusting tool output lets an adversarial third-party page or document inject instructions that Claude follows as if you'd written them — indirect prompt injection, one of the two threat models Anthropic's guardrail docs call out explicitly. |
Three patterns worth a closer look
☺ Like you're 10: these are the three mistakes that show up again and again in real systems — trusting an agent with more freedom than the task needs, stuffing the whole library into every question, and skipping the "are you sure?" step before something can't be undone.
Every row in the table above matters, but three of them are where most real deployments actually go wrong: over-provisioning agent autonomy, under-engineering retrieval, and skipping the human checkpoint on irreversible actions. Each deserves more than one table row.
Foxy: This new task feels unpredictable — let's just wire up a fully autonomous agent to handle the whole thing!
Timmy: Hold on — is every step actually unpredictable, or is it just a little annoying to plan out by hand?
Foxy: I mean... it's basically draft, check it, then fix it. Same three steps, every time.
Professor Owl: Then that's a chaining problem, not an agent problem. Save full autonomy — and the cost and compounding-error risk that comes with it — for when the steps genuinely can't be predicted in advance.
Matching agent complexity to the task
Start with the augmented LLM and the simplest workflow pattern that fits — chaining, routing, parallelization, orchestrator-workers, or evaluator-optimizer — and only reach for an open-ended autonomous agent when the task is genuinely unpredictable and the number of steps can't be hardcoded. When you do go autonomous, give the agent ground-truth signals from the environment at each step (tool results, test runs) and confine it to a sandboxed or trusted environment with guardrails.
Defaulting to a fully autonomous tool-loop agent for tasks with a fixed, predictable structure. You pay the latency and cost tax of an agentic system without needing the flexibility, and you inherit its core risk for free — agents run this way cost more to operate and carry a real chance of errors compounding silently across steps.
Targeted RAG retrieval over context-stuffing
Chunk the knowledge base, embed it, and retrieve only the top-k relevant chunks per query — ideally with contextual retrieval (a Claude-generated context blurb prepended before embedding and BM25 indexing) plus a reranking step on top. Measure retrieval quality (precision, recall, F1, MRR) separately from end-to-end answer quality so you know which stage to fix when something's wrong.
Pasting the entire knowledge base into every prompt. It's the simplest thing to build and the fastest to stop scaling — cost balloons, irrelevant chunks dilute the model's attention, and a wrong answer gives you no way to tell whether retrieval or generation was at fault.
Human confirmation before irreversible actions
Gate anything destructive, financial, or irreversible — sending a message, deleting data, merging code, spending money — behind an explicit human approval step. This is exactly what Claude Code's permission modes are for (the default mode reads freely but prompts for everything else), what MCP's tool-approval dialogs enforce even though tools are model-invoked, and what usage-policy human-in-the-loop requirements mandate for high-risk domains like legal, healthcare, and finance.
Granting broad or bypass-level tool access so the agent can act unattended. A single confused step becomes unrecoverable — which is exactly why the most permissive modes, the ones that skip virtually every check, are meant only for isolated, disposable sandboxes, never for anything touching real accounts or data.
You should now be able to scan any of the sixteen patterns above and explain both when it applies and what silently breaks if you skip it — and you've seen the three highest-leverage checks in more depth: agent autonomy matched to task complexity, targeted retrieval instead of context-stuffing, and a human checkpoint before anything irreversible. This is a reference page, not a lesson — come back to it before you ship any new capability. For where to go from here, see Next Steps.
Check your answers
- When should you reach for an open-ended autonomous agent instead of a fixed workflow pattern? Only when the task is genuinely unpredictable and the number of steps can't be hardcoded in advance — start with the simplest workflow pattern that fits (chaining, routing, parallelization, orchestrator-workers, evaluator-optimizer) and reserve full autonomy for cases where a fixed structure would break.
- Why does dumping an entire knowledge base into every prompt eventually stop working, even though it's the easiest thing to build first? It burns tokens and money, dilutes the model's attention with irrelevant chunks, and gives you no way to tell whether a wrong answer came from bad retrieval or bad generation — targeted top-k retrieval, ideally with contextual retrieval and reranking, scales instead.
- What's the common thread across human confirmation before irreversible actions, eval-gated prompt changes, and exponential backoff on 429s? Each is a missing constraint that only shows up as a failure under real load — no approval gate, no test set, or no retry logic all look fine in a demo, until an irreversible action, a regression, or a transient rate limit actually happens.