This post is not yet available in English. Showing Portuguese version.

O que é SDD

Spec-Driven Development (SDD) é a prática de escrever uma especificação clara e detalhada antes de escrever qualquer linha de código. Não é um conceito novo — engenheiros experientes sempre souberam que entender o problema antes de resolver é metade do caminho. O que mudou é que agora temos IA disponível em cada etapa do processo.

A ideia central é simples: se você não consegue escrever uma spec do que quer construir, você não entende o problema o suficiente para codificar. A IA amplifica isso — ela é excelente em transformar ideias vagas em especificações estruturadas, mas só funciona bem quando você sabe o que quer.

SDD com IA não é sobre deixar a IA pensar por você. É sobre usar a IA para externalizar e estruturar seu pensamento mais rápido.

Como a IA se encaixa

Ferramentas como Claude, ChatGPT e GitHub Copilot têm capacidades diferentes mas complementares:

  • Claude e ChatGPT são melhores para raciocínio, geração de specs, planejamento arquitetural e revisão de código
  • Cursor e Claude Code vivem dentro do editor e são melhores para implementação assistida com contexto do codebase
  • GitHub Copilot é mais útil para completion inline durante a escrita de código

O erro mais comum é pular direto para “me escreva o código para X”. Isso produz código genérico que provavelmente não se encaixa na sua arquitetura. O SDD resolve isso: você chega no passo de codificação com um contexto tão bem definido que a IA produz algo diretamente utilizável.

O workflow na prática

1. Brainstorm com IA

Antes de qualquer coisa, use a IA para explorar o espaço do problema. Não peça solução ainda — peça perguntas.

Prompt: "Quero adicionar sistema de notificações por email no meu app Rails.
Quais são as principais decisões de design que preciso tomar antes de implementar?
Que casos extremos devo considerar?"

A IA vai levantar pontos que você talvez não tivesse considerado: filas de envio, bounce handling, unsubscribe, templates, idempotência. Isso é o brainstorm. Você filtra o que é relevante para o seu contexto.

2. Spec document

Com o escopo definido, peça à IA para ajudar a escrever uma spec estruturada.

Prompt: "Com base nessa conversa, escreva uma spec técnica para o sistema de
notificações. Inclua: objetivo, requisitos funcionais, requisitos não-funcionais,
modelo de dados, interfaces públicas e o que está fora do escopo."

O output é um documento que você revisa e ajusta. Esse documento passa a ser o contexto para todos os próximos passos com a IA — e também serve como documentação para a equipe.

3. Implementation plan

Com a spec pronta, quebre em tasks concretas.

Prompt: "A partir dessa spec, crie um plano de implementação com tasks ordenadas
por dependência. Cada task deve ser pequena o suficiente para ser feita em uma
sessão de código. Indique quais podem ser feitas em paralelo."

O resultado é uma lista de tasks tipo: “criar migration para tabela notifications”, “criar modelo Notification com validações”, “criar job SendEmailNotificationJob”, etc. Cada uma delas é pequena, testável e tem escopo claro.

4. Código assistido

Agora sim você vai para o código, task por task. Mas não com um prompt vago — você traz a spec e a task específica como contexto.

Prompt: "Usando a spec abaixo e seguindo as convenções do nosso projeto Rails,
implemente o modelo Notification. [spec aqui] [código de exemplo do projeto aqui]"

Com contexto rico, a IA produz código que segue as convenções do projeto, não um exemplo genérico de tutorial.

5. Review

Depois de implementar, peça revisão para a própria IA — mas com critérios específicos.

Prompt: "Revise esse código considerando: (1) está seguindo a spec? (2) há edge
cases não cobertos? (3) os testes cobrem os cenários importantes? (4) há
problemas de performance óbvios?"

A IA não vai encontrar tudo, mas vai encontrar coisas que você estava cego por estar imerso no código.

Benefícios reais

Velocidade: o maior ganho não é a IA escrever código mais rápido — é você não ficar travado. Quando surgir uma dúvida de design no meio da implementação, você tem um interlocutor disponível 24/7.

Consistência: com a spec como contexto fixo, o código gerado em diferentes sessões tende a ser mais consistente do que o código que você escreveria em dias diferentes com humores diferentes.

