What is Spec-Driven Development

Core Concepts

What Spec-Driven Development Is

Spec-driven development is a practice where you write a structured, explicit specification before giving a task to an AI agent or model. The spec defines what you want, the constraints it must respect, the format of the output, and enough context for the model to act without guessing.

The word "driven" matters. The spec is not documentation you write after the fact. It is the input that drives the generation. Writing the spec is the work. Running the model is the execution.

A three-person team is building a My-Calendar scheduling platform. One of the first tasks is generating the email notification sent to clients after they book a time slot. An engineer types: "Write a booking confirmation email." The model produces something reasonable-sounding but generic. It does not match the product's tone. It includes placeholder fields the team does not use. It omits the calendar link the product actually generates. Two rounds of back-and-forth later, the engineer has something usable, but the next engineer on the team starts from scratch when they need the cancellation email.

With spec-driven development, the team writes a spec first. That spec defines: what the email is for, who receives it, what data fields are available, what tone the product uses, what must be included, and what must not be included. Every email-related generation task starts from that spec. The results are consistent. The review time drops. New team members can produce on-day-one output that matches what senior engineers produce.

How It Differs from Ad-Hoc AI Use

Ad-hoc AI use means typing a prompt when you need something and seeing what you get. It works for individual, low-stakes tasks where iteration is cheap. It breaks down when:

• Multiple people on a team need to produce consistent outputs
• The task has constraints the model cannot infer from a short prompt
• The output feeds into another system, a design, or a downstream process
• You need to reproduce the same quality result next week or next month

Spec-driven development replaces improvisation with repeatability. The spec is a shared artifact. It can be reviewed, improved, versioned, and reused. The model's output becomes predictable because the input is controlled.

The Cost of Ambiguity

Ambiguous instructions do not produce ambiguous outputs. They produce confident outputs that are wrong in ways that are hard to spot immediately.

When the scheduling platform team asks the model to "add validation to the booking form," the model has to guess what that means. Does it mean client-side validation? Server-side? Both? Does it validate that the time slot is still available? That the client email is real? That the booking window has not already passed? A model working from that instruction will pick an interpretation and execute it fully and fluently. The engineer reviews what comes back, and it looks correct. It is only in testing, or after a bug report, that the missing constraint surfaces.

The cost is not just the time to fix the mistake. It is the confidence erosion. Teams that experience this repeatedly stop trusting AI-generated output and over-review everything, or stop using AI for anything that matters. Both outcomes eliminate the productivity gain.

Ambiguity at scale is worse. In a team of five engineers all generating code against the same feature, five different mental models of "add validation" produce five different implementations. The integration review takes longer than writing the code would have.

What Makes a Spec Agent-Readable

A traditional requirements document is written for a human reader. It uses natural language, assumes shared context, and leaves details to professional judgment. A sentence like "the booking confirmation email should be professional and on-brand" is useful to a human designer who knows the product. It is useless to a model that does not.

An agent-readable spec is written for a model. It makes the implicit explicit. It removes ambiguity not by being longer, but by being precise about the things that matter.

For the scheduling platform's booking confirmation email, a traditional requirement might read: "Send users a confirmation email when they book a meeting." An agent-readable version of the same requirement looks like this:

Task: Generate the HTML and plain-text content for a booking confirmation email.

Recipient: The client who submitted the booking (not the host).

Available data fields: client_name, host_name, meeting_title, start_datetime (ISO 8601), duration_minutes, calendar_link, cancellation_link.

Tone: Friendly but professional. No exclamation marks. No filler phrases like "We're so excited to meet you."

Must include: calendar_link, cancellation_link, formatted start_datetime in the recipient's local timezone.

Must not include: The host's personal email address, any pricing information, any reference to the platform name in the body copy.

Output format: Two sections: html and plain_text. Use semantic HTML for the email body. Plain text must be readable without rendering.

The agent-readable spec takes two minutes longer to write. It eliminates three rounds of revision.

Key Points

• Spec-driven development means writing a structured specification before you give a task to an AI model or agent
• Ad-hoc AI use fails at the team level: inconsistency, low reusability, and compounding ambiguity
• Ambiguous instructions produce confident wrong outputs, not ambiguous outputs
• Agent-readable specs make the implicit explicit: they are written for a model, not a human reviewer
• The spec is the artifact under review, not the generated output

---

Actionable Takeaways

1. Pick one task you regularly give to AI, something you do at least once a week. Write down exactly what you currently type. That is your baseline.

2. Identify three things the model has to guess when it reads that prompt: context it does not have, constraints you have not stated, or output requirements you are inferring from what comes back.

