D4 · Prompt Engineering › Cluster 7 · Structured Outputs & JSON

7.1 · Increasing Output Consistency

Make the shape repeatable

CONCEPT Consistency is engineered, not hoped for

Before reaching for any feature, you can make Claude's output far more predictable with plain prompting. Anthropic's guidance lists four levers, roughly in order of strength:

LeverWhat it doesExample
Specify the exact formatDescribe every field, its type, and the wrapper (JSON, XML, or a template) so nothing is left to interpretation"Output JSON with keys sentiment, key_issues (list), action_items (list of {team, task})"
Show an example of the shapeA concrete filled-in example teaches the structure better than any abstract descriptionInclude one worked <competitor>…</competitor> block, then "Now do X"
Use XML tagsNamed tags give Claude an unambiguous skeleton to fill and give you an easy parse target<report><summary>…</summary></report>
Constrain the valuesEnumerate allowed values so free-text drift can't happen"sentiment is one of: positive / negative / neutral"
🔑 Two supporting techniques round this out: retrieval grounding (answer from a fixed knowledge set so responses don't wander), and prompt chaining (break a complex task into smaller subtasks, each of which Claude handles more consistently).

CONCEPT Prefill is powerful — but model-gated now

Historically the strongest lever was prefilling the assistant turn: you start the assistant message with the opening of your desired structure ({ or <report>) and Claude continues from there, skipping any friendly preamble.

⚠️ Assistant prefill is not supported on current Claude models — Fable 5, Opus 4.8 / 4.7 / 4.6, and Sonnet 4.6 reject a trailing assistant turn with a 400. On those models the format-locking job moves to structured outputs (7.4), tool use (7.3), or a plain system-prompt instruction. Prefill (7.2) remains only for older models that still allow it.
Anthropic's own tip: "For guaranteed JSON schema conformance, use Structured Outputs instead of the prompt-engineering techniques." Reach for prompting when you want flexibility beyond a strict schema; reach for the feature when the shape must never drift.

DIAGRAM The consistency escalation ladder

flowchart TD A["Need a repeatable output shape"] --> Q{"How strict must it be?"} Q -->|"loose / flexible"| P["🟢 Prompt techniques
specify format · give an example
XML tags · enums · retrieval"] Q -->|"must parse as JSON
every time"| F{"Feature available on this model?"} F -->|"yes"| SO["🟢 Structured Outputs (7.4)
or Tool Use (7.3)
guaranteed conformance"] F -->|"no / older model"| PF["🟠 Prefill + stop (7.2)
or JSON-only + parse"] classDef ok fill:#d4edda,stroke:#28a745,color:#155724; classDef gate fill:#ffe8cc,stroke:#ff9f40,color:#9a4a0a; class P ok; class SO ok; class PF gate;

CODE Vague prompt → specified prompt

The same request, made repeatable by naming the format, showing the shape, and constraining the values.

# ❌ BAD — vague; every response is shaped differently
system = "Analyze this customer feedback."

# ✅ GOOD — exact format + example shape + enum + XML skeleton
system = """You are a Customer Insights AI. Analyze the feedback inside
<feedback> tags and reply with ONLY this XML — no preamble:

<analysis>
  <sentiment>positive | negative | neutral</sentiment>
  <key_issues>
    <issue>one short phrase</issue>
  </key_issues>
  <action_items>
    <item team="Product | UX | Marketing">task</item>
  </action_items>
</analysis>"""

resp = client.messages.create(
    model="claude-opus-4-8", max_tokens=1024,
    system=system,
    messages=[{"role": "user",
               "content": "<feedback>The new UI is a scavenger hunt.</feedback>"}],
)
The <sentiment> enum, the single worked <item>, and the "reply with ONLY this XML" instruction together do most of the work — no feature required.

TRADE-OFFS Prompt techniques vs. the feature

✅ Prompt-only techniques

  • Work on every model, no beta, no schema compiler
  • Flexible — mix prose + structure, partial structure, free-form fields
  • Zero added latency on the first call

⚠️ Prompt-only limits

  • Best-effort — a stray token can still break the shape
  • You must validate and retry yourself
  • For hard JSON guarantees, escalate to 7.3 / 7.4

EXAM TRAPS

Trap: "Just tell Claude 'return JSON' and it will always be valid." → Plain instructions are best-effort, not guaranteed. For a hard guarantee use structured outputs or strict tool use.
Trap: "Prefill the assistant turn to lock the format." → Prefill is rejected with a 400 on Fable 5 and the 4.6/4.7/4.8 family. It only works on older models — use the feature instead.
Trap: Abstract instructions over concrete examples. → Anthropic explicitly notes an example of the filled-in shape teaches structure better than describing it in words.
Trap: Forgetting to constrain the values. → Naming an enum ("one of: A / B / C") eliminates a whole class of free-text drift that format alone doesn't.

PRACTICE

Q1 · Name three prompt-only levers that increase output consistency.

Any three of: specify the exact format (JSON/XML/template with every field named), give an example of the shape, use XML tags as a skeleton, constrain values with enums, ground with retrieval, and chain prompts into smaller subtasks.

Q2 · Why is prefilling no longer the default answer for locking JSON?

Assistant-turn prefill returns a 400 error on current models (Fable 5, Opus 4.8/4.7/4.6, Sonnet 4.6). The format-locking job has moved to structured outputs (7.4) or tool use (7.3), with system-prompt instructions as the plain-text fallback.

Q3 · When should you escalate from prompting to the Structured Outputs feature?

When the output must parse as valid JSON conforming to a fixed schema every time. Prompting is best-effort; the feature uses constrained decoding to guarantee conformance. Keep prompting when you want flexibility beyond a strict schema.