Handling ambiguity
Prompt Engineering
One of the most practical prompt engineering skills is getting Claude to produce output in an exact format — JSON you can parse, a markdown table you can paste into a doc, a CSV ready to import, HTML you can drop into a page. Claude can do all of these reliably, but the prompting matters. This chapter covers the patterns that work and the failure modes to watch for.
The Golden Rule: Specify Format Last
As established in Chapter 1, the end of your message carries the most weight. Format instructions belong at the end of your prompt — after the task, after the context, after the constraints. If you put them at the beginning, Claude may drift by the time it gets to generating the output.
Getting Clean JSON
JSON is the most commonly requested structured format — it's the lingua franca of pipelines, scripts, and APIs. The challenge is that Claude defaults to wrapping code in markdown fences and adding explanatory prose, which breaks a JSON.parse() call.
The reliable JSON prompt pattern
Three things make this work:
- The schema is defined upfront — field names, types, and null behaviour are all specified
- "No markdown code fences" — explicitly prevents the
```jsonwrapper Claude adds by default - Format instruction is last — "Return only the JSON object. No explanation." closes the prompt
Ensure all strings use double quotes and the output is valid JSON that passes JSON.parse(). This prevents Claude from using single quotes or trailing commas that some parsers reject.
Defining the schema with an example
For complex or nested JSON, show Claude an example of the structure you want (few-shot from Chapter 4 applies here):
Return results in this exact JSON structure:
{
"commands": [
{
"name": "string",
"syntax": "string",
"description": "string",
"example": "string"
}
]
}
No extra fields. No explanation. No markdown fences.
Markdown Tables
Markdown tables render cleanly in most documentation tools, GitHub, and note-taking apps. They're also easy for Claude to produce consistently.
CSV Output
CSV is slightly trickier because commas in values need quoting, and Claude may add a header row you don't want (or omit one you do). Be explicit:
HTML Fragments
For web projects, asking Claude to produce ready-to-use HTML saves a translation step. The key is specifying whether you want a full document or a fragment, and what CSS classes or structure to use.
Format Recipe Cards
Here are reliable prompt patterns for the most common structured output types:
Add "Ensure all strings use double quotes" if parsing programmatically.
Specify whether the array should be wrapped in a root key or bare.
Name columns exactly as you want them to appear.
Specify delimiter if not comma (e.g. semicolon for European locales).
Add "exactly N items" to enforce a fixed count.
Useful for config-style output or quick reference cards.
Common Failure Modes
| Failure | Why it happens | Fix |
|---|---|---|
| Markdown fences around JSON | Claude's default is to wrap code in ```json blocks for readability |
Explicitly add "no markdown fences" or "raw JSON only" to the prompt |
| Explanation before/after the output | Claude wants to be helpful by contextualising its output | "No explanation. Output only." at the end of the prompt — repetition is fine |
| Trailing commas in JSON | Claude sometimes produces JS-style JSON which some strict parsers reject | "Valid JSON that passes JSON.parse()" — this phrasing triggers standards compliance |
| Wrong number of table columns | Claude added or merged columns based on what seemed logical | Name columns explicitly and add "use exactly these column headers" |
| Format drift over a long conversation | Format instructions from earlier turns lose weight as the conversation grows | Restate the format requirement in each message where it matters |
| Null vs. missing key in JSON | Claude may omit a key entirely rather than setting it to null | Specify: "Include all fields even if the value is null — never omit a key" |
Structured Output in Pipelines
When Claude's output feeds directly into code, a few extra practices help:
- Parse defensively. Even with good prompting, occasionally Claude adds a preamble or trailing sentence. Strip whitespace and, for JSON, try parsing after removing any
```fences as a fallback. - Validate the schema. Use a library like Python's
pydanticor JavaScript'szodto validate Claude's output against your expected shape before passing it downstream. - Use the API's structured output feature. When calling Claude via the API, you can pass a JSON schema directly as a parameter — this enforces structure at the model level rather than relying purely on prompting. Covered in the Advanced API course.