Specs, Examples, and Constraints

"Write me a landing page." "Summarize these interviews." "Clean up this data." Every one of these requests contains dozens of decisions you haven't made yet: who it's for, how long, what to leave out, what format, what counts as done. When you don't make those decisions, the model makes them for you, silently, and differently each time.

That's the root of most "it's close but not right" results. The fix isn't a longer prompt. It's a spec: a short, precise description of the outcome you want. This lesson teaches three tools for turning fuzzy requests into precise ones. You'll learn to write specs that agents can execute, use examples to show what words can't describe, phrase constraints so models follow them without overdoing it, and get structured output you can safely feed into code.

What a spec is and why agents need one#

A spec (short for specification) describes what you want and how you'll know you got it, without dictating every step of how to get there. Engineers have written specs for decades. They matter even more with agents, because an agent will happily fill every gap with a plausible guess and keep going.

A good spec answers six questions:

Non-goals and acceptance criteria are the two sections people skip, and they're the most valuable. Non-goals stop an agent from gold-plating (adding features you didn't ask for). Acceptance criteria give it a way to check its own work before declaring victory.

Here's a reusable spec template you can drop into any project as a Markdown file and hand to a coding agent:

# Spec: CSV export for the invoices table
 
## Goal
Accountants need to get invoice data into their own spreadsheets at month end.
Today they copy-paste from the screen, which is slow and error-prone.
 
## Context
- Invoices table UI: src/app/invoices/page.tsx
- Data access: src/lib/invoices.ts (getInvoices already supports date filters)
- Users can have up to ~20,000 invoices
 
## Output
An "Export CSV" button above the invoices table that downloads the currently
filtered invoices as a CSV file.
 
## Requirements
- Columns, in order: invoice_number, client_name, issue_date, due_date,
  amount, currency, status
- Dates as YYYY-MM-DD; amounts as plain numbers with two decimals (no symbols)
- Respects whatever date and status filters are active on screen
- File name: invoices-YYYY-MM-DD.csv using today's date
 
## Non-goals
- No Excel (.xlsx) format
- No background jobs or emailing the file
- No changes to the table UI beyond adding the button
 
## Acceptance criteria
- Unit tests cover: empty result, commas and quotes in client names, filters applied
- Exporting 20,000 invoices completes in under 5 seconds locally
- Existing tests still pass; lint passes

That file took ten minutes to write. It will save far more than ten minutes of back-and-forth, and it doubles as documentation of what was built and why.

Let the agent interview you#

You don't have to write specs alone. When a request is fuzzy in your own head, have the model pull the decisions out of you before it does any work.

I want to build the following, but I haven't thought through the details:

[one or two sentences describing what you want]

Before doing any work, interview me to produce a spec. Ask me questions one at a
time, most important first, covering: the goal and audience, inputs, the exact
output, constraints, non-goals, and how we'll check it's done. Offer a sensible
default with each question so I can just say "yes". Stop after at most 10
questions, then write the spec in Markdown with those six sections.