Spec-Driven Development: guia de BDD, DDD, MDE e API-First

Índice

• Primeiro se escreve o que o software deve fazer, depois o código
• Por que o SDD voltou à moda: a IA programa, você especifica
• 1. Behavior-Driven Development (BDD): a especificação que executa
• 2. Domain-Driven Design (DDD): o modelo do negócio como especificação
• 3. Model-Driven Engineering (MDE) e Model-Driven Architecture (MDA): do modelo ao código gerado
• 4. API-First e Contract-Driven Development (CDD): o contrato manda
• Comparativo: qual abordagem serve para você?
• SDD com IA: um fluxo que você pode usar amanhã

  • Como fazer isso com OpenSpec
• Erros comuns ao começar com SDD
• Conclusão
• Perguntas frequentes
• Fontes

Primeiro se escreve o que o software deve fazer, depois o código

Com certeza você já viveu isso: o cliente pede "um bot que agende consultas", o time começa a programar e, três semanas depois, ninguém concorda sobre o que significava "agendar". Dava para cancelar? O que acontecia se o horário já estivesse ocupado? O código existe, mas a ideia nunca foi escrita.

O Spec-Driven Development (SDD), ou desenvolvimento guiado por especificações, ataca exatamente esse problema. A regra é simples: a especificação é o artefato principal do projeto, e o código, os testes e a documentação são derivados dela. Se o negócio muda, primeiro muda a especificação; o código vem depois.

Não é uma metodologia única. É uma família de abordagens que colocam uma especificação, um modelo ou um contrato no centro de todo o ciclo de vida do software (SDLC). Neste artigo você vai ver os quatro mais usados —BDD, DDD, MDE/MDA e API-First—, como eles se comparam e como aplicá-los hoje, quando boa parte do código já é escrita por uma IA.

Por que o SDD voltou à moda: a IA programa, você especifica

A ideia de especificar antes de programar tem décadas. O novo é quem escreve o código. Com agentes de IA como Copilot, Claude Code ou Cursor, gerar código é barato; o caro é saber o que gerar.

Se você pede a um agente "me faça um login" sem mais contexto, vai receber um login, não o seu login. Essa forma de trabalhar por intuição ganhou um nome: vibe coding. Funciona para protótipos e quebra em projetos reais.

Por isso surgiram ferramentas que colocam a especificação no centro do trabalho com IA:

• OpenSpec: minha recomendação. É leve, funciona com mais de 30 assistentes de IA (Claude Code, Cursor, Copilot e outros) e foi pensado para projetos que já existem, não só para começar do zero.
• Kiro: IDE da AWS que transforma cada funcionalidade em três arquivos: requirements.md, design.md e tasks.md.
• GitHub Spec Kit: kit open source com um processo mais rígido, dividido por fases; útil principalmente se você trabalha com GitHub Copilot.

A especificação passou de documento que ninguém lia para o prompt mais importante do projeto.

1. Behavior-Driven Development (BDD): a especificação que executa

O BDD leva as ideias do TDD para a linguagem do negócio. A especificação são cenários de comportamento escritos em linguagem natural estruturada, quase sempre no formato Gherkin (Given / When / Then, ou em português Dado / Quando / Então).

Feature: Agendar consulta por WhatsApp

  Scenario: O horário solicitado já está ocupado
    Given um cliente que conversa com o bot da clínica
    And a terça-feira às 10:00 já tem uma consulta marcada
    When o cliente pede uma consulta na terça-feira às 10:00
    Then o bot responde que o horário não está disponível
    And oferece os três horários livres mais próximos

Como ele percorre o ciclo de vida:

• Análise e design: negócio, desenvolvimento e QA escrevem juntos os cenários na reunião dos "Três Amigos".
• Desenvolvimento e testes: cada cenário é conectado a um teste automatizado (Cucumber, Behave, SpecFlow/Reqnroll) que falha antes de programar a funcionalidade.
• Manutenção: os arquivos .feature são documentação viva (living documentation): se deixam de ser verdadeiros, os testes falham.

Use quando o maior risco do projeto é interpretar mal o que o cliente pede.

2. Domain-Driven Design (DDD): o modelo do negócio como especificação

No DDD a especificação é um modelo de domínio rico e uma linguagem ubíqua: as mesmas palavras, com o mesmo significado, na reunião com o cliente, no quadro e no código. Se o negócio diz "reserva", a classe se chama Reserva, não BookingItemDTO.

Como ele percorre o ciclo de vida:

