Introdução

Com o advento da inteligência artificial no desenvolvimento de software, escrever código se tornou a parte mais trivial do processo. No entanto, se não usada corretamente, a IA pode introduzir bugs e complexidade desnecessários, aumentando significativamente o retrabalho.

Felizmente, existem técnicas que tornam o resultado da IA mais determinístico, contornando um dos principais problemas do seu uso no desenvolvimento de software. Uma dessas técnicas é o SDD — Spec Driven Development — que será abordado neste artigo.

O que é Spec Driven Development?

Na prática, é uma metodologia que inverte a relação entre código e requisitos. Em equipes que mantêm sistemas legados, é comum que o código seja a fonte da verdade. Quando surge uma dúvida de negócios sobre o sistema, se a documentação é ausente, a equipe precisa recorrer ao código para entender o comportamento. Num cenário ideal, após descobrir o funcionamento, gera-se documentação para evitar esse esforço no futuro.

O problema é que, dependendo de onde essa documentação é criada, mantê-la atualizada conforme o sistema evolui se torna cada vez mais complexo.

O SDD propõe inverter essa dinâmica: a documentação passa a ser a fonte da verdade, e o código se torna apenas um reflexo dela. Essa inversão é especialmente valiosa com IA porque modelos de linguagem precisam de contexto explícito — eles não inferem intenções de negócio como um humano faria.

Funcionamento

Como o nome sugere, a documentação central dessa metodologia é a especificação (spec), ou PRD — Product Requirement Document. Esse documento contém todas as regras e requisitos de uma nova funcionalidade em linguagem não técnica. A equipe de desenvolvimento, juntamente com a área de negócios, evolui esse documento garantindo que todos os pontos estão cobertos. Só então inicia-se a fase de desenvolvimento, delegando a criação do código para a IA com base no documento de especificações. A spec serve como um “contrato” entre produto e engenharia, e a IA atua como “executora” desse contrato.

Por que SDD torna a IA determinística?

Sem uma especificação clara, o desenvolvimento com IA se assemelha a pedir para alguém construir algo com base numa conversa informal. O resultado varia a cada interação — a IA pode interpretar requisitos de formas diferentes, tomar decisões de design inconsistentes entre sessões e introduzir comportamentos não previstos. Esse é o cerne da não-deterministicidade: mesmo com o mesmo prompt, pequenas variações no contexto ou no modelo podem gerar outputs radicalmente diferentes.

O SDD resolve isso ao transformar requisitos ambíguos em um documento estruturado e explícito. A spec funciona como um contrato: cada regra de negócio, critério de aceitação e cenário de erro está documentado de forma que a IA não precisa “adivinhar” intenções. O resultado é previsível e repetível — se a spec não muda, o código gerado tende a ser consistente entre execuções.

O que é uma especificação (spec)

Nada mais é que um documento que detalha todos os comportamentos de um sistema, quais resultados são esperados para cada ação de um usuário, o que uma funcionalidade deve ou não fazer, critérios de aceitação, etc. Os artefatos de uma especificação podem variar muito de acordo com qual abordagem de aplicação do SDD irá utilizar.

Exemplo de uma especificação:

# Funcionalidade: Reset de Senha por E-mail

## Descrição

Permitir que usuários solicitem a redefinição de senha através de um link enviado por e-mail.

## Regras de Negócio

- O link de reset expira em 15 minutos após a geração
- Cada link só pode ser utilizado uma única vez
- O usuário deve estar cadastrado na base para receber o e-mail
- A nova senha deve ter no mínimo 8 caracteres, incluindo uma letra maiúscula e um número
- Após 5 tentativas falhas de reset em 1 hora, a conta é temporariamente bloqueada

## Critérios de Aceitação

1. Usuário informa e-mail → recebe e-mail com link de reset
2. Usuário acessa link válido → pode definir nova senha
3. Usuário acessa link expirado → recebe mensagem de erro e opção de solicitar novo link
4. Senha definida com sucesso → usuário é redirecionado para login

## Cenários de Erro e Borda

- E-mail não cadastrado: não revelar se o e-mail existe (mensagem genérica: "Se o e-mail estiver cadastrado, você receberá um link")
- Link já utilizado: exibir "Este link já foi utilizado. Solicite um novo reset."
- Tentativa de brute force: bloquear IP após 10 requisições consecutivas
- Serviço de e-mail indisponível: enfileirar requisição e retry com backoff exponencial

