Voc\u00ea j\u00e1 recebeu um card de sprint com tr\u00eas linhas de descri\u00e7\u00e3o, pediu para o agente de IA implementar a funcionalidade, e trinta minutos depois estava diante de um c\u00f3digo que compilava, passava nos testes que voc\u00ea mesmo escreveu \u00e0s pressas, mas resolvia o problema errado? O agente n\u00e3o teve culpa: ele fez exatamente o que foi pedido \u2014 o problema \u00e9 que ningu\u00e9m tinha definido, de fato, o que deveria ser pedido. A ambiguidade que um desenvolvedor s\u00eanior absorve intuitivamente, preenchendo lacunas com contexto de anos de dom\u00ednio do sistema, vira terreno f\u00e9rtil para alucina\u00e7\u00e3o quando quem est\u00e1 do outro lado \u00e9 um modelo de linguagem sem mem\u00f3ria institucional.<\/p>\n
Esse tipo de retrabalho \u2014 implementar, descobrir que a interpreta\u00e7\u00e3o estava errada, jogar fora, reimplementar \u2014 n\u00e3o \u00e9 exclusivo de IA. Sempre existiu em projetos com requisitos mal escritos. A diferen\u00e7a \u00e9 que, com agentes gerando c\u00f3digo em minutos, o custo de errar a especifica\u00e7\u00e3o se multiplica pela velocidade de execu\u00e7\u00e3o. Voc\u00ea erra mais r\u00e1pido e em maior volume. \u00c9 aqui que o Spec Driven Development<\/strong> (SDD) deixa de ser um exerc\u00edcio acad\u00eamico de engenharia de requisitos e se torna uma pr\u00e1tica de sobreviv\u00eancia para quem trabalha com IA no fluxo di\u00e1rio de desenvolvimento.<\/p>\n Neste artigo, vamos al\u00e9m da defini\u00e7\u00e3o de dicion\u00e1rio. O objetivo \u00e9 mostrar como estruturar specs que funcionem como contrato execut\u00e1vel entre voc\u00ea, 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\u00e1 mal formulada antes que ela vire c\u00f3digo ruim.<\/p>\n Spec Driven Development \u00e9 uma abordagem em que a especifica\u00e7\u00e3o \u2014 n\u00e3o o c\u00f3digo \u2014 \u00e9 o artefato central do processo de desenvolvimento. Isso n\u00e3o significa voltar ao modelo cascata dos anos 90, com documentos de 80 p\u00e1ginas que ningu\u00e9m l\u00ea. Significa escrever specs estruturadas, versionadas junto ao c\u00f3digo, e suficientemente precisas para que tanto um humano quanto um agente de IA consigam derivar a implementa\u00e7\u00e3o sem precisar adivinhar.<\/p>\n A diferen\u00e7a central em rela\u00e7\u00e3o ao desenvolvimento tradicional orientado a testes (TDD) ou a requisitos em ferramentas como Jira \u00e9 o n\u00edvel de formalidade e a proximidade com o c\u00f3digo. Uma spec em SDD normalmente cont\u00e9m:<\/p>\n O ponto crucial \u00e9 que essa spec vive perto do c\u00f3digo \u2014 em um arquivo Markdown no reposit\u00f3rio, em um diret\u00f3rio \ud83d\udca1 Dica do Mestre:<\/strong> o termo Spec Driven Development ganhou tra\u00e7\u00e3o recente tamb\u00e9m por conta de ferramentas como o Spec Kit do GitHub<\/a>, que prop\u00f5e um fluxo estruturado de especifica\u00e7\u00e3o para uso com agentes de IA, e o conceito de “Specification by Example”, de Gojko Adzic, que j\u00e1 defendia specs execut\u00e1veis muito antes da IA generativa existir. Vale a leitura do livro Specification by Example<\/em> para entender as ra\u00edzes dessa pr\u00e1tica.<\/p><\/blockquote>\n Antes da IA generativa, uma spec amb\u00edgua gerava uma reuni\u00e3o de esclarecimento com o desenvolvedor. Ele perguntava, voc\u00ea respondia, e o contexto ficava registrado na cabe\u00e7a dele \u2014 talvez em um coment\u00e1rio de c\u00f3digo, talvez em nada. Um agente de IA n\u00e3o pergunta (a menos que voc\u00ea o configure para isso) e n\u00e3o guarda contexto entre sess\u00f5es. Ele preenche a lacuna com a interpreta\u00e7\u00e3o estatisticamente mais prov\u00e1vel, que nem sempre \u00e9 a correta para o seu dom\u00ednio espec\u00edfico.<\/p>\n Isso cria um efeito perverso: o c\u00f3digo gerado parece bom. Ele compila, segue conven\u00e7\u00f5es razo\u00e1veis, \u00e0s vezes at\u00e9 tem testes. Mas resolve uma vers\u00e3o simplificada ou distorcida do problema real. A revis\u00e3o humana, sob press\u00e3o de prazo, tende a aprovar c\u00f3digo que “parece certo” \u2014 e aqui mora o risco de que specs fr\u00e1geis se transformem em bugs de produ\u00e7\u00e3o meses depois.<\/p>\n Imagine a seguinte instru\u00e7\u00e3o, comum em times que usam Claude Code ou Cursor no dia a dia:<\/p>\n Um agente competente vai gerar algo funcional. Mas v\u00e1rias perguntas ficaram sem resposta: o desconto \u00e9 sobre o valor total ou sobre o valor excedente a R$ 500? Existe teto para o desconto? O c\u00e1lculo considera frete? Itens com desconto individual entram na soma? Sem uma spec, o agente escolhe \u2014 e a escolha dele pode n\u00e3o ser a sua.<\/p>\n Vamos reescrever o exemplo anterior como uma spec estruturada, no formato que normalmente uso em projetos que integram IA ao fluxo de desenvolvimento:<\/p>\n Note que essa spec n\u00e3o \u00e9 c\u00f3digo, mas j\u00e1 \u00e9 execut\u00e1vel em esp\u00edrito: qualquer pessoa \u2014 ou agente \u2014 consegue derivar a implementa\u00e7\u00e3o e os testes unit\u00e1rios diretamente dela. N\u00e3o sobra espa\u00e7o para interpreta\u00e7\u00e3o livre nos pontos que importam.<\/p>\n Com a spec pronta, o prompt para o agente muda de qualidade. Em vez de descrever a inten\u00e7\u00e3o vagamente, voc\u00ea referencia o arquivo da spec e pede a implementa\u00e7\u00e3o com base nela:<\/p>\n Essa \u00faltima instru\u00e7\u00e3o \u2014 pedir que o agente sinalize ambiguidade em vez de resolver sozinho \u2014 \u00e9 uma das pr\u00e1ticas mais valiosas do SDD aplicado a IA. Ela transforma o agente de “adivinhador silencioso” em colaborador que exp\u00f5e as lacunas da spec antes de gerar c\u00f3digo sobre uma base incerta.<\/p>\n SDD n\u00e3o substitui TDD, Domain-Driven Design ou revis\u00e3o de c\u00f3digo \u2014 ele \u00e9 complementar e, na pr\u00e1tica, potencializa cada um desses. A sequ\u00eancia que costuma funcionar bem em times que j\u00e1 adotaram IA como parte do fluxo \u00e9:<\/p>\n A vantagem do SDD \u00e9 que a spec \u00e9 agn\u00f3stica de linguagem. A mesma spec de desconto progressivo pode gerar implementa\u00e7\u00f5es em contextos completamente diferentes sem perder consist\u00eancia de comportamento. Em um backend Python com FastAPI:<\/p>\n E em Delphi, para quem mant\u00e9m sistemas corporativos legados com regras de neg\u00f3cio semelhantes:<\/p>\n A spec permanece a mesma; apenas a sintaxe muda. Isso \u00e9 particularmente valioso em times poliglotas ou em migra\u00e7\u00f5es de stack, onde a l\u00f3gica de neg\u00f3cio precisa ser preservada com fidelidade entre implementa\u00e7\u00f5es diferentes.<\/p>\n O erro mais frequente \u00e9 achar que “mais detalhe \u00e9 sempre melhor”. Specs de dez p\u00e1ginas para uma fun\u00e7\u00e3o de c\u00e1lculo de desconto s\u00e3o t\u00e3o in\u00fateis quanto a aus\u00eancia de spec \u2014 ningu\u00e9m as l\u00ea, ningu\u00e9m as atualiza, e elas se tornam fic\u00e7\u00e3o corporativa. A regra pr\u00e1tica: a spec deve ser exaustiva nos pontos amb\u00edguos e minimalista no resto. Se o comportamento \u00e9 \u00f3bvio, n\u00e3o precisa de spec \u2014 precisa de c\u00f3digo limpo e um teste.<\/p>\n Specs n\u00e3o s\u00e3o pedra. Durante a implementa\u00e7\u00e3o, \u00e9 comum descobrir que um caso de borda n\u00e3o foi previsto. O fluxo saud\u00e1vel \u00e9 atualizar a spec no mesmo commit que ajusta o c\u00f3digo \u2014 nunca deixar o c\u00f3digo divergir silenciosamente do que est\u00e1 documentado. Isso \u00e9 o mesmo princ\u00edpio de “documenta\u00e7\u00e3o viva” aplicado \u00e0 camada de requisitos.<\/p>\n Ter uma spec n\u00e3o elimina a necessidade de revis\u00e3o \u2014 ela apenas torna a revis\u00e3o objetiva. Ao revisar um PR gerado com apoio de IA, o checklist deveria ser: cada regra de neg\u00f3cio da spec tem um teste correspondente? Os casos de borda listados foram tratados? Existe alguma regra implementada que n\u00e3o est\u00e1 na spec (sinal de que o agente “inventou” comportamento)?<\/p>\n Frases como “o sistema deve ser r\u00e1pido” ou “a interface deve ser intuitiva” n\u00e3o s\u00e3o specs \u2014 s\u00e3o inten\u00e7\u00f5es vagas travestidas de requisito. Uma spec de qualidade sempre permite a pergunta: “como eu comprovo, com um teste automatizado ou uma m\u00e9trica, que isso foi atendido?”. Se a resposta n\u00e3o existir, a spec precisa ser reescrita.<\/p>\n \ud83d\udca1 Dica do Mestre:<\/strong> a linguagem Gherkin (Given-When-Then), popularizada pelo Cucumber<\/a>, \u00e9 uma ferramenta \u00fatil para for\u00e7ar clareza em specs comportamentais, mesmo que voc\u00ea n\u00e3o use BDD como framework de testes. O formato obriga a explicitar pr\u00e9-condi\u00e7\u00e3o, a\u00e7\u00e3o e resultado esperado \u2014 exatamente o que falta na maioria dos requisitos escritos \u00e0s pressas.<\/p><\/blockquote>\n Um sinal claro de que a spec est\u00e1 fraca \u00e9 quando voc\u00ea pede para um agente de IA implement\u00e1-la e ele come\u00e7a a fazer perguntas \u2014 ou, pior, come\u00e7a a preencher lacunas silenciosamente com suposi\u00e7\u00f5es razo\u00e1veis, mas potencialmente erradas. Algumas perguntas que ajudam a testar a robustez de uma spec antes de liber\u00e1-la para implementa\u00e7\u00e3o:<\/p>\n Se a resposta para qualquer uma dessas perguntas for “n\u00e3o”, a spec ainda n\u00e3o est\u00e1 pronta para virar prompt de IA nem para virar c\u00f3digo escrito \u00e0 m\u00e3o.<\/p>\n O ecossistema ao redor de SDD amadureceu rapidamente com a populariza\u00e7\u00e3o de agentes de IA no desenvolvimento. Vale conhecer:<\/p>\nO que \u00e9 Spec Driven Development, na pr\u00e1tica<\/h2>\n
\n
specs\/<\/code>, ou embutida em ferramentas espec\u00edficas \u2014 e \u00e9 ela que alimenta tanto o desenvolvedor quanto o agente de IA no momento da implementa\u00e7\u00e3o.<\/p>\nPor que isso importa mais agora, com IA no fluxo<\/h2>\n
Um cen\u00e1rio concreto<\/h3>\n
Implemente uma fun\u00e7\u00e3o de c\u00e1lculo de desconto progressivo\npara pedidos acima de R$ 500.<\/code><\/pre>\nEscrevendo uma spec que realmente guia a implementa\u00e7\u00e3o<\/h2>\n
## Spec: C\u00e1lculo de Desconto Progressivo\n\n### Contexto\nPedidos com valor total (soma de itens, sem frete) acima de R$ 500\nrecebem desconto progressivo para incentivar ticket m\u00e9dio maior.\n\n### Regras de neg\u00f3cio\n- Desconto aplica-se apenas sobre o valor que EXCEDE R$ 500,\n n\u00e3o sobre o total do pedido.\n- Faixas de desconto sobre o valor excedente:\n - At\u00e9 R$ 500 excedentes: 5%\n - De R$ 500,01 a R$ 1500 excedentes: 10%\n - Acima de R$ 1500 excedentes: 15%\n- Frete N\u00c3O entra no c\u00e1lculo do valor eleg\u00edvel a desconto.\n- Itens j\u00e1 com desconto individual (promo\u00e7\u00e3o) S\u00c3O somados\n normalmente ao valor total do pedido.\n- Desconto m\u00e1ximo por pedido: R$ 300 (teto absoluto).\n\n### Contrato de interface\n```\nfunction calcularDescontoProgressivo(valorTotalItens: number): {\n valorDesconto: number;\n percentualEfetivo: number;\n}\n```\n\n### Casos de teste obrigat\u00f3rios\n| Entrada (valorTotalItens) | valorDesconto esperado |\n|---|---|\n| 300 | 0 |\n| 500 | 0 |\n| 700 | 10 (5% de 200) |\n| 1200 | 45 (5% de 500 + 10% de 200) |\n| 5000 | 300 (teto atingido) |\n\n### Casos de borda\n- Valor negativo: lan\u00e7ar erro `ValorInvalidoError`.\n- Valor zero: retornar desconto zero, sem erro.\n<\/code><\/pre>\nPassando a spec para o agente de IA<\/h3>\n
Implemente a fun\u00e7\u00e3o descrita em specs\/desconto-progressivo.md.\nGere tamb\u00e9m os testes unit\u00e1rios cobrindo exatamente a tabela\nde casos de teste da spec, usando Jest.\nN\u00e3o adicione regras de neg\u00f3cio que n\u00e3o estejam explicitamente\nna spec \u2014 se algo parecer amb\u00edguo, sinalize antes de implementar.<\/code><\/pre>\nOnde o Spec Driven Development se encaixa no fluxo real<\/h2>\n
\n
Exemplo com m\u00faltiplas linguagens<\/h3>\n
def calcular_desconto_progressivo(valor_total_itens: float) -> dict:\n if valor_total_itens 0:\n primeira_faixa = min(excedente, 500)\n desconto += primeira_faixa * 0.05\n\n segunda_faixa = min(max(excedente - 500, 0), 1000)\n desconto += segunda_faixa * 0.10\n\n terceira_faixa = max(excedente - 1500, 0)\n desconto += terceira_faixa * 0.15\n\n desconto_final = min(desconto, 300.0)\n percentual_efetivo = (\n (desconto_final \/ valor_total_itens) * 100\n if valor_total_itens > 0 else 0\n )\n\n return {\n \"valor_desconto\": round(desconto_final, 2),\n \"percentual_efetivo\": round(percentual_efetivo, 2),\n }<\/code><\/pre>\nfunction CalcularDescontoProgressivo(ValorTotalItens: Currency): TDescontoResultado;\nvar\n Excedente, Desconto, PrimeiraFaixa, SegundaFaixa, TerceiraFaixa: Currency;\nbegin\n if ValorTotalItens 0 then\n begin\n PrimeiraFaixa := Min(Excedente, 500);\n Desconto := Desconto + (PrimeiraFaixa * 0.05);\n\n SegundaFaixa := Min(Max(Excedente - 500, 0), 1000);\n Desconto := Desconto + (SegundaFaixa * 0.10);\n\n TerceiraFaixa := Max(Excedente - 1500, 0);\n Desconto := Desconto + (TerceiraFaixa * 0.15);\n end;\n\n Result.ValorDesconto := Min(Desconto, 300);\n if ValorTotalItens > 0 then\n Result.PercentualEfetivo := (Result.ValorDesconto \/ ValorTotalItens) * 100\n else\n Result.PercentualEfetivo := 0;\nend;<\/code><\/pre>\nErros comuns ao adotar Spec Driven Development<\/h2>\n
1. Specs longas demais, que ningu\u00e9m mant\u00e9m atualizadas<\/h3>\n
2. Tratar a spec como imut\u00e1vel<\/h3>\n
3. Confiar cegamente na implementa\u00e7\u00e3o do agente sem validar contra a spec<\/h3>\n
4. Escrever specs sem crit\u00e9rios verific\u00e1veis<\/h3>\n
Como depurar uma spec malformulada antes que vire c\u00f3digo ruim<\/h2>\n
\n
Ferramentas que apoiam Spec Driven Development hoje<\/h2>\n
\n
Junte-se \u00e0 Comunidade Dev’s AI<\/h2>\n