Structured Outputs: Examples, XML Tags, and Format Rules

When Instructions Fail and Examples Succeed

Instructions describe behavior in the abstract. Examples demonstrate it concretely. Claude is highly sensitive to this distinction. Tell Claude to write concise commit messages and you will get Claude's interpretation of conciseness, which may not match yours. Show Claude three commit messages that exemplify the style you want and the next commit message Claude writes will look like those three examples. The difference in adherence is substantial.

This lesson covers three techniques for getting reliable structured output from Claude: multi-shot examples in rules files, XML tags for complex instructions, and explicit format and verification specifications.

The Few-Shot Pattern in Rules Files

The most reliable way to specify output format, tone, or structure is to include examples in a rules file. Instead of describing the desired format, provide 3-5 representative examples and let Claude extract the pattern.

A commit message rules file that uses examples looks like this:

# Commit Message Format

Write commit messages in this format. Examples:

<examples>
<example>Add rate limiting to the /api/users endpoint — prevents abuse during authentication flows</example>
<example>Fix session token expiry not refreshing on activity — users were being logged out during active sessions</example>
<example>Refactor PaymentProcessor to extract Stripe-specific logic — preparation for adding a second payment provider</example>
</examples>

Claude sees the pattern from the examples: present tense, specific scope, brief rationale after the dash. No instruction needed to enumerate these rules. The examples convey the pattern more efficiently than any description.

Writing Effective Examples

Examples work best when they are relevant, diverse, and clearly separated from instructions. The <example> and <examples> XML tags signal to Claude that the enclosed content is a demonstration, not an instruction. Without the tags, Claude may treat example content as literal instructions rather than patterns to learn from.

Relevant means examples that closely mirror your actual use cases. If you want a specific PR description format, show three PR descriptions in that format, not generic placeholders.

Diverse means examples that cover different scenarios and edge cases. If all your examples are the happy-path case, Claude will struggle when an edge case appears. Include examples that cover the range of situations where the format applies.

3-5 examples is the sweet spot. Fewer than 3 leaves too much ambiguity. More than 5 starts to consume significant context with examples that provide diminishing returns. For most format specifications, 3-4 well-chosen examples are sufficient.

XML Tags for Structured Instructions

For complex CLAUDE.md entries that mix multiple types of content — instructions, context, examples, variable inputs — XML tags prevent Claude from misinterpreting which part is which. Without tags, a CLAUDE.md entry that includes both an instruction and an example of what not to do can be ambiguous. With tags, the structure is explicit:

<instructions>
API endpoints must validate all user input before processing. Use the ValidationResult type from src/types/validation.ts.
</instructions>

<context>
The ValidationResult type was added in the Q3 refactor and replaces the old boolean-return pattern. Any code using the old pattern is legacy.
</context>

<example>
// Correct — uses ValidationResult
const result = validate(input, userSchema);
if (!result.valid) return errorResponse(result.errors);
</example>

Use consistent, descriptive tag names throughout your rules files. Common useful tags: <instructions>, <context>, <example>, <input>, <output>. Avoid tags that could be confused with HTML elements that Claude might interpret as rendering instructions.

Format Specs and Templates

For repeatable artifacts — PR descriptions, release notes, code review comments, API documentation — a format spec in a rules file ensures Claude produces a consistent structure every time. A PR description rules file might include:

---
paths:
- "**/*.ts"
- "**/*.tsx"
---

# PR Description Format

When creating a pull request, use this structure:

<examples>
<example>
## Summary
One or two sentences explaining what changed and why.

## What changed
- Specific change 1
- Specific change 2

## Testing
How to verify the changes work. What tests were added or modified.
</example>
</examples>

The path-scoping means this rule only loads when Claude is working with TypeScript files — which is when PRs for TypeScript code are most likely to be created.

Verification Specs in CLAUDE.md

The definition of \"done\" belongs in context alongside the coding standards. When you embed verification specs in CLAUDE.md, Claude knows what it is working toward without you restating it each session:

# Definition of Done

Before considering any implementation complete:
- IMPORTANT: Run npm test and confirm all tests pass
- Run npm run lint and fix all errors (warnings are acceptable)
- Confirm the build succeeds with npm run build

This is more reliable than relying on per-prompt verification instructions, which can be forgotten in long sessions. The verification criteria are part of the always-loaded context.

Automation Output Formats

When running Claude non-interactively with claude -p, the --output-format flag controls how results are returned to the calling script:

• --output-format text — plain text, suitable for display
• --output-format json — structured JSON, suitable for parsing
• --output-format stream-json — streaming JSON with --verbose, suitable for real-time processing

JSON output includes metadata alongside the text response — session identifiers, token counts, tool uses. This is useful for logging, monitoring, and building automated pipelines that need more than just the text output. For debugging during development, add --verbose to see the full tool use trace. Remove it in production to reduce output noise.