Algumas ferramentas para aplicação de SDD

  • spec-kit: Conjunto de ferramentas open source criado pelo GitHub. Contém diversos artefatos que auxiliam numa especificação sólida e com grande cobertura de cenários de erro e de borda, que auxiliam na criação de um sistema robusto e resiliente. Pode parecer muito para projetos pequenos devido à quantidade de artefatos gerados durante o desenvolvimento e possuir uma curva moderada de aprendizado.

  • open-spec: Propõe-se a ser um framework lightweight para desenvolvimento spec-driven. Fornece alternativas de desenvolvimento mais diretas, requerendo poucos artefatos, e alternativas mais robustas que englobam desde o entendimento inicial de um problema, desenho de solução até a implementação do código. Sua curva de aprendizado é baixa.

  • kiro: IDE criada pela AWS voltada para desenvolvimento com agentes e SDD. Não cheguei a testar, mas pelo que observei segue uma pegada lightweight com poucos artefatos.

  • get-shit-done: Outra alternativa open source. Essa já estava em meu radar, no entanto vi que sua versão original passou por problemas com os mantenedores, então resolvi segurar meus testes, mas vale a menção.

Pontos positivos do SDD na prática

Pontos positivos observados durante minha adoção ao SDD no meu dia a dia:

  • Identificação de casos de borda e cenários de erro que passariam despercebidos durante o refinamento de tarefas tradicional
  • Envolvimento com produto durante a fase de definição de especificação trouxe diversos benefícios, entre eles uma melhor interação entre engenharia e produto, melhor mapeamento das necessidades da funcionalidade, além de promover a discussão de uma funcionalidade — até mesmo inviabilizando alguma antes mesmo de iniciar o código
  • Resultado próximo do determinismo no uso da IA para desenvolvimento de software. Seguindo o SDD, o resultado de uma entrega foi muito próximo a uma tarefa similar feita inteiramente por um humano
  • Tempo de desenvolvimento reduzido consideravelmente. Tarefas que levariam 2 semanas levam poucos dias, onde a maioria é gasta na definição da especificação; o código leva pouquíssimo tempo
  • O uso do TDD (Test Driven Development) se mostrou essencial nos resultados esperados da IA — os testes atuam como guardrails automatizados que validam se o código gerado segue a especificação

Pontos negativos do SDD na prática

  • Em projetos green-field (projetos novos) o SDD é muito performático e assertivo. No entanto, em projetos legados com uma code-base não padronizada, o tempo gasto durante a especificação e detalhamento técnico aumenta consideravelmente, pois é necessário definir quais padrões de código seguir, quais não replicar, etc.
  • Para tarefas pequenas ou triviais o SDD se torna gargalo. O ideal é utilizá-lo em funcionalidades maiores
  • No meio corporativo é comum uma funcionalidade exigir trabalho em múltiplos projetos diferentes ao mesmo tempo. Para esse cenário, a aplicação do SDD se torna um problema, pois manter contexto compartilhado entre repositórios é desafiador, além de exigir um controle de token mais refinado
  • Com as inúmeras ferramentas disponíveis para aplicação de SDD e cada uma seguindo uma forma de implementar, aplicar diferentes ferramentas em um projeto se torna desafiador. Por ser um conceito novo, não existe um padrão definido para arquivos de especificações e artefatos a serem gerados — isso é um cenário que pode inserir muitos arquivos na sua code-base.

Próximos passos

Alguns pontos que tenho mapeados para continuar evoluindo meus conhecimentos no SDD são:

  • Conceitos de “harness engineering”, que consistem em fornecer o ferramental para que a IA possa ter guardrails e limites bem definidos, garantindo que seu resultado saia como esperado. Por exemplo: a adoção de um linter robusto, testes automatizados, entre outros.

  • Aplicar SDD sem as ferramentas disponíveis, ou seja, criar prompts e skills que me forneçam uma experiência próxima à oferecida por tais ferramentas sem ficar dependente delas, dessa forma mantendo a code-base limpa de arquivos desnecessários.

Conclusão

O Spec Driven Development se mostra uma abordagem promissora para quem busca usar IA de forma mais previsível no desenvolvimento de software. Embora exija investimento inicial na criação de especificações detalhadas, os ganhos em qualidade, alinhamento entre equipes e velocidade de implementação justificam a adoção — especialmente para funcionalidades complexas.

Como toda metodologia, não é bala de prata. O ideal é experimentar em projetos piloto e avaliar se os benefícios se aplicam ao seu contexto.