Why a casual prompt is unstable
The same sentence can produce very different results on another day or another model. Usually the model did not get dumber — your requirement was never constrained: no output format, no boundaries, no examples. A structured prompt closes that gap. It does not guarantee correctness, but it makes results predictable, checkable and reusable.
Five composable modules
| Module | Purpose | Example |
|---|---|---|
| Role | Fixes viewpoint and tone | You are a senior SRE; answer in under 200 words |
| Task | What to do | Summarise this log into 3 findings |
| Context | The facts | Paste real logs, config and versions |
| Constraints | What must not happen | Do not guess missing fields; use null |
| Output format | The structure | Output JSON only, fields a, b, c |
Make the output machine-usable
Extract the text below into JSON, strictly:
1. Output JSON only - no prose, no code fences
2. Fixed fields: title, tags, summary
3. tags: array of 1-3 strings; summary: max 60 chars
4. If information is missing use null - do not invent
Text:
...Validate the shape before it reaches business code. That single step filters out most "almost right" outputs: a stray comma, a wrong field type, an explanatory preamble. Those are not model failures — they are constraints you left soft.
Few-shot beats long descriptions
Rather than describing the style in three sentences, show 2 "input → output" examples. The model imitates their structure and granularity far more reliably than abstract description. Cover both a normal case and an edge case: one ideal output, one showing what to do when information is missing (null, not invention).
Common mistakes
- Format rules at the end: they get ignored — place them after the task, before the context;
- Words like "try" or "preferably": vague phrasing relaxes constraints; use hard rules (must / must not / null when missing);
- Asking many things at once: split into turns, each advancing one decision;
- Trusting output without validation: structured output can still lack fields or mistype them — validate first.
Follow-up questions
Can a prompt be an interface contract? No, not by itself. It constrains this conversation; a real contract is enforced in code with schema validation, retries, fallback and rollback. Is a longer prompt better? Not necessarily — redundancy dilutes the point, and clear modules beat length. When you need a lot of background, use RAG to inject only the relevant fragments.
A skeleton you can copy
Role:
Task:
Context:
Constraints:
Output:
Examples: <1-2 "input -> output" pairs> Keep it as a team prompt template — far more stable than improvising each time. For a new task you replace the module contents, not the structure.
Try it: JSON formatter and validator
Validating and retrying structured output
- Enforce a schema: prefer the model's JSON Schema or function-calling support over "please answer in JSON" in the prompt;
- Always validate: even when the model claims to comply, parse and validate; on failure, feed the error back for one retry;
- Cap retries: allow one or two, or you enter a fix-then-fail loop that multiplies cost;
- Have a fallback: route failures to a safe path such as a human queue instead of surfacing a parse error.
Prompt versus validation
The prompt encourages the right shape; validation ensures a wrong shape is detected. Treating them as one layer is a classic mistake: say "always return JSON" in the prompt, skip parsing, and production eventually sees a parse failure. Structural guarantees come from code, not model goodwill.