Spec-Driven Development: a BDD, DDD, MDE & API-First guide

Table of Contents

• First you write what the software should do, then the code
• Why SDD became trendy again: the AI codes, you specify
• 1. Behavior-Driven Development (BDD): the specification that runs
• 2. Domain-Driven Design (DDD): the business model as specification
• 3. Model-Driven Engineering (MDE) and Model-Driven Architecture (MDA): from model to generated code
• 4. API-First and Contract-Driven Development (CDD): the contract rules
• Comparison: which approach is right for you?
• SDD with AI: a workflow you can use tomorrow

  • How to do it with OpenSpec
• Common mistakes when starting with SDD
• Conclusion
• Frequently asked questions
• Sources

First you write what the software should do, then the code

It has surely happened to you: the client asks for "a bot that books appointments", the team starts coding and, three weeks later, nobody agrees on what "booking" meant. Could appointments be cancelled? What happened if the time slot was already taken? The code exists, but the idea was never written down.

Spec-Driven Development (SDD), or specification-driven development, attacks exactly that problem. The rule is simple: the specification is the main artifact of the project, and code, tests and documentation are derived from it. If the business changes, the specification changes first; the code comes after.

It is not a single methodology. It is a family of approaches that put a specification, a model or a contract at the center of the whole software life cycle (SDLC). In this article you will see the four most used ones —BDD, DDD, MDE/MDA and API-First—, how they compare and how to apply them today, when a good part of the code is already written by AI.

Why SDD became trendy again: the AI codes, you specify

The idea of specifying before coding is decades old. What's new is who writes the code. With AI agents like Copilot, Claude Code or Cursor, generating code is cheap; the expensive part is knowing what to generate.

If you ask an agent for "a login" with no further context, you will get a login, not your login. That way of working on intuition earned itself a name: vibe coding. It works for prototypes and breaks down in real projects.

That's why tools appeared that put the specification at the center of working with AI:

• OpenSpec: my recommendation. It is lightweight, works with more than 30 AI assistants (Claude Code, Cursor, Copilot and others) and is designed for projects that already exist, not only for starting from scratch.
• Kiro: an AWS IDE that turns each feature into three files: requirements.md, design.md and tasks.md.
• GitHub Spec Kit: an open source kit with a more rigid, phase-based process; especially useful if you work with GitHub Copilot.

The specification went from being a document nobody read to being the most important prompt of the project.

1. Behavior-Driven Development (BDD): the specification that runs

BDD takes the ideas of TDD into the language of the business. The specification is behavior scenarios written in structured natural language, almost always in Gherkin format (Given / When / Then).

Feature: Booking an appointment via WhatsApp

  Scenario: The requested time slot is already taken
    Given a client messaging the clinic's bot
    And Tuesday at 10:00 already has an appointment assigned
    When the client requests an appointment on Tuesday at 10:00
    Then the bot replies that the time slot is not available
    And offers the three closest free time slots

How it goes through the life cycle:

• Analysis and design: business, development and QA write the scenarios together in the "Three Amigos" meeting.
• Development and testing: each scenario is connected to an automated test (Cucumber, Behave, SpecFlow/Reqnroll) that fails before the feature is coded.
• Maintenance: the .feature files are living documentation: if they stop being true, the tests fail.

Use it when the biggest risk of the project is misunderstanding what the client is asking for.

2. Domain-Driven Design (DDD): the business model as specification

In DDD the specification is a rich domain model and a ubiquitous language: the same words, with the same meaning, in the meeting with the client, on the board and in the code. If the business says "reservation", the class is called Reservation, not BookingItemDTO.

How it goes through the life cycle:

• Analysis and strategy: with workshops like Event Storming you discover the business events and divide them into Bounded Contexts (for example, Schedule, Billing and Notifications), connected by a context map.
• Architecture and implementation: tactical design (Entities, Value Objects, Aggregates, Domain Events) translates the model directly into code.
• Evolution: when a business rule changes, the model is updated first, and then the architecture and the code.

An example of the ubiquitous language turned into code:

// Bounded Context: Schedule
class Appointment {
  reschedule(newSlot: TimeSlot) {
    if (this.status === "cancelled") throw new Error("A cancelled appointment cannot be rescheduled");
    this.slot = newSlot;
    this.record(new AppointmentRescheduled(this.id, newSlot));
  }
}

Use it when the complexity is in the business rules, not in the technology.

3. Model-Driven Engineering (MDE) and Model-Driven Architecture (MDA): from model to generated code

Here the specification is a formal model: UML diagrams, a domain-specific language (DSL) or any modeling language. MDA is the variant standardized by the OMG, which separates a platform-independent model (PIM) from a platform-specific one (PSM).

How it goes through the life cycle:

• Design: abstract models are built, without tying yourself to a language or a framework.
• Build and deployment: transformation engines convert the models into source code, database schemas, infrastructure scripts and tests.
• Maintenance: the system is updated by changing the high-level model and regenerating; the generated code is not touched by hand.

You use it more than you think: a schema.prisma that generates the database and the client, or a Terraform file that defines your infrastructure, are small examples of this philosophy. Low-code platforms take the idea to the extreme.

Use it when you have many similar systems or highly regulated domains where it is better to generate than to write. Beware of rigidity: if the transformation tools can't keep up, the team ends up editing the generated code and the model stops being the truth.

4. API-First and Contract-Driven Development (CDD): the contract rules

