A spec is a written description of what you want built and why, handed to the agent before it starts. It does not have to be long. It has to be clear: the goal, the constraints, what "done" looks like, and any edge cases you already know about.
Why a spec beats a one-liner
"Add auth" leaves a thousand decisions to the model, and it will guess at every one, sometimes well, often not in the way you meant. A spec is context you provide up front so the agent solves your problem instead of a plausible nearby one. Vague input reliably produces vague output; specific input is the cheapest quality lever you have.
A workable spec usually states:
- The goal, in one or two plain sentences.
- Constraints: the stack, the patterns, what not to touch.
- Acceptance criteria: how you will know it worked.
- Known edge cases and how they should behave.
Spec, ticket, artifact
A spec is close kin to a ticket and a handoff artifact. All three are just written context that tells an agent what to do. The label matters less than the discipline of writing the thing down before you set the agent loose.
Related terms
Ticket
A ticket is a scoped unit of work carrying enough context to act on. Well-formed tickets are ideal agent inputs.
Read definition →Handoff artifact
A handoff artifact is the concrete document produced at a handoff, recording what is done, what is next, and the key decisions. The next session reads it to get up to speed fast.
Read definition →Agent
An agent is a language model wrapped in a loop that lets it call tools, read the results, and decide what to do next. The model supplies the judgement; the loop and the tools give it hands.
Read definition →