BLOG

Especificação Antes do Código: Como o Spec Driven Development Evita que a IA Adivinhe o Que Você Quis Dizer

Adriano Santos · 18 de agosto de 2026 · 12 min de leitura

Você já recebeu um card de sprint com três linhas de descrição, pediu para o agente de IA implementar a funcionalidade, e trinta minutos depois estava diante de um código que compilava, passava nos testes que você mesmo escreveu às pressas, mas resolvia o problema errado? O agente não teve culpa: ele fez exatamente o que foi pedido — o problema é que ninguém tinha definido, de fato, o que deveria ser pedido. A ambiguidade que um desenvolvedor sênior absorve intuitivamente, preenchendo lacunas com contexto de anos de domínio do sistema, vira terreno fértil para alucinação quando quem está do outro lado é um modelo de linguagem sem memória institucional.

Esse tipo de retrabalho — implementar, descobrir que a interpretação estava errada, jogar fora, reimplementar — não é exclusivo de IA. Sempre existiu em projetos com requisitos mal escritos. A diferença é que, com agentes gerando código em minutos, o custo de errar a especificação se multiplica pela velocidade de execução. Você erra mais rápido e em maior volume. É aqui que o Spec Driven Development (SDD) deixa de ser um exercício acadêmico de engenharia de requisitos e se torna uma prática de sobrevivência para quem trabalha com IA no fluxo diário de desenvolvimento.

Neste artigo, vamos além da definição de dicionário. O objetivo é mostrar como estruturar specs que funcionem como contrato executável entre você, seu time e os agentes de IA, com exemplos de como isso se materializa em ferramentas reais, os erros mais comuns ao adotar SDD e como diagnosticar quando uma spec está mal formulada antes que ela vire código ruim.

O que é Spec Driven Development, na prática

Spec Driven Development é uma abordagem em que a especificação — não o código — é o artefato central do processo de desenvolvimento. Isso não significa voltar ao modelo cascata dos anos 90, com documentos de 80 páginas que ninguém lê. Significa escrever specs estruturadas, versionadas junto ao código, e suficientemente precisas para que tanto um humano quanto um agente de IA consigam derivar a implementação sem precisar adivinhar.

A diferença central em relação ao desenvolvimento tradicional orientado a testes (TDD) ou a requisitos em ferramentas como Jira é o nível de formalidade e a proximidade com o código. Uma spec em SDD normalmente contém:

Contexto e objetivo: por que essa funcionalidade existe, qual problema de negócio resolve.
Comportamento esperado: descrito de forma testável, muitas vezes em formato Given-When-Then.
Contratos de interface: assinaturas de função, schemas de API, tipos de dados de entrada e saída.
Casos de borda explícitos: o que acontece quando a entrada é nula, vazia, duplicada, fora de faixa.
Critérios de aceite verificáveis: algo que um teste automatizado consiga confirmar.

O ponto crucial é que essa spec vive perto do código — em um arquivo Markdown no repositório, em um diretório specs/, ou embutida em ferramentas específicas — e é ela que alimenta tanto o desenvolvedor quanto o agente de IA no momento da implementação.

💡 Dica do Mestre: o termo Spec Driven Development ganhou tração recente também por conta de ferramentas como o Spec Kit do GitHub, que propõe um fluxo estruturado de especificação para uso com agentes de IA, e o conceito de “Specification by Example”, de Gojko Adzic, que já defendia specs executáveis muito antes da IA generativa existir. Vale a leitura do livro Specification by Example para entender as raízes dessa prática.

Por que isso importa mais agora, com IA no fluxo

Antes da IA generativa, uma spec ambígua gerava uma reunião de esclarecimento com o desenvolvedor. Ele perguntava, você respondia, e o contexto ficava registrado na cabeça dele — talvez em um comentário de código, talvez em nada. Um agente de IA não pergunta (a menos que você o configure para isso) e não guarda contexto entre sessões. Ele preenche a lacuna com a interpretação estatisticamente mais provável, que nem sempre é a correta para o seu domínio específico.

Isso cria um efeito perverso: o código gerado parece bom. Ele compila, segue convenções razoáveis, às vezes até tem testes. Mas resolve uma versão simplificada ou distorcida do problema real. A revisão humana, sob pressão de prazo, tende a aprovar código que “parece certo” — e aqui mora o risco de que specs frágeis se transformem em bugs de produção meses depois.

Um cenário concreto

Imagine a seguinte instrução, comum em times que usam Claude Code ou Cursor no dia a dia:


Implemente uma função de cálculo de desconto progressivo
para pedidos acima de R$ 500.

Implemente uma função de cálculo de desconto progressivo

para pedidos acima de R$ 500.

