VisaSpark
Sign in
beginner24 min

Prompt Design: Instructions and Structured Outputs

Write prompts that reliably get the response shape and quality you actually need.

What you'll learn

  • Distinguish system instructions from user messages
  • Write specific, testable prompts instead of vague ones
  • Explain why requesting structured output (like JSON) makes responses easier to use in code

Prerequisites

Explanation

A prompt is the input you give a language model, and how you write it materially changes the quality of the response — this is called prompt design or prompt engineering.

Most chat-based LLM APIs separate messages into roles. The system message sets persistent instructions and context the model should follow throughout the conversation (tone, role, constraints, what it should refuse to do). The user message is the actual question or request for this turn. Keeping these separate matters: system instructions represent the application developer's intent and should take priority over anything a user (or, importantly, untrusted retrieved content) later says — a distinction that becomes a real security concern in the prompt injection lesson later in this track.

Good prompts share a few traits:

  • Specific, not vague. "Write a short product description (2-3 sentences) for a stainless steel water bottle, emphasizing durability" beats "write something about a water bottle."
  • Show, don't just tell. Including one or two examples of the exact input/output shape you want ("few-shot" examples) often outperforms a long paragraph of abstract instructions.
  • State constraints explicitly. Length limits, tone, what to avoid, and the exact output format all help the model converge on what you actually want instead of guessing.

When your code needs to parse a model's response programmatically — rather than just display it as text to a human — ask for a structured output, typically JSON with a specific shape. Many providers support a strict "JSON mode" or schema-constrained output that guarantees valid, parseable JSON matching a schema you define, instead of hoping the model's free-form text happens to look like JSON. This is the difference between reliably extracting {"sentiment": "positive", "confidence": 0.92} from code versus regex-parsing a paragraph and hoping for the best.

Example

A mock 'prompt evaluator' that checks whether a prompt string includes the traits of a well-specified prompt (a teaching stand-in — real prompt quality ultimately requires judgment and testing against a real model).

function promptQualityScore(prompt) {
  let score = 0;
  if (/\d+/.test(prompt)) score += 1; // mentions a specific number/constraint
  if (prompt.length > 40) score += 1; // not just a one-word vague request
  if (/format|json|structure/i.test(prompt)) score += 1; // requests a specific output shape
  return score;
}

console.log(promptQualityScore("write something"));
console.log(promptQualityScore("Summarize this article in exactly 3 bullet points, returned as a JSON array of strings."));

Try it yourself

Try scoring your own prompt string.

Code editor. Press Escape then Tab to leave the editor if keyboard focus becomes trapped. Press Control+Shift+M inside the editor to toggle Tab-key focus trapping.

Loading editor…

Guided exercise

Guided exercise

Write a function `buildMessages(systemInstructions, userQuestion)` that returns an array of two objects: `{ role: 'system', content: systemInstructions }` and `{ role: 'user', content: userQuestion }`, in that order.

Checks: Returns exactly two messages · First message is the system role/content · plus 1 hidden check

Code editor. Press Escape then Tab to leave the editor if keyboard focus becomes trapped. Press Control+Shift+M inside the editor to toggle Tab-key focus trapping.

Loading editor…

Stuck? Get a hint.

Independent exercise

Independent exercise

Write a function `parseStructuredReply(jsonText)` that safely parses a JSON string reply and returns the parsed object, or returns `{ error: 'invalid response format' }` if parsing fails (do not let it throw).

Checks: Valid JSON parses correctly · plus 1 hidden check

Code editor. Press Escape then Tab to leave the editor if keyboard focus becomes trapped. Press Control+Shift+M inside the editor to toggle Tab-key focus trapping.

Loading editor…

Stuck? Get a hint.

Common mistakes

  • Writing vague prompts ('make it better') and being surprised the output doesn't match an unstated expectation.
  • Treating system instructions as optional — they establish the priority boundary the model should respect.
  • Trying to regex-parse free-form text instead of requesting a structured JSON response when code needs to consume the output.

Knowledge check

Knowledge check

1. What is the purpose of a system message?
2. Why request structured output (like JSON) instead of free-form text?
3. Which of these is the most well-specified prompt?

Takeaway

System instructions set the rules of the conversation; specific, structured requests get you outputs your code can actually use.

Summary

System messages carry persistent, higher-priority instructions; user messages carry the immediate request. Specific, example-driven prompts outperform vague ones, and requesting structured output (like schema-constrained JSON) makes model responses reliably consumable by code.

References

Your notes

Notes save automatically.

Finished this lesson?

Mark it complete to track your progress and schedule a future review.

Next: Embeddings and Vector Similarity →