Claude XML anti-patterns: what not to do

Mistakes that look fine but quietly degrade reliability. Each entry: the trap, why it bites, and the fix.

1. Over-tagging trivial prompts

The trap: Wrapping a one-line question in <question>, <context>, <instructions> when none of them carry weight. Adds tokens, no quality gain.

The fix: Tag when the structure is load-bearing. A simple zero-shot question doesn't need scaffolding.

2. Putting the user question inside <instructions>

The trap: Claude will follow the question as a directive rather than answer it.

The fix: Keep <instructions> for what the model should do; put the question in its own tag or unwrapped after the structured blocks.

3. Mismatched tags

The trap: Opening <document> and closing with </Document> or forgetting the close.

The fix: XML is case-sensitive; Claude usually recovers but reliability drops. Lint your prompts.

4. Putting documents after the question on long contexts

The trap: Anthropic's guidance is the opposite: long reference material first, then instructions, then question.

The fix: Order: <documents> → <instructions> → <question>. Helps attention land on the instruction block.

5. Asking for JSON without saying "only JSON"

The trap: Claude often wraps JSON in ```json markdown fences by default.

The fix: Add "Return only the JSON object, no prose, no markdown fences" — or wrap the output in <result> and parse from there.

6. Reading <thinking> output as ground truth

The trap: Chain-of-thought scratchpads are reasoning aids, not verified logs. They can rationalize wrong answers.

The fix: Use CoT to improve accuracy; don't show the scratchpad to end users as if it were proof.

7. Stuffing the system prompt and an inline <role> with different personas

The trap: The two will fight; Claude becomes inconsistent.

The fix: One source of persona truth. Prefer the API system parameter.

8. Few-shot examples that don't span the real distribution

The trap: If all your examples are happy-path, edge cases collapse to the happy-path label.

The fix: Include hard cases, edge cases, and at least one example of each output class.

9. Forgetting <source> in RAG prompts

The trap: Then asking for citations. Claude invents source names.

The fix: Always pair <document> with <source> when you want attribution.

10. Treating XML tags as a security boundary

The trap: Users can inject </instructions> into their input and break out of your scaffolding.

The fix: Sanitize user input — escape angle brackets or strip XML-like sequences before splicing into the prompt.

11. Nesting tags that don't logically nest

The trap: Putting <example> inside <instructions>, or <document> inside <context>.

The fix: Keep major sections as siblings. Nest only when the semantics are containment (<source> inside <document>, <example> inside <examples>).

---

When to skip XML entirely

XML is load-bearing when there's structural ambiguity in a single prompt the model has to resolve. No ambiguity → no scaffolding needed. Skip XML when:

• Conversational chat. Multi-turn dialogue already establishes who is talking. Wrapping a question in <question> doesn't help — the model knows.
• Single-shot creative writing. "Write a haiku about Tuesday." No structure to scaffold.
• One-line lookups. "What's the capital of France?" The tax is small but real.

And skip specific tags when the API now does the job better:

• Structured output: prefer the API's tool-use / JSON-mode over <format> + "return only JSON". XML coercion is the second-best option in 2026.
• Persona: the API system parameter is stronger than inline <role>.
• Reasoning: on Claude 3.7 and newer with extended thinking enabled, the <thinking> tag is redundant and can fight the internal mechanism. Use one, not both.

See also: when XML genuinely helps — the inverse list.