Um agente competente vai gerar algo funcional. Mas várias perguntas ficaram sem resposta: o desconto é sobre o valor total ou sobre o valor excedente a R$ 500? Existe teto para o desconto? O cálculo considera frete? Itens com desconto individual entram na soma? Sem uma spec, o agente escolhe — e a escolha dele pode não ser a sua.

Escrevendo uma spec que realmente guia a implementação

Vamos reescrever o exemplo anterior como uma spec estruturada, no formato que normalmente uso em projetos que integram IA ao fluxo de desenvolvimento:


## Spec: Cálculo de Desconto Progressivo

### Contexto
Pedidos com valor total (soma de itens, sem frete) acima de R$ 500
recebem desconto progressivo para incentivar ticket médio maior.

### Regras de negócio
- Desconto aplica-se apenas sobre o valor que EXCEDE R$ 500,
  não sobre o total do pedido.
- Faixas de desconto sobre o valor excedente:
  - Até R$ 500 excedentes: 5%
  - De R$ 500,01 a R$ 1500 excedentes: 10%
  - Acima de R$ 1500 excedentes: 15%
- Frete NÃO entra no cálculo do valor elegível a desconto.
- Itens já com desconto individual (promoção) SÃO somados
  normalmente ao valor total do pedido.
- Desconto máximo por pedido: R$ 300 (teto absoluto).

### Contrato de interface
```
function calcularDescontoProgressivo(valorTotalItens: number): {
  valorDesconto: number;
  percentualEfetivo: number;
}
```

### Casos de teste obrigatórios
| Entrada (valorTotalItens) | valorDesconto esperado |
|---|---|
| 300  | 0 |
| 500  | 0 |
| 700  | 10 (5% de 200) |
| 1200 | 45 (5% de 500 + 10% de 200) |
| 5000 | 300 (teto atingido) |

### Casos de borda
- Valor negativo: lançar erro `ValorInvalidoError`.
- Valor zero: retornar desconto zero, sem erro.

## Spec: Cálculo de Desconto Progressivo

### Contexto

Pedidos com valor total (soma de itens, sem frete) acima de R$ 500

recebem desconto progressivo para incentivar ticket médio maior.

### Regras de negócio

- Desconto aplica-se apenas sobre o valor que EXCEDE R$ 500,

não sobre o total do pedido.

- Faixas de desconto sobre o valor excedente:

- Até R$ 500 excedentes: 5%

- De R$ 500,01 a R$ 1500 excedentes: 10%

- Acima de R$ 1500 excedentes: 15%

- Frete NÃO entra no cálculo do valor elegível a desconto.

- Itens já com desconto individual (promoção) SÃO somados

normalmente ao valor total do pedido.

- Desconto máximo por pedido: R$ 300 (teto absoluto).

### Contrato de interface

```

function calcularDescontoProgressivo(valorTotalItens: number): {

valorDesconto: number;

percentualEfetivo: number;

}

```

### Casos de teste obrigatórios

| Entrada (valorTotalItens) | valorDesconto esperado |

|---|---|

| 300 | 0 |

| 500 | 0 |

| 700 | 10 (5% de 200) |

| 1200 | 45 (5% de 500 + 10% de 200) |

| 5000 | 300 (teto atingido) |

### Casos de borda

- Valor negativo: lançar erro `ValorInvalidoError`.

- Valor zero: retornar desconto zero, sem erro.

Note que essa spec não é código, mas já é executável em espírito: qualquer pessoa — ou agente — consegue derivar a implementação e os testes unitários diretamente dela. Não sobra espaço para interpretação livre nos pontos que importam.

Passando a spec para o agente de IA

Com a spec pronta, o prompt para o agente muda de qualidade. Em vez de descrever a intenção vagamente, você referencia o arquivo da spec e pede a implementação com base nela:


Implemente a função descrita em specs/desconto-progressivo.md.
Gere também os testes unitários cobrindo exatamente a tabela
de casos de teste da spec, usando Jest.
Não adicione regras de negócio que não estejam explicitamente
na spec — se algo parecer ambíguo, sinalize antes de implementar.

Implemente a função descrita em specs/desconto-progressivo.md.

Gere também os testes unitários cobrindo exatamente a tabela

de casos de teste da spec, usando Jest.

Não adicione regras de negócio que não estejam explicitamente

na spec — se algo parecer ambíguo, sinalize antes de implementar.

Essa última instrução — pedir que o agente sinalize ambiguidade em vez de resolver sozinho — é uma das práticas mais valiosas do SDD aplicado a IA. Ela transforma o agente de “adivinhador silencioso” em colaborador que expõe as lacunas da spec antes de gerar código sobre uma base incerta.

Onde o Spec Driven Development se encaixa no fluxo real

SDD não substitui TDD, Domain-Driven Design ou revisão de código — ele é complementar e, na prática, potencializa cada um desses. A sequência que costuma funcionar bem em times que já adotaram IA como parte do fluxo é:

