When to use it
Right before you hand a coding agent (Claude Code, Cursor, Spec Kit, Kiro) a feature or a service to build. The classic failure of "vibe coding" is a vague request like "make a login" — the model fills in the behavior itself and drifts away from what you meant. Spec-driven fixes that: spec first, code second. The AI's role here is systems analyst writing a spec, not code. Output: a document the agent builds from, and that stays the source of truth as things change.
The prompt (copy and paste)
You are a systems analyst. Do not write code. Write an EXECUTABLE SPEC for a coding AI agent —
the single source of truth it will generate the implementation from.
FEATURE/SERVICE: "<PASTE what needs to be built>"
CONTEXT: <stack/environment if known; otherwise propose one and record it as [assumption]>
The spec, section by section:
1. Goals and non-goals: what the system does and what it does NOT do (the boundaries), as one list.
2. Requirements in EARS format: "WHEN <event>, the system SHALL <response>" / "IF <condition>, THEN …" —
numbered, each one verifiable and unambiguous.
3. Contracts: inputs/outputs, data shapes (fields and types), APIs/signatures, error codes.
4. Edge cases and error handling: empty/invalid data, races, limits, offline.
5. Acceptance criteria: a "done when …" checklist the CODE can be checked against (ideally, future tests).
6. Open questions: what has to be decided before code; give a recommended default for each.
Write it so that two different developers would build the same thing from this spec. No "etc." — be specific.
Where you lack data, make a reasonable assumption and mark it [assumption]; don't invent facts silently.
The technique: spec-driven development, a practice that took shape in 2025 as the answer to "intent drift" in AI agents — the executable spec becomes the source of truth and the code is derived from it. Writing requirements in EARS removes ambiguity.
Filled-in example
Feature: "magic-link email sign-in (passwordless), no password". Context: TS / Node / PostgreSQL.
Expected AI response: non-goals ("no OAuth, no 2FA in v1"); EARS requirements ("WHEN the user submits an email, the system SHALL send a one-time link valid for 15 minutes"; "IF the link has expired, THEN the system SHALL show an error and offer to send a new one"); the contract POST /auth/magic-link {email} → codes 200/400/429; edge cases — repeat requests (rate limit), a non-existent email (don't leak that it doesn't exist); acceptance criteria as a checklist. With this spec, the coding agent no longer "fills in" the link lifetime or the repeat-request behavior.
Variations
- Spec Kit / Kiro style. Ask it to split the output into three files:
requirements.md(EARS) →design.md→tasks.md(atomic tasks) — for tools that expect exactly that. - On top of legacy. "Take existing module
into account: what we reuse, what we must not break" — adds a compatibility section. - Spec as tests. "From the acceptance criteria, generate a list of test cases (input → expectation)" — the bridge to TDD.
Pro tips
- The spec stays alive: when a requirement changes, edit the spec and regenerate the code instead of patching the code directly. Otherwise code and intent drift apart again.
- Insist on EARS phrasing: "the system shall respond to
" is verifiable, "a convenient fast login" is not. - The "non-goals" section saves the most: that's exactly where half of an agent's wasted work goes when the boundaries aren't set.