This is the most practical application of SDD in service architectures, microservices and integrations. The specification is the API contract, written in an open standard before coding: OpenAPI (Swagger) for REST, AsyncAPI for events or Protobuf for gRPC.

openapi: 3.1.0
info:
  title: Appointments API
  version: 1.0.0
paths:
  /appointments:
    post:
      summary: Create an appointment
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [clientId, timeSlot]
              properties:
                clientId: { type: string }
                timeSlot: { type: string, format: date-time }
      responses:
        "201": { description: Appointment created }
        "409": { description: The time slot is already taken }

How it goes through the life cycle:

• Design: the contract is agreed between whoever exposes the API and whoever consumes it.
• Parallel development: from the contract you generate mock servers, client SDKs and code skeletons, so frontend and backend move forward at the same time without waiting for each other.
• Integration and deployment: contract tests (Consumer-Driven Contracts with tools like Pact) run in the CI/CD pipeline and block any change that breaks a consumer.

Use it when several teams or systems depend on the same API, as in integrations with WhatsApp, CRMs or payment gateways.

Comparison: which approach is right for you?

They don't compete with each other: they attack different risks and combine well.

Methodology	Central artifact	Main focus in the SDLC	Mostly solves
BDD	Behavior scenarios (.feature)	Business-development-QA alignment and validation	"We built something the client didn't ask for"
DDD	Domain model and ubiquitous language	Architecture, complexity and business	"The business rules are scattered all over the code"
MDE / MDA	Abstraction models (UML, DSL)	Automatic generation and abstraction	"We write the same thing by hand over and over"
API-First / CDD	API contracts (OpenAPI, AsyncAPI, Protobuf)	Integration, microservices and parallelism	"Every deployment breaks an integration"

A frequent combination in real projects: DDD to divide the system into contexts, API-First to define how those contexts talk to each other and BDD to validate every feature from the user's point of view.

SDD with AI: a workflow you can use tomorrow

You don't need to adopt the four methodologies to get started. This workflow works with any AI agent and a few Markdown files in your repository; further down I show you how to automate it with OpenSpec.

1. Specify: write in spec.md what the feature should do and why, with acceptance criteria. BDD scenarios and the DDD ubiquitous language fit here.
2. Plan: ask the agent for a plan.md with the architecture, the stack and the contracts (your OpenAPI lives here). Review it yourself before moving on.
3. Tasks: divide the plan into a tasks.md with small, verifiable steps, one per commit.
4. Implement: the agent executes one task at a time, always reading the specification and the plan as context.
5. Verify: the tests derived from the specification say whether the task is done, not intuition.

The golden rule: when a requirement changes, you edit the specification and let the change flow downwards. If you fix things directly in the code, the specification stops being the truth and you go back to vibe coding.

How to do it with OpenSpec

OpenSpec is the tool I recommend for applying this workflow. Compared to Spec Kit, it has three practical advantages:

• Less ceremony: it doesn't force you through rigid phases; you iterate on the proposal until it is clear.
• Designed for existing projects: each change lives in its own folder as a delta over the current specs, so you don't have to document the whole system before starting.
• It doesn't tie you to one agent: it works with Claude Code, Cursor, Copilot, Amazon Q and dozens more.

To install it you need Node.js 20.19 or higher:

npm install -g @fission-ai/openspec@latest
cd your-project
openspec init

Then, from your AI agent, the cycle has three commands:

1. /opsx:propose: creates a folder in openspec/changes/ with the proposal, the affected specs, the design and the tasks. You review and adjust before moving on.
2. /opsx:apply: the agent implements the tasks following the specification.
3. /opsx:archive: the finished change is archived and its specs become part of openspec/specs/, the source of truth of the project.

If you don't have a clear idea yet, /opsx:explore lets you think through the requirements with the agent before creating the proposal. The exact command syntax may vary depending on the assistant you use.

Common mistakes when starting with SDD

• Over-specifying: nobody maintains a 40-page spec. Start with one page per feature.
• Specifying how instead of what: "use Redis" goes in the plan, not in the specification.
• A spec that is never verified: if no test or contract validates it, it goes stale within weeks.
• Changing the code and forgetting the spec: it is the mistake that turns SDD into dead documentation.

Conclusion

Spec-Driven Development is not bureaucracy: it is writing down first what you will have to explain anyway. BDD, DDD, MDE and API-First are four ways to do it, each with its own artifact and its favorite risk. With AI agents writing more and more code, the specification became your best tool to make sure the result is what you need.

Your next step: take the next feature of your project, write its spec.md with three Given/When/Then scenarios and hand it to your AI agent before asking for a single line of code. Tell me in the comments how it went.

Frequently asked questions

Is SDD the same as TDD? No. TDD starts from unit tests written by the developer; SDD starts from a higher-level specification from which tests, code and documentation can come. BDD is the bridge between both.

Does it work for small teams or personal projects? Yes. A spec.md and a tasks.md are enough for an AI agent to work with far more focus, even if you are a team of one.

Do I have to use all four methodologies? No. Choose based on your biggest risk: misunderstandings with the client (BDD), complex business rules (DDD), repetitive code (MDE) or fragile integrations (API-First).

What tools do I need to get started? An editor, Markdown and your favorite AI agent. If you want ready-made structure, start with OpenSpec: it installs with one command and works with the agent you already use.

Sources

• OpenSpec (repository)
• Kiro: Specs documentation
• GitHub Spec Kit (repository)
• Pact: Consumer-Driven Contract Testing