When a Claude-backed feature produces flaky output, teams tend to blame the model or reach for more rules. In practice, the same few prompt-construction mistakes account for most of the trouble. Here are the ones we see most, roughly ordered by how often they bite, with the fix for each.
1. The unmarked blob
Anti-pattern: instructions, reference material, and the user's input pasted together as one undifferentiated wall of text. The model has to guess where your rules end and the customer's email begins — and when the input itself contains instruction-like sentences, it sometimes follows them.
Fix: wrap each part in its own consistent, descriptive XML tag — <instructions>, <policy>, <customer_email> — and nest tags for hierarchy, as Anthropic's best-practices guide recommends. Clear boundaries also make the prompt auditable by humans.
2. Assuming shared context
Anti-pattern: "Summarize this for the usual report." Claude doesn't know your usual report. Anthropic's golden rule: treat Claude like a brilliant but brand-new employee — if a colleague with minimal context would be confused by the prompt, so will the model. A related variant is expecting "above and beyond" behavior without asking for it.
Fix: state audience, purpose, length, and format explicitly, and explain why constraints matter (e.g., "this is read aloud by a text-to-speech engine, so never use ellipses"). The model generalizes from reasons better than from bare rules.
3. Describing a format instead of showing it
Anti-pattern: five paragraphs specifying the output layout in prose, which the model interprets slightly differently each time.
Fix: show 3–5 relevant, diverse examples wrapped in <example> tags. And when output feeds software, don't describe JSON at all — enforce it with structured outputs (output_config with a JSON schema, additionalProperties: false). A schema is guaranteed; prose is a suggestion.
4. Relying on retired mechanics
Anti-pattern: prompts and code carried over from older integrations — prefilling the assistant's reply to force a format, or tweaking temperature to "stabilize" output. On current models these fail outright: prefilled assistant turns return a 400 error on Claude 4.6-generation and newer models, and Fable 5, Opus 4.8, and Sonnet 5 reject non-default temperature, top_p, and top_k with a 400.
Fix: migrate format-forcing prefills to structured outputs or direct "no preamble" instructions, and delete sampling-knob tweaks from request templates.
5. Instructions in the wrong place
Anti-pattern: a 40-page document pasted after the question, or per-request data baked into the system prompt. For long inputs (20k+ tokens), Anthropic's guidance is to put the documents at the top and the query at the end — end-placed queries can improve response quality by up to 30%. Multiple documents belong in <document> tags with <source> and <document_content> subtags.
Fix: stable role and rules in the system prompt; longform data first in the user message; the question last.
6. The volatile prefix
Anti-pattern: a timestamp, request ID, or user name interpolated at the top of the system prompt. Prompt caching is a strict byte-level prefix match, so one changed byte at position N invalidates every cache breakpoint after it — this single habit can silently zero out your cache hit rate and multiply input costs.
Fix: order prompt content from most stable to most volatile: tools, then system rules, then per-request data at the end. Keep serialization deterministic.
7. Piling on rules instead of measuring
Anti-pattern: every bad output triggers a new ALL-CAPS rule, appended forever, never tested. Contradictions accumulate; nobody knows which rules do anything. And per Anthropic's overview, some failures aren't prompting problems at all — a different model can be the cheaper fix for latency or cost issues.
Fix: hold a fixed eval set and require every prompt change to beat the incumbent on it before shipping — the discipline described in running your own evals and assessing prompt changes.
Where to go next
See XML structure, negative instructions, and short vs. long prompts for deeper dives on individual fixes.