Desenvolvimento de software · IA · Boas práticas

O que é Spec-Driven Development?

Uma spec (especificação) é um registro estruturado da intenção e do comportamento esperado de uma funcionalidade. Pode reunir requisitos, regras de negócio, exemplos, critérios de aceitação, restrições técnicas e decisões de projeto. No SDD, esse material orienta as etapas seguintes, em vez de deixar que a implementação comece a partir de uma ideia vaga ou de um único pedido informal.

O termo ainda é usado de maneiras diferentes. Em geral, significa começar com uma especificação antes de implementar com IA. Algumas equipes mantêm a especificação atualizada durante a vida da funcionalidade; outras chegam a tratá-la como o principal artefato mantido. Portanto, SDD não determina um único formato de documento nem obriga a equipe a adotar uma ferramenta específica.

Para que serve?

• Diminuir ambiguidades: transformar pedidos genéricos em resultados observáveis e regras explícitas.
• Orientar agentes de IA: dar contexto suficiente para que a ferramenta proponha código coerente, sem depender de suposições escondidas.
• Alinhar pessoas: criar uma referência comum para produto, design, desenvolvimento, qualidade e negócio.
• Planejar e dividir o trabalho: converter requisitos em decisões técnicas, tarefas pequenas e testes.
• Facilitar revisão e manutenção: comparar o que foi construído com o comportamento combinado e entender a intenção por trás da funcionalidade.
• Reduzir retrabalho: descobrir contradições e lacunas antes que elas se espalhem pelo código.

O SDD é particularmente útil em funcionalidades com várias regras, integrações, impacto em dados ou critérios de aceitação importantes. Para uma correção trivial e bem compreendida, uma especificação extensa pode custar mais do que ajuda.

Como criar uma especificação prática

1. Descreva o problema e o objetivo. Explique o que está acontecendo hoje, quem é afetado e qual resultado se pretende alcançar. Evite começar escolhendo a solução antes de entender a necessidade.
2. Defina o escopo. Registre o que entra nesta mudança e, se necessário, o que fica explicitamente de fora.
3. Escreva requisitos comportamentais. Prefira frases concretas: “O sistema permite que uma pessoa solicite um link de recuperação” em vez de “Melhorar o login”.
4. Inclua regras, exceções e restrições. Considere permissões, estados inválidos, limites, privacidade, acessibilidade, desempenho e compatibilidade, conforme o caso.
5. Defina critérios de aceitação testáveis. Cada critério deve indicar uma condição observável para aceitar ou rejeitar o resultado.
6. Peça uma análise de lacunas antes do plano. A pessoa ou agente deve apontar dúvidas, contradições, riscos e dependências; não deve inventar respostas importantes.
7. Planeje e divida em tarefas. Só depois de validar o comportamento esperado, decida arquitetura, arquivos envolvidos, sequência de implementação e testes.
8. Implemente em etapas pequenas e verifique. Execute testes, revise o diff e compare cada resultado com a especificação. Atualize a spec quando a decisão mudar de forma deliberada.

Exemplo de especificação

Esse exemplo registra o comportamento, não prescreve uma arquitetura. Detalhes técnicos — como armazenamento de tokens e integração com o provedor de e-mail — pertencem ao plano, salvo quando forem restrições obrigatórias do projeto.

Um modelo reutilizável

Prompt aprimorado para trabalhar com uma IA

Você como fullstack developer pode adaptar este prompt a uma funcionalidade real. Ele separa a definição do problema da implementação e pede que dúvidas importantes sejam levantadas antes de gerar código:

Quero desenvolver ou alterar esta funcionalidade: [descreva a ideia].

Antes de escrever código:
1. Analise o contexto e os arquivos existentes do projeto; não recrie componentes ou regras que já existem.
2. Resuma o problema, os usuários afetados, o objetivo e o que está fora do escopo.
3. Elabore uma especificação comportamental com requisitos claros, regras de negócio, exceções, restrições e critérios de aceitação verificáveis.
4. Identifique ambiguidades, contradições, riscos e decisões em aberto. Não invente respostas para decisões que mudem o comportamento, a segurança, os dados ou o escopo; pergunte primeiro.
5. Separe requisitos funcionais de decisões de implementação. Reutilize os padrões e a arquitetura existentes, salvo justificativa explícita.
6. Aguarde minha aprovação da especificação antes de propor ou executar mudanças no código.