Documentação automática: a spec que você criou no passo 2 já é documentação. Os prompts que você usou já documentam as decisões de design. Isso tem valor para a equipe e para você mesmo em 6 meses.

Onboarding de contexto: quando você volta a uma feature depois de semanas, pegar a spec e passar para a IA te reconecta ao contexto muito mais rápido do que ler o código.

Armadilhas para evitar

Confiar cegamente no código gerado. A IA pode produzir código que parece correto mas tem bugs sutis, especialmente em edge cases de concorrência, segurança e lógica de negócio complexa. Revisão humana não é opcional.

Pular a spec e ir direto para o código. Funciona para tasks triviais, mas para qualquer coisa com mais de 30 minutos de trabalho, a falta de spec vai te custar mais do que o tempo que você economizou.

Aceitar a spec da IA sem questionar. A IA vai gerar uma spec plausível, mas plausível não é o mesmo que correto para o seu contexto. Você precisa revisar e ajustar.

Usar a IA como substituto para entender o problema. Se você não consegue explicar o problema para um colega, a IA também não vai resolver isso. Ela vai gerar algo, mas provavelmente não o que você precisa.

Um exemplo concreto

Feature de exportação de relatório CSV que levaria 2 dias no fluxo tradicional:

  • 30 min de exploração com IA (quais formatos? async ou sync? como lidar com relatórios grandes?)
  • 20 min para revisar e finalizar a spec gerada pela IA
  • 15 min para quebrar em tasks
  • 2h para implementar as tasks com código assistido
  • 30 min de revisão

Total: menos de 4 horas. A aceleração não vem do código ser escrito mais rápido — vem de não ficar travado em decisões de design no meio da implementação.

Spec Kit: SDD como toolkit open source

O GitHub lançou o Spec Kit — um toolkit open source que formaliza o SDD em um processo estruturado com três fases claras e comandos prontos para uso com agentes de IA como Copilot, Claude Code e Gemini CLI.

As 3 fases do Spec Kit

1. Specify (/speckit.specify): Transforma ideias vagas em documentos de requisitos completos. Foca em necessidades de negócio e valor para o usuário, sem detalhes de implementação. Ambiguidades são marcadas explicitamente com [NEEDS CLARIFICATION].

2. Plan (/speckit.plan): Converte especificações em planos de implementação técnicos. Mapeia requisitos para decisões arquiteturais com justificativa documentada. Gera modelos de dados, contratos de API e cenários de teste.

3. Tasks (/speckit.tasks): Deriva listas de tasks executáveis a partir do plano. Identifica oportunidades de trabalho paralelo e produz entregas concretas prontas para geração de código.

A inversão de poder

A filosofia central do Spec Kit é que especificações não servem ao código — código serve às especificações. O PRD (Product Requirements Document) não é um guia para implementação; é a fonte que gera a implementação. Quando a spec dirige tudo, não há gap entre intenção e execução — só transformação.

Na prática, isso significa que o Spec Kit trata linguagem natural como artefato executável. Templates estruturados constrangem o output da IA para produzir specs de maior qualidade, e princípios constitucionais (como “test-first” e “library-first”) garantem que o código gerado mantenha consistência.

Por que isso importa

Antes do Spec Kit, cada time improvisava seu workflow de SDD. Agora existe um processo padronizado, com templates validados e gates de qualidade embutidos. Se você trabalha com agentes de IA para desenvolvimento, vale experimentar.

Ferramentas que funcionam bem juntas

  • Spec Kit: framework de SDD com fases e templates estruturados
  • Claude Code ou Cursor: para o ciclo de código com contexto do projeto
  • Claude.ai ou ChatGPT: para brainstorm, specs e planejamento (contexto de conversa longo)
  • GitHub Copilot: para completion inline durante a escrita

Conclusão

SDD com IA é sobre amplificar o desenvolvedor, não substituí-lo. A IA é boa em estruturar, gerar e revisar. Você é bom em entender o negócio, tomar decisões com contexto e julgar qualidade. O workflow funciona quando cada um faz o que faz melhor.

O Spec Kit do GitHub formalizou esse processo em algo replicável e open source. O investimento em escrever uma boa spec antes de codar retorna em código mais focado, menos retrabalho e documentação que se escreve sozinha. A IA torna esse investimento muito mais barato.

Referências