Spec driven development com IA: como começar na sua equipe

Spec driven development com IA: como começar na sua equipe

Spec driven development com IA é a prática de escrever uma especificação clara e revisável antes de pedir código a um assistente, e usar esse texto como referência para gerar, testar e revisar. Em vez de corrigir resultados vagos depois, a equipe discute intenção, limites e critérios de aceite antes da primeira linha. A hipótese de trabalho é simples: o erro de entendimento aparece no texto, onde custa pouco para corrigir, e não no código já escrito.

Principais pontos

• A especificação vira o contrato entre pessoas e assistente: o que deve acontecer, o que não pode acontecer e como saber que ficou pronto.
• Assistentes de código preenchem lacunas com suposições. Quanto mais lacunas na instrução, mais retrabalho na revisão.
• Uma boa especificação é curta, verificável e versionada junto com o código, não um documento longo que ninguém atualiza.
• Os critérios de aceite da especificação são a base natural dos testes, o que facilita validar o que a IA entregou.
• O caminho mais seguro para começar é um piloto em uma funcionalidade real e pequena, com revisão humana e um critério de sucesso combinado antes.

O que é desenvolvimento guiado por especificação com IA?

É uma forma de organizar o trabalho com assistentes como Claude Code, Copilot ou Cursor. Primeiro a equipe escreve, em linguagem comum, o que a mudança precisa fazer. Depois o assistente propõe um plano, a equipe revisa o plano e só então o código é gerado. A especificação continua viva: quando o comportamento muda, o texto muda primeiro.

Isso não é novidade como ideia. Times que já escreviam requisitos, histórias de usuário ou documentos de design conhecem o princípio. O que muda com assistentes é a velocidade: gerar código ficou barato, então o gargalo passa a ser decidir bem o que gerar. Uma instrução ambígua produz muito código plausível e errado, e ler esse código custa tempo de gente experiente.

Vale separar três coisas. O que a documentação oficial das ferramentas descreve é como fornecer instruções e contexto ao modelo. O que vem de experiência de implementação é que equipes tendem a ganhar clareza quando discutem o texto antes do código. E o que ainda é hipótese, e deve ser testado na sua realidade, é quanto retrabalho cada equipe realmente evita.

Por que pedir código sem especificação gera retrabalho?

Quando alguém escreve apenas "crie a tela de reagendamento", o assistente precisa decidir sozinho muitas coisas: quem pode reagendar, até quando, o que acontece com a cobrança, que mensagem aparece em caso de erro. Cada decisão tomada em silêncio é uma possível divergência com o que o negócio queria.

O retrabalho costuma aparecer de quatro formas:

• Regras de negócio inventadas pelo modelo que parecem razoáveis, mas contradizem a operação.
• Código que funciona no caminho feliz e ignora casos de borda, como dados ausentes ou usuário sem permissão.
• Mudanças que tocam arquivos demais, porque o limite do escopo nunca foi dito.
• Revisões longas, em que o revisor precisa reconstruir a intenção a partir do código.

A especificação desloca essa conversa para antes. A discussão acontece sobre um parágrafo, não sobre um conjunto de alterações já espalhado pelo repositório.

O que uma boa especificação contém?

Não precisa ser longa. Precisa ser verificável. Uma estrutura enxuta que funciona para a maioria das tarefas:

• Objetivo: a mudança em uma ou duas frases, ligada ao problema de negócio.
• Contexto: onde isso vive no sistema, quais módulos e integrações são afetados.
• Comportamento esperado: regras escritas como situações e resultados (quando acontece X, o sistema faz Y).
• Fora de escopo: o que o assistente não deve tocar nem decidir.
• Dados e permissões: quais dados pessoais entram, quem pode executar a ação, o que precisa ser registrado em log.
• Critérios de aceite: condições objetivas que a equipe pode checar, de preferência convertidas em testes.
• Perguntas em aberto: dúvidas que precisam de resposta humana antes de implementar.

O item de perguntas em aberto é o mais subestimado. Pedir ao assistente que liste dúvidas antes de planejar evita que ele preencha lacunas por conta própria.

Como começar: um plano em etapas

Para uma equipe que ainda não adotou a prática, a sugestão é um piloto curto e controlado:

• Escolha uma funcionalidade real, pequena e de baixo risco, com um responsável de negócio disponível para tirar dúvidas.
• Defina o critério de sucesso antes de começar, por exemplo: menos rodadas de correção na revisão e entendimento claro do que foi entregue. Registre como será observado.
• Escreva a especificação em um arquivo no próprio repositório, em texto simples, para que fique versionada e revisável como qualquer outro artefato.
• Peça ao assistente que leia a especificação e devolva dúvidas e um plano de implementação, sem escrever código ainda.
• Revise o plano com um humano. Corrija a especificação, não apenas a resposta do assistente.
• Gere o código em passos pequenos, cada um ligado a um critério de aceite, e rode os testes a cada passo.
• Faça a revisão de código comparando o resultado com a especificação, não apenas com a opinião de quem revisa.
• Ao final, registre o que faltou na especificação e ajuste o modelo de documento para a próxima tarefa.
• Decida com base no que foi observado: expandir para outras tarefas, ajustar o formato ou parar.