Escrever a spec a partir da conversa com stakeholder ou análise do problema técnico.
Revisar a spec com o time (ou com você mesmo, em projetos solo) antes de qualquer linha de código — é muito mais barato corrigir uma spec do que um PR inteiro.
Gerar testes a partir da spec, manualmente ou com IA, antes da implementação.
Implementar, com ou sem IA, tendo a spec e os testes como critério de sucesso objetivo.
Versionar a spec junto ao código, para que mudanças futuras de comportamento exijam atualização explícita da spec — evitando o efeito “documentação desatualizada” que discutimos em outros contextos de pipelines de docs.

Exemplo com múltiplas linguagens

A vantagem do SDD é que a spec é agnóstica de linguagem. A mesma spec de desconto progressivo pode gerar implementações em contextos completamente diferentes sem perder consistência de comportamento. Em um backend Python com FastAPI:


def calcular_desconto_progressivo(valor_total_itens: float) -&gt; dict:
    if valor_total_itens  0:
        primeira_faixa = min(excedente, 500)
        desconto += primeira_faixa * 0.05

        segunda_faixa = min(max(excedente - 500, 0), 1000)
        desconto += segunda_faixa * 0.10

        terceira_faixa = max(excedente - 1500, 0)
        desconto += terceira_faixa * 0.15

    desconto_final = min(desconto, 300.0)
    percentual_efetivo = (
        (desconto_final / valor_total_itens) * 100
        if valor_total_itens &gt; 0 else 0
    )

    return {
        "valor_desconto": round(desconto_final, 2),
        "percentual_efetivo": round(percentual_efetivo, 2),
    }

def calcular_desconto_progressivo(valor_total_itens: float) -> dict:

if valor_total_itens 0:

primeira_faixa = min(excedente, 500)

desconto += primeira_faixa * 0.05

segunda_faixa = min(max(excedente - 500, 0), 1000)

desconto += segunda_faixa * 0.10

terceira_faixa = max(excedente - 1500, 0)

desconto += terceira_faixa * 0.15

desconto_final = min(desconto, 300.0)

percentual_efetivo = (

(desconto_final / valor_total_itens) * 100

if valor_total_itens > 0 else 0

)

return {

"valor_desconto": round(desconto_final, 2),

"percentual_efetivo": round(percentual_efetivo, 2),

}

E em Delphi, para quem mantém sistemas corporativos legados com regras de negócio semelhantes:


function CalcularDescontoProgressivo(ValorTotalItens: Currency): TDescontoResultado;
var
  Excedente, Desconto, PrimeiraFaixa, SegundaFaixa, TerceiraFaixa: Currency;
begin
  if ValorTotalItens  0 then
  begin
    PrimeiraFaixa := Min(Excedente, 500);
    Desconto := Desconto + (PrimeiraFaixa * 0.05);

    SegundaFaixa := Min(Max(Excedente - 500, 0), 1000);
    Desconto := Desconto + (SegundaFaixa * 0.10);

    TerceiraFaixa := Max(Excedente - 1500, 0);
    Desconto := Desconto + (TerceiraFaixa * 0.15);
  end;

  Result.ValorDesconto := Min(Desconto, 300);
  if ValorTotalItens &gt; 0 then
    Result.PercentualEfetivo := (Result.ValorDesconto / ValorTotalItens) * 100
  else
    Result.PercentualEfetivo := 0;
end;

function CalcularDescontoProgressivo(ValorTotalItens: Currency): TDescontoResultado;

var

Excedente, Desconto, PrimeiraFaixa, SegundaFaixa, TerceiraFaixa: Currency;

begin

if ValorTotalItens 0 then

begin

PrimeiraFaixa := Min(Excedente, 500);

Desconto := Desconto + (PrimeiraFaixa * 0.05);

SegundaFaixa := Min(Max(Excedente - 500, 0), 1000);

Desconto := Desconto + (SegundaFaixa * 0.10);

TerceiraFaixa := Max(Excedente - 1500, 0);

Desconto := Desconto + (TerceiraFaixa * 0.15);

end;

Result.ValorDesconto := Min(Desconto, 300);

if ValorTotalItens > 0 then

Result.PercentualEfetivo := (Result.ValorDesconto / ValorTotalItens) * 100

else

Result.PercentualEfetivo := 0;

end;

A spec permanece a mesma; apenas a sintaxe muda. Isso é particularmente valioso em times poliglotas ou em migrações de stack, onde a lógica de negócio precisa ser preservada com fidelidade entre implementações diferentes.

Erros comuns ao adotar Spec Driven Development

1. Specs longas demais, que ninguém mantém atualizadas

O erro mais frequente é achar que “mais detalhe é sempre melhor”. Specs de dez páginas para uma função de cálculo de desconto são tão inúteis quanto a ausência de spec — ninguém as lê, ninguém as atualiza, e elas se tornam ficção corporativa. A regra prática: a spec deve ser exaustiva nos pontos ambíguos e minimalista no resto. Se o comportamento é óbvio, não precisa de spec — precisa de código limpo e um teste.