3. Rewrite your prompt as a spec. Add a task statement, the relevant context, at least two constraints (what to include, what to avoid), and the expected output format. Keep it under 200 words.

4. Run both versions against the same model. Compare the outputs. Note which one required fewer follow-up prompts to reach a usable result.

5. Share the spec with one colleague and ask them to run it without any additional context from you. If their output matches yours, the spec is working.

---

Practical Examples

Example 1: The Admin Dashboard Filter (Engineering)

An engineer on the scheduling platform needs to implement a filter on the admin dashboard that lets hosts see bookings by status: upcoming, completed, and cancelled. The ad-hoc prompt: "Add a status filter to the bookings table."

The model generates a working filter, but it uses a client-side approach with hardcoded status strings. The actual status values in the database are integers. The filter breaks in production.

The spec version:

Task: Implement a status filter for the bookings table on the admin dashboard.

Filter options: Upcoming, Completed, Cancelled (display labels). Map to database values: 0 (upcoming), 1 (completed), 2 (cancelled).

Behavior: Filter applies on selection without a submit button. URL query param ?status= updates to reflect current filter. Default state shows all bookings.

Stack: React frontend, REST API at /api/bookings?status=. API already handles the status query parameter.

Do not: Hardcode status values in the component. Import status constants from src/constants/bookingStatus.js.

The spec took four minutes to write. The generated component worked on the first run and passed code review without changes.

Example 2: Onboarding Email Copy (Product Manager)

A product manager needs copy for the onboarding email sent when a new host signs up. The ad-hoc prompt: "Write a welcome email for new users."

The model produces a generic welcome email that could belong to any SaaS product. It uses the phrase "powerful features" twice. It does not mention the one action the PM needs new hosts to take: connecting their calendar.

The spec version:

Task: Write the subject line and body copy for the welcome email sent to new hosts after account creation.

Primary goal: Get the host to connect their calendar. This is the single most important action. The email should make this feel easy and necessary, not optional.

Tone: Direct, warm, no filler. The product voice is calm and capable: it does not oversell.

Must include: A clear call to action to connect calendar (with placeholder for the link), a one-sentence explanation of why it matters (without time slots connected, clients cannot book).

Must not include: Feature lists, "powerful" or "seamless" or similar adjectives, more than one CTA.

Length: Subject line under 50 characters. Body under 120 words.

The first output was usable. Light editing reduced it to final copy in five minutes.

Example 3: Definition Alignment (Technical Director)

A technical director notices that two engineers on the team produced different implementations of the same calendar sync feature because they had different mental models of what "calendar sync" meant: one built one-way push (platform to calendar), the other built bidirectional sync.

The director writes a feature spec:

Feature: Calendar sync between the scheduling platform and the host's external calendar (Google Calendar, Outlook).

Sync direction: One-way only. Platform availability windows are the source of truth. Changes in the external calendar do NOT update the platform.

Scope: When a booking is confirmed, create a calendar event in the host's connected calendar. When a booking is cancelled, delete that event.

Out of scope: Reading events from external calendars. Blocking off time based on external events. Two-way conflict detection.

That spec, reviewed by the team in ten minutes, would have prevented two weeks of rework.

---

Implementation Workflow

This exercise produces a real spec you can use this week. Work through each step in order.

1. Choose your task. Pick one thing you currently use AI for in your work on or around the scheduling platform (or your own equivalent project). It should be a task you have done more than once. Write the task name at the top of a blank document.

2. Write your current prompt. Type out the prompt you normally use, exactly as you would type it into a chat interface. Do not improve it yet. This is your honest baseline.

3. Audit the ambiguity. Read your prompt as if you have never seen the product before. List every piece of context the model would need to guess: data shapes, tone, constraints, output format, what to exclude.

4. Write the spec. Structure it with these fields:

   • Task: One sentence. What are you asking for?
   • Context: What does the model need to know about the product or situation?
   • Constraints: What must the output include? What must it not include?
   • Output format: What does a correct result look like? Length, structure, format.

5. Run the spec. Paste it into your AI tool of choice without adding anything else. Do not prompt-engineer mid-conversation. Let the spec do the work.

6. Compare. Run your original prompt in a separate session. Put the two outputs side by side. Ask: which one requires fewer follow-up messages to reach something you can actually use?

7. Store the spec. Save it in a shared location your team can access: a specs/ folder in your repo, a Notion page, a shared doc. Give it a filename that reflects the task. This is now a team asset, not a personal shortcut.