Esse último ponto importa. Se o formato não ajudou naquele tipo de trabalho, parar é um resultado legítimo do piloto.

Cenário ilustrativo: regra de reagendamento de visita técnica

Imagine, como exemplo, uma empresa de serviços que quer permitir que o cliente reagende uma visita técnica pelo sistema interno. Sem especificação, o pedido ao assistente seria "permita reagendar visitas". O resultado provável: um botão que altera a data, sem checar se o técnico está disponível e sem avisar ninguém.

Com especificação, o texto diria algo assim: o cliente só pode reagendar visitas ainda não iniciadas; a nova data precisa respeitar a agenda do técnico; se não houver horário, o sistema oferece a lista de datas livres e não altera nada; toda alteração gera um registro com quem pediu e quando; mensagens ao cliente seguem os modelos já aprovados; mudanças na cobrança estão fora de escopo. Nas perguntas em aberto, a equipe anota: existe prazo mínimo antes da visita para permitir mudança?

A resposta a essa pergunta vem do responsável de operações, em minutos, antes de qualquer código. Sem essa etapa, a regra provavelmente seria descoberta em produção. Este é um exemplo construído para ilustrar o mecanismo, não um resultado de cliente.

Como a especificação se conecta a testes, contexto e skills?

Os critérios de aceite são o ponto de ligação com a qualidade. Cada critério verificável pode virar um teste, e isso reduz o risco de aceitar testes que apenas confirmam o que o código já faz. Vale ler o texto sobre testes automatizados gerados por IA e como validar para montar essa etapa com cuidado. A documentação da Anthropic sobre como avaliar agentes segue a mesma lógica: definir antes o que conta como sucesso e medir contra isso.

Há também a questão do contexto. Uma especificação longa demais ocupa espaço que o modelo poderia usar para o código relevante. A orientação da Anthropic sobre engenharia de contexto para agentes vai no sentido de fornecer informação suficiente e enxuta, sem excesso. Se o tema é novo para você, o artigo sobre janela de contexto em IA explica por que isso importa.

Por fim, o que se repete deve virar padrão. Modelos de especificação, convenções do projeto e checklists de revisão podem ser empacotados como skills no Claude Code, para que toda a equipe parta do mesmo formato. Como princípio geral, o material da Anthropic sobre agentes eficazes recomenda começar simples e só adicionar complexidade quando ela se justificar, o que vale também para o processo.

Quais erros evitar e como saber se está funcionando?

Os problemas mais comuns são previsíveis:

• Escrever a especificação depois do código, só para documentar. Isso não reduz retrabalho, apenas cria papel.
• Detalhar demais. Um texto enorme que descreve implementação tira a liberdade de bons planos e fica desatualizado rápido.
• Deixar de dizer o que está fora de escopo.
• Tratar o plano do assistente como aprovado sem leitura humana.
• Colocar dados pessoais reais de clientes na especificação ou nos prompts sem necessidade. Se houver dado pessoal envolvido, a equipe deve alinhar com a política interna e com as exigências da LGPD, e usar exemplos fictícios sempre que possível.

Sobre medir, o cuidado é não transformar o piloto em vigilância individual. Observe sinais do processo: quantas vezes uma entrega volta para correção, quantas dúvidas surgiram só na revisão, se o revisor entendeu a intenção sem perguntar. O texto sobre como medir produtividade com IA sem virar vigilância detalha essa abordagem.

O método que usamos em projetos de IA se aplica aqui de forma direta. Mapear: entender como a equipe especifica e revisa hoje, e onde o retrabalho se concentra. Limitar: definir quais tarefas, dados e permissões o assistente pode tocar. Pilotar: aplicar o formato em um fluxo real, com registro e um critério de sucesso combinado. Transferir: entregar o modelo de especificação e o processo de revisão para a equipe, e decidir juntos se expande, ajusta ou para.

Perguntas frequentes

Spec driven development com IA serve para equipes pequenas? Serve, desde que o formato seja leve. Para uma equipe pequena, uma especificação de poucos parágrafos no repositório já cria o hábito de decidir antes de gerar. O risco é burocratizar, então comece por uma tarefa e ajuste conforme o uso.

Preciso de uma ferramenta específica para praticar? Não necessariamente. O núcleo da prática é um arquivo de texto revisável, um assistente que consiga lê-lo e um processo de revisão que compare o resultado com ele. Existem ferramentas que estruturam esse fluxo, mas é possível começar com o que a equipe já usa.

A especificação substitui o prompt? Não, ela o organiza. O prompt passa a apontar para a especificação e pedir etapas claras, como listar dúvidas, propor um plano e implementar um critério por vez. A especificação fica no repositório e serve também para quem chega depois, enquanto o prompt é descartável.

Como saber se a prática está reduzindo retrabalho? Combine antes do piloto o que será observado, como o número de rodadas de correção por entrega e as dúvidas que só apareceram na revisão, e compare com o fluxo anterior sem transformar isso em ranking de pessoas. Se o ganho não for perceptível naquele tipo de tarefa, ajuste o formato ou interrompa. A decisão deve vir do que foi registrado, não da expectativa.

Fontes

• Anthropic: Effective context engineering for AI agents
• Anthropic: Demystifying evals for AI agents
• Anthropic: Building effective agents