Spec-Driven Development (SDD) é a prática de tratar a especificação de um software como o artefato central do ciclo de desenvolvimento, não como documento descartável que vira PowerPoint e morre. Em 2026, com agentes de IA escrevendo cada vez mais código, SDD virou a forma mais sã de garantir que o que é gerado corresponde ao que foi pedido, com rastreabilidade e validação automatizada.
Este guia explica o que é SDD, por que ele ressurgiu na era da IA, qual a diferença para BDD e TDD, e como adotá-lo sem cair em burocracia.
O que mudou para SDD virar tema central
Por décadas, "spec" foi sinônimo de documento Word esquecido no SharePoint. O código era a fonte da verdade. Comentários e testes documentavam intenção quando tinham sorte. SDD inverte: a spec é a fonte da verdade, descrita em formato legível por humano e máquina (Markdown estruturado, YAML, JSON Schema, OpenAPI, Gherkin). O código é gerado, validado e mantido a partir dela.
O gatilho foi a chegada dos agentes de codificação (Claude Code, Cursor, Copilot Workspace, Aider, ferramentas internas com Claude Agent SDK). Esses agentes funcionam muito melhor quando recebem uma spec clara, com critérios de aceitação, regras de negócio e exemplos, em vez de pedidos vagos como "implementa esse endpoint". A consequência prática: equipes que escrevem boas specs colhem código melhor, mais rápido e com menos retrabalho.
Anatomia de uma boa spec
Uma spec útil tem cinco seções. 1. Contexto e objetivo: qual problema resolve, para quem, por que agora. 2. Comportamento esperado: descrição do fluxo principal e dos casos de borda. 3. Contratos: schema da entrada, schema da saída, formato de erro. 4. Critérios de aceitação: lista de assertivas verificáveis ("dado X, quando Y, então Z"). 5. Não-objetivos: o que explicitamente está fora do escopo, para não virar projeto sem fim.
Uma spec ruim é genérica, sem critério de aceitação, sem schema, e cabe em qualquer interpretação. Uma boa spec é específica, com schema rigoroso, exemplos concretos e claro o que não deve fazer.
SDD vs TDD vs BDD
As três disciplinas compartilham o mesmo gene: escrever a intenção antes do código. As diferenças importam. TDD (Test-Driven Development): você escreve o teste antes da implementação. Foco em verificação granular. Sofre quando o teste é frágil ou quando a intenção real não cabe em "esse retorno é igual a esse". BDD (Behavior-Driven Development): você escreve cenários em linguagem natural estruturada (Gherkin). Foco em comportamento legível por produto. Sofre quando os cenários viram macarrão de step definitions. SDD: você escreve a spec completa, incluindo contratos, critérios e exemplos, antes de qualquer código. Foco em ser fonte canônica reutilizável por humanos e agentes de IA.
Na prática, SDD contém BDD (os cenários viram parte dos critérios de aceitação) e TDD nasce naturalmente dela (cada critério vira pelo menos um teste).
SDD com agentes de IA
O ganho mais visível de SDD aparece quando você pede para um agente implementar uma feature. Com spec rica, o agente gera código que passa nos critérios de aceitação de primeira na maioria dos casos. Sem spec, o agente preenche lacunas com suposições, e você descobre as suposições erradas depois.
Um fluxo maduro tem três passos. Primeiro, humano escreve ou refina a spec com auxílio do agente (o agente faz perguntas, propõe cenários esquecidos, sugere edge cases). Segundo, o agente implementa a feature a partir da spec, com testes derivados dos critérios. Terceiro, humano revisa spec, código e testes lado a lado, com diffs comparáveis.
Ferramentas e formatos populares em 2026
O ecossistema cresceu. OpenAPI / AsyncAPI: padrão de fato para APIs REST e event-driven. JSON Schema: para validação de payloads e configuração. Gherkin (Cucumber): para cenários comportamentais. Markdown estruturado com frontmatter: para specs de feature legíveis por agentes. Spec Kit do GitHub e iniciativas similares: para padronizar o formato de spec consumida por copilots. Pydantic / Zod / TypeBox: para gerar runtime validators a partir de schemas declarativos.
Anti-padrões de SDD
Quatro armadilhas mais comuns. 1. Spec gigantesca e desatualizada: spec sem dono e sem ciclo de revisão vira folclore. Trate spec como código: tem PR, tem review, tem versionamento. 2. Spec genérica sem critério de aceitação verificável. Se não dá pra escrever um teste a partir dela, não é spec. 3. Spec só de produto, sem contratos técnicos. Use a spec para alinhar produto, engenharia e QA, não só uma das partes. 4. Spec depois do código: documentação retroativa não tem o mesmo valor. SDD funciona porque a spec vem antes.
Quando SDD não vale a pena
SDD não é gratuito. Para um script descartável, um one-off de migração, ou um spike exploratório, escrever spec é overhead que não retorna. SDD brilha em código que vai durar, ser mantido por mais de uma pessoa, ser estendido com agentes, e que tem critérios de qualidade não negociáveis (APIs públicas, módulos críticos, integrações com sistemas externos).
SDD na Steply
Na Steply, SDD é prática padrão em todos os squads que constroem produto com IA. Toda feature começa com uma spec curta, escrita junto com o cliente, contendo objetivo, contratos, critérios e não-objetivos. Essa spec vira o briefing do agente, vira a base dos testes, vira o changelog e vira o material de revisão. O efeito composto é entrega mais rápida com menos retrabalho, menos discussão de "não era isso que eu pedi", e código mais alinhado ao que o negócio precisa.