2. Tratar a spec como imutável

Specs não são pedra. Durante a implementação, é comum descobrir que um caso de borda não foi previsto. O fluxo saudável é atualizar a spec no mesmo commit que ajusta o código — nunca deixar o código divergir silenciosamente do que está documentado. Isso é o mesmo princípio de “documentação viva” aplicado à camada de requisitos.

3. Confiar cegamente na implementação do agente sem validar contra a spec

Ter uma spec não elimina a necessidade de revisão — ela apenas torna a revisão objetiva. Ao revisar um PR gerado com apoio de IA, o checklist deveria ser: cada regra de negócio da spec tem um teste correspondente? Os casos de borda listados foram tratados? Existe alguma regra implementada que não está na spec (sinal de que o agente “inventou” comportamento)?

4. Escrever specs sem critérios verificáveis

Frases como “o sistema deve ser rápido” ou “a interface deve ser intuitiva” não são specs — são intenções vagas travestidas de requisito. Uma spec de qualidade sempre permite a pergunta: “como eu comprovo, com um teste automatizado ou uma métrica, que isso foi atendido?”. Se a resposta não existir, a spec precisa ser reescrita.

💡 Dica do Mestre: a linguagem Gherkin (Given-When-Then), popularizada pelo Cucumber, é uma ferramenta útil para forçar clareza em specs comportamentais, mesmo que você não use BDD como framework de testes. O formato obriga a explicitar pré-condição, ação e resultado esperado — exatamente o que falta na maioria dos requisitos escritos às pressas.

Como depurar uma spec malformulada antes que vire código ruim

Um sinal claro de que a spec está fraca é quando você pede para um agente de IA implementá-la e ele começa a fazer perguntas — ou, pior, começa a preencher lacunas silenciosamente com suposições razoáveis, mas potencialmente erradas. Algumas perguntas que ajudam a testar a robustez de uma spec antes de liberá-la para implementação:

Um desenvolvedor que nunca viu esse sistema conseguiria implementar isso sem me perguntar nada?
Todos os valores numéricos (limites, percentuais, tetos) estão explícitos, e não implícitos em “regras de negócio conhecidas”?
Os casos de borda (nulo, vazio, negativo, zero, limite exato de faixa) foram listados individualmente?
Existe pelo menos um exemplo concreto de entrada e saída para cada regra?

Se a resposta para qualquer uma dessas perguntas for “não”, a spec ainda não está pronta para virar prompt de IA nem para virar código escrito à mão.

Ferramentas que apoiam Spec Driven Development hoje

O ecossistema ao redor de SDD amadureceu rapidamente com a popularização de agentes de IA no desenvolvimento. Vale conhecer:

GitHub Spec Kit: ferramenta open source que estrutura o fluxo de criação de specs para uso com agentes como Claude Code, GitHub Copilot e outros, incluindo templates de spec, plano de implementação e tarefas derivadas.
Claude Code: permite referenciar arquivos de spec diretamente no diretório do projeto e usá-los como contexto persistente para múltiplas sessões de trabalho.
OpenAPI Specification: para APIs, a especificação OpenAPI já é, na prática, uma forma madura de SDD aplicada a contratos de interface — vale usá-la como spec viva mesmo fora de projetos que adotam SDD formalmente.

Junte-se à Comunidade Dev’s AI

Se você quer discutir Spec Driven Development, trocar templates de specs que funcionam na prática e ver como outros desenvolvedores estão integrando essa disciplina ao fluxo com Claude Code, Cursor e outros agentes, venha para a Comunidade Dev’s AI. É um espaço para quem já programa e quer ir além do básico na integração entre desenvolvimento de software e inteligência artificial — sem enrolação, com exemplos reais de projetos em produção.

Conclusão

Spec Driven Development não é burocracia disfarçada nem retorno a processos pesados do passado. É a resposta natural a um problema muito concreto: agentes de IA são rápidos, mas não são telepáticos. Eles preenchem lacunas com a interpretação mais provável, e essa interpretação nem sempre coincide com a sua intenção real. Investir tempo em escrever specs precisas, testáveis e versionadas junto ao código não é overhead — é a forma mais eficiente de transformar velocidade de geração de código em velocidade de entrega de valor correto.

A prática pede disciplina, mas essa disciplina se paga rapidamente: menos ciclos de retrabalho, revisões de código mais objetivas, e agentes de IA que finalmente colaboram com precisão em vez de adivinhar. Da próxima vez que abrir um prompt para pedir uma implementação, pergunte-se antes: existe uma spec por trás disso, ou você está prestes a descobrir, código pronto, que pediu a coisa errada?