Código / CDG.005Explicado

Spec-driven development: escreva o que você quer antes de pedir código à IA

Antes de pedir código a um agente de IA, escreva o que você quer construir. Entenda o desenvolvimento guiado por especificação e as quatro etapas do Spec Kit.

Você pede a um agente de IA “crie uma tela de cadastro” e recebe algo que funciona, mas não é o que você tinha em mente. Faltou validação, o fluxo de erro ficou estranho e a tela não conversa com o resto do projeto. No entanto, o problema raramente é o modelo. Na maioria das vezes, o pedido deixou espaço demais para adivinhação. O spec-driven development (desenvolvimento guiado por especificação) propõe inverter a ordem: primeiro você descreve com cuidado o que quer construir e por quê, e só depois o código é gerado.

Neste explicado, você vai entender a ideia, conhecer as quatro etapas do Spec Kit, um kit aberto que o GitHub lançou em setembro de 2025, e ver quando esse método compensa.

O que é spec-driven development

Spec-driven development é uma forma de trabalhar em que a especificação vira a fonte principal de verdade do projeto. Em vez de tratar o documento como algo que se escreve uma vez e se esquece, a equipe mantém a especificação viva, e o código passa a ser uma consequência dela.

O anúncio do GitHub resume o motivo com uma frase direta: modelos de linguagem são excelentes em completar padrões, mas não em ler mentes. Ou seja, quando o pedido é vago, o modelo precisa preencher dezenas de requisitos que ninguém disse. Por isso, uma especificação clara reduz essas suposições.

Isso não é uma ideia nova. Afinal, equipes de software sempre escreveram requisitos. A diferença agora é o leitor: além das pessoas, um agente de IA lê o documento e age a partir dele.

As quatro etapas do Spec Kit

O Spec Kit organiza o trabalho em quatro fases, cada uma com um ponto de conferência. Além disso, ele funciona com agentes como GitHub Copilot, Claude Code e Gemini CLI, segundo o próprio GitHub.

  1. Especificar. Você descreve o que está construindo e por quê: quem usa, que problema resolve, como saber que deu certo. Por enquanto, ainda não se fala de tecnologia.
  2. Planejar. Aqui entram as decisões técnicas: linguagem, arquitetura, restrições do projeto. Em seguida, o agente propõe um plano, e você pode pedir variações para comparar.
  3. Quebrar em tarefas. A especificação e o plano viram tarefas pequenas, que podem ser feitas e testadas isoladamente.
  4. Implementar. O agente executa as tarefas, e você revisa mudanças menores em vez de um bloco enorme de código.
Fluxo do spec-driven development em quatro etapas: especificar o que e por quê, planejar a parte técnica, quebrar em tarefas pequenas e implementar com revisão a cada tarefa, com a pessoa conferindo entre uma etapa e outra.
Cada etapa termina com uma conferência humana. O código só aparece na última.

No kit, cada fase tem um comando próprio (/specify, /plan e /tasks), e a estrutura do projeto é criada por uma ferramenta de linha de comando chamada specify.

Por que a especificação melhora o resultado

Pense em uma tarefa simples: “adicionar recuperação de senha”. Sem especificação, o agente decide sozinho quanto tempo o link vale, o que acontece com um e-mail que não existe e qual texto aparece na tela. Assim, cada uma dessas escolhas pode estar errada para o seu produto.

Com uma especificação curta, essas decisões ficam registradas antes do código. Assim, o agente deixa de adivinhar, e quem revisa tem um critério para dizer se o resultado está certo. Além disso, a especificação continua útil depois: quando alguém pergunta “por que funciona assim?”, a resposta está escrita.

Comparação entre um pedido vago e uma especificação: o pedido vago deixa o agente decidir prazo do link, mensagem de erro e comportamento para e-mail inexistente; a especificação registra essas decisões antes do código.
Exemplo ilustrativo. Cada lacuna do pedido vago vira uma decisão tomada pelo modelo, não por você.

Quando o spec-driven development compensa

O GitHub aponta três situações em que o método rende mais:

  • Projetos do zero, para que a IA construa o que você pretende, não uma solução genérica.
  • Novas funcionalidades em sistemas existentes, porque o plano registra as restrições de arquitetura e o código novo se encaixa no que já existe.
  • Modernização de sistemas antigos, já que a lógica de negócio é capturada numa especificação nova antes da reconstrução.

Por outro lado, para um ajuste pequeno ou um protótipo descartável, escrever uma especificação completa pode ser exagero. Nesses casos, um pedido bem feito resolve.

Como começar sem ferramenta nenhuma

Você não precisa instalar o Spec Kit para aproveitar a ideia. Por exemplo, antes do próximo pedido a um agente, tente escrever um arquivo curto com quatro partes:

  1. Objetivo: o que a funcionalidade faz, em uma frase.
  2. Quem usa e em que situação.
  3. Critérios de aceite: como você vai saber que ficou certo.
  4. Fora do escopo: o que não deve ser feito agora.

Depois, peça ao agente que leia esse arquivo antes de propor qualquer código. Se o resultado ainda vier diferente do esperado, a pergunta muda de “o modelo errou?” para “o que faltou na especificação?”. Afinal, é essa pergunta que faz o processo melhorar a cada ciclo.

Se você quer entender o que acontece quando o agente começa a agir, vale ler o que são agentes de IA. E, para dar ao agente regras permanentes do projeto, a especificação combina bem com um arquivo de instruções, assunto de outro explicado desta editoria.

/ Conexões

Próximas conexões

Autor

Gledson Dias

Ver todos os artigos

Sistemativo / Brief

Gostou dessa ideia?

A cada duas semanas, ideias, ferramentas, referências e movimentos que valem alguns minutos da sua atenção.

Brief (formulário compacto)

Você poderá sair da lista quando quiser. Sem spam.