ysskrishna logoysskrishna

Chapter 3 of 8 · 2 min

Output contracts: get the shape you need

Specify format, length and structure so the result drops straight into your next step: a diff, a JSON object, a table or a three-line summary.

An output contract is the part of a prompt that says exactly what you want back. Without one, you get the model's default: a friendly paragraph, a recap of your question, a list of caveats, and the answer somewhere in the middle.

Contracts matter more for agents than for chat, because agent output often feeds a next step: a script parses it, another agent reads it, or you paste it into a PR.

Four parts of a contract

  1. Format: diff, JSON, Markdown table, bullet list, a single line.
  2. Skeleton: the exact fields or headings.
  3. Limits: maximum items, lines or words.
  4. Gap handling: what to output when information is missing.

Example: a JSON contract

Review the diff below for security issues.

Return only JSON, no prose, matching:
{
  "issues": [
    {"file": string, "line": number, "severity": "high"|"medium"|"low",
     "problem": string (max 20 words), "fix": string (max 20 words)}
  ],
  "summary": string (max 25 words)
}
If there are no issues, return {"issues": [], "summary": "No issues found."}.

The "if there are no issues" line is gap handling. Without it, some models invent a low-severity issue to fill the list.

Example: a review summary for humans

Output:
- Line 1: verdict, one of APPROVE / REQUEST CHANGES.
- Then at most 5 bullets, most important first, each "path:line - problem - fix".
- No introduction, no closing summary.

Use the host's structured output when you can

Many APIs can enforce a JSON Schema on the response (often called structured outputs or JSON mode). When you call a model from code, prefer that over asking nicely: the API guarantees the shape. In an interactive agent, a clear contract in the prompt is the next best thing. Check the result once with a parser and tell the agent when it drifts.

Contracts for subagents

When a main agent delegates (see the Agent Building Blocks course), the subagent's output lands in the main context. A tight contract there protects your budget:

Return at most 15 lines: <path>:<line> | <symbol> | <why it matters>.
End with: START HERE: <one path>.

Step by step: add a contract to a prompt you reuse

  1. Pick a prompt you run often (code review, test plan, commit message).
  2. Look at the last three results. Note what you deleted or rewrote each time.
  3. Write a contract that would have produced the edited version: format, skeleton, limits, gaps.
  4. Run the prompt on two new inputs. If you still edit the output, tighten the skeleton.

Common mistakes

  • Length in vague words. "Brief" means different things to different models. Use numbers.
  • Skeleton without types. Say "severity": "high"|"medium"|"low", not just severity.
  • Contradictions. "Be thorough" plus "max 3 bullets" makes the model choose; it may choose wrong.
  • Forgetting the empty case. Always say what to return when there is nothing to report.

Practice: tighten a vague request

Before: "Review this PR and tell me what you think."

After, with a contract:

Review the diff in this PR for correctness and security only.
Output exactly:
- Verdict: approve | request changes
- Blocking issues: numbered list, each with file:line and a one-line fix (or "none")
- Non-blocking: at most 3 bullets
No praise, no restating the diff.

Run both on the same PR and compare: the second is shorter, easier to skim, and you can tell at a glance whether it followed the contract.

Quick check

  1. What are the four parts of an output contract?Format, skeleton, limits and gap handling.

  2. Your review prompt sometimes invents trivial issues. What part is missing?Gap handling: say what to return when there are no issues.

  3. When should you prefer an API-level schema over a prompt?When you call the model from code and need the shape guaranteed.

Continue exploring

CourseCover image for Agent Building Blocks: Skills, Subagents, MCP and Hooks

Agent Building Blocks: Skills, Subagents, MCP and Hooks

A free, hands-on course on the four pieces behind Cursor and Claude Code agents: skills, subagents, MCP servers and hooks. Build each one, then combine them.

Agent Skills
Chat & AI
+1

9 chapters · 30 min

BlogCover image for 17 Thinking Skills for AI Agents: Pre-Mortem, Five Whys, Six Hats and More

17 Thinking Skills for AI Agents: Pre-Mortem, Five Whys, Six Hats and More

AI Apps & Assistants
Agent Skills
4 min read
ToolCover image for AI Token Counter

AI Token Counter

AI token counter with model pricing and context-window comparison in your browser.

Chat & AI
AI Apps & Assistants
+1
Productskills.sh+1Claude Code Subagents for Cursor

Claude Code Subagents for Cursor

Your Cursor subagents can finally run on the model you picked in each agent file.
Chat & AI
Agent Skills
AI Apps & Assistants
Bash
BlogCover image for How to Install Caveman in Cursor and Claude Code

How to Install Caveman in Cursor and Claude Code

AI Apps & Assistants
Agent Skills
+1
3 min read
BlogCover image for Publish AI Agent Skills to ClawHub: Stop Re-Pasting Your AI Workflow

Publish AI Agent Skills to ClawHub: Stop Re-Pasting Your AI Workflow

AI Apps & Assistants
Agent Skills
3 min read