• Análise e estratégia: com oficinas como Event Storming você descobre os eventos do negócio e os divide em Bounded Contexts (por exemplo, Agenda, Faturamento e Notificações), conectados por um context map.
• Arquitetura e implementação: o design tático (Entidades, Objetos de Valor, Agregados, Eventos de Domínio) traduz o modelo diretamente para código.
• Evolução: quando uma regra de negócio muda, primeiro se atualiza o modelo e depois a arquitetura e o código.

Um exemplo da linguagem ubíqua convertida em código:

// Bounded Context: Agenda
class Reserva {
  reagendar(novoHorario: Horario) {
    if (this.status === "cancelada") throw new Error("Uma reserva cancelada não pode ser reagendada");
    this.horario = novoHorario;
    this.registrar(new ReservaReagendada(this.id, novoHorario));
  }
}

Use quando a complexidade está nas regras do negócio, não na tecnologia.

3. Model-Driven Engineering (MDE) e Model-Driven Architecture (MDA): do modelo ao código gerado

Aqui a especificação é um modelo formal: diagramas UML, uma linguagem específica de domínio (DSL) ou qualquer linguagem de modelagem. A MDA é a variante padronizada pelo OMG, que separa um modelo independente de plataforma (PIM) de um específico de plataforma (PSM).

Como ele percorre o ciclo de vida:

• Design: constrói-se modelos abstratos, sem se prender a uma linguagem ou a um framework.
• Construção e implantação: motores de transformação convertem os modelos em código-fonte, schemas de banco de dados, scripts de infraestrutura e testes.
• Manutenção: o sistema é atualizado mudando o modelo de alto nível e regenerando; o código gerado não é mexido à mão.

Você usa mais do que imagina: um schema.prisma que gera o banco e o cliente, ou um arquivo Terraform que define sua infraestrutura, são pequenos exemplos dessa filosofia. As plataformas low-code levam a ideia ao extremo.

Use quando você tem muitos sistemas parecidos ou domínios muito regulados, onde vale mais a pena gerar do que escrever. Cuidado com a rigidez: se as ferramentas de transformação não acompanham, o time acaba editando o código gerado e o modelo deixa de ser a verdade.

4. API-First e Contract-Driven Development (CDD): o contrato manda

É a aplicação mais prática do SDD em arquiteturas de serviços, microsserviços e integrações. A especificação é o contrato da API, escrito em um padrão aberto antes de programar: OpenAPI (Swagger) para REST, AsyncAPI para eventos ou Protobuf para gRPC.

openapi: 3.1.0
info:
  title: API de Agendamentos
  version: 1.0.0
paths:
  /reservas:
    post:
      summary: Criar uma reserva
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [clienteId, horario]
              properties:
                clienteId: { type: string }
                horario: { type: string, format: date-time }
      responses:
        "201": { description: Reserva criada }
        "409": { description: O horário já está ocupado }

Como ele percorre o ciclo de vida:

• Design: o contrato é acordado entre quem expõe a API e quem a consome.
• Desenvolvimento em paralelo: do contrato são gerados servidores mock, SDKs cliente e esqueletos de código, assim frontend e backend avançam ao mesmo tempo sem se esperar.
• Integração e implantação: os testes de contrato (Consumer-Driven Contracts com ferramentas como Pact) rodam no pipeline de CI/CD e bloqueiam qualquer mudança que quebre um consumidor.

Use quando vários times ou sistemas dependem da mesma API, como em integrações com WhatsApp, CRMs ou gateways de pagamento.

Comparativo: qual abordagem serve para você?

Eles não competem entre si: atacam riscos diferentes e se combinam bem.

Metodologia	Artefato central	Foco principal no SDLC	Resolve principalmente
BDD	Cenários de comportamento (.feature)	Alinhamento negócio-desenvolvimento-QA e validação	"Construímos algo que o cliente não pediu"
DDD	Modelo de domínio e linguagem ubíqua	Arquitetura, complexidade e negócio	"As regras do negócio estão espalhadas por todo o código"
MDE / MDA	Modelos de abstração (UML, DSL)	Geração automática e abstração	"Escrevemos à mão a mesma coisa repetidas vezes"
API-First / CDD	Contratos de API (OpenAPI, AsyncAPI, Protobuf)	Integração, microsserviços e paralelismo	"Cada implantação quebra uma integração"

Uma combinação frequente em projetos reais: DDD para dividir o sistema em contextos, API-First para definir como esses contextos conversam e BDD para validar cada funcionalidade do ponto de vista do usuário.

SDD com IA: um fluxo que você pode usar amanhã