Depois da aprovação:
7. Apresente um plano técnico curto e tarefas pequenas, com os testes correspondentes.
8. Implemente uma tarefa por vez, mantendo as alterações limitadas ao escopo aprovado.
9. Execute os testes relevantes, informe resultados reais, limitações e arquivos alterados. Não declare sucesso se algo não foi verificado.
10. Se a implementação exigir mudar a especificação, explique a diferença e peça confirmação antes de ampliar o escopo.

Contexto do projeto: [stack, convenções, restrições e requisitos relevantes].
Critérios adicionais: [segurança, acessibilidade, desempenho, compatibilidade etc.].

Dicas para obter bons resultados

• Use linguagem observável. Troque “rápido”, “intuitivo” ou “seguro” por limites, cenários ou controles que possam ser avaliados.
• Mostre exemplos e contraexemplos. Entradas, saídas esperadas, estados e mensagens ajudam a reduzir interpretações diferentes.
• Separe necessidade de solução. Não misture “o usuário precisa recuperar a conta” com “criar uma tabela específica”, a menos que essa decisão técnica seja uma restrição.
• Trate questões em aberto como questões. Marque claramente o que precisa de resposta; não deixe a IA preencher lacunas importantes por conta própria.
• Trabalhe em fatias pequenas. Uma mudança revisável de cada vez facilita correções e impede que um plano grande esconda erros.
• Evite documentação duplicada. Não mantenha vários arquivos longos dizendo a mesma coisa. Escolha um local claro para a especificação e atualize-o quando necessário.
• Revise o código, não só a spec. Uma boa especificação não garante que o agente a seguirá, nem prova que o código está correto.
• Defina a estratégia de manutenção. Decida se a especificação será descartável após a entrega, mantida como referência ou tratada como artefato central do projeto.

O que o Spec-Driven Development não é

• Não é apenas escrever um prompt enorme. Uma especificação útil é revisável, organizada e conectada a critérios de aceitação e verificação.
• Não é uma garantia contra erros de IA. Agentes podem ignorar instruções, interpretar mal requisitos ou produzir código incorreto.
• Não é sinônimo de TDD. TDD (desenvolvimento orientado a testes) é uma prática de ciclo de implementação guiada por testes. SDD organiza o trabalho a partir de uma especificação. Podem ser combinados, mas não são a mesma coisa.
• Não exige sempre um processo burocrático. Ajuste a quantidade de documentação ao risco e ao tamanho da tarefa.
• Não significa que o código deixou de importar. Testes, revisão, observabilidade e manutenção continuam essenciais.

Ferramentas e formatos

Uma especificação pode ser um documento Markdown, uma página de produto, critérios em um sistema de gestão, exemplos executáveis ou um conjunto de artefatos. Ferramentas como o GitHub Spec Kit oferecem fluxos estruturados que passam por especificação, planejamento, tarefas e implementação. O fluxo e os comandos podem mudar; consulte a documentação oficial antes de instalar ou aplicar a ferramenta no seu projeto.

Você também pode começar sem ferramenta especializada: crie um arquivo curto por funcionalidade, revise-o com a equipe e use-o como contexto para o assistente de código. O processo deve servir ao produto — não o contrário.

Conclusão

Spec-Driven Development é uma maneira de tornar explícito o que se quer construir antes de delegar ou iniciar a implementação. Quando a especificação é clara, testável e enxuta, ela ajuda pessoas e agentes de IA a planejar melhor, reduzir suposições e verificar o resultado. A melhor abordagem não é a que produz mais documentos: é a que mantém intenção, código e testes alinhados, sem criar burocracia desnecessária.

Referências

• Martin Fowler / Thoughtworks — Understanding Spec-Driven-Development: Kiro, spec-kit, and Tessl.
• Thoughtworks Technology Radar — Spec-driven development.
• GitHub — Spec Kit.

Artigo educativo. Adapte o processo ao contexto, ao risco e às práticas da sua equipe.