Você não precisa adotar as quatro metodologias para começar. Este fluxo funciona com qualquer agente de IA e alguns arquivos Markdown no seu repositório; mais abaixo mostro como automatizá-lo com OpenSpec.

1. Especificar: escreva no spec.md o que a funcionalidade deve fazer e por quê, com critérios de aceitação. Aqui encaixam os cenários BDD e a linguagem ubíqua do DDD.
2. Planejar: peça ao agente um plan.md com a arquitetura, o stack e os contratos (seu OpenAPI mora aqui). Revise você mesmo antes de seguir.
3. Tarefas: divida o plano em um tasks.md com passos pequenos e verificáveis, um por commit.
4. Implementar: o agente executa uma tarefa por vez, lendo sempre a especificação e o plano como contexto.
5. Verificar: os testes derivados da especificação dizem se a tarefa está terminada, não a intuição.

A regra de ouro: quando um requisito muda, você edita a especificação e deixa a mudança fluir para baixo. Se você corrige direto no código, a especificação deixa de ser a verdade e você volta ao vibe coding.

Como fazer isso com OpenSpec

O OpenSpec é a ferramenta que recomendo para aplicar este fluxo. Em comparação com o Spec Kit, tem três vantagens práticas:

• Menos cerimônia: não te obriga a passar por fases rígidas; você itera sobre a proposta até que ela fique clara.
• Pensado para projetos existentes: cada mudança vive na sua própria pasta como um delta sobre as specs atuais, assim você não precisa documentar todo o sistema antes de começar.
• Não te prende a um agente: funciona com Claude Code, Cursor, Copilot, Amazon Q e dezenas mais.

Para instalar, você precisa de Node.js 20.19 ou superior:

npm install -g @fission-ai/openspec@latest
cd seu-projeto
openspec init

Depois, a partir do seu agente de IA, o ciclo tem três comandos:

1. /opsx:propose: cria uma pasta em openspec/changes/ com a proposta, as specs afetadas, o design e as tarefas. Você revisa e ajusta antes de seguir.
2. /opsx:apply: o agente implementa as tarefas seguindo a especificação.
3. /opsx:archive: a mudança concluída é arquivada e suas specs passam a fazer parte de openspec/specs/, a fonte da verdade do projeto.

Se você ainda não tem a ideia clara, o /opsx:explore deixa você pensar nos requisitos com o agente antes de criar a proposta. A sintaxe exata do comando pode variar conforme o assistente que você usa.

Erros comuns ao começar com SDD

• Especificar demais: uma spec de 40 páginas ninguém mantém. Comece com uma página por funcionalidade.
• Especificar o como em vez do o quê: "usar Redis" vai no plano, não na especificação.
• Spec que não se verifica: se nenhum teste ou contrato a valida, ela fica desatualizada em semanas.
• Mudar o código e esquecer a spec: é o erro que transforma SDD em documentação morta.

Conclusão

Spec-Driven Development não é burocracia: é escrever primeiro o que você vai ter que explicar de qualquer forma. BDD, DDD, MDE e API-First são quatro formas de fazer isso, cada uma com seu artefato e seu risco favorito. Com agentes de IA escrevendo cada vez mais código, a especificação virou sua melhor ferramenta para que o resultado seja o que você precisa.

Seu próximo passo: pegue a próxima funcionalidade do seu projeto, escreva o spec.md dela com três cenários Given/When/Then e entregue ao seu agente de IA antes de pedir uma única linha de código. Conta nos comentários como foi.

Perguntas frequentes

SDD é a mesma coisa que TDD? Não. O TDD parte de testes unitários escritos pelo desenvolvedor; o SDD parte de uma especificação de nível mais alto, da qual podem sair testes, código e documentação. O BDD é a ponte entre os dois.

Serve para times pequenos ou projetos pessoais? Sim. Um spec.md e um tasks.md bastam para que um agente de IA trabalhe com muito mais foco, mesmo que você seja um time de uma pessoa só.

Preciso usar as quatro metodologias? Não. Escolha conforme seu maior risco: mal-entendidos com o cliente (BDD), regras de negócio complexas (DDD), código repetitivo (MDE) ou integrações frágeis (API-First).

Quais ferramentas preciso para começar? Um editor, Markdown e seu agente de IA favorito. Se quiser estrutura pronta, comece com o OpenSpec: instala com um comando e funciona com o agente que você já usa.

Fontes

• OpenSpec (repositório)
• Kiro: documentação de Specs
• GitHub Spec Kit (repositório)
• Pact: Consumer-Driven Contract Testing