Uma feature spec ruim não é a que “falta detalhe” de forma genérica. É a que falha numa parte específica, de um jeito previsível. Depois de gerar centenas de specs no Feature Spec do Artifice, os erros se repetem nos mesmos lugares. Aqui está o que cada seção precisa ter para não ser só um documento bonito que ninguém segue.
Problema: a dor, não a solução
O erro mais comum é escrever o problema já pensando na solução. “O usuário precisa de um botão de exportar PDF” não é um problema, é uma solução disfarçada. O problema real por trás disso pode ser “o usuário perde 20 minutos toda semana copiando dados manualmente para um relatório”, e esse problema poderia ter três soluções diferentes, não só uma.
Teste rápido: se o seu “problema” já menciona uma tela, um botão ou uma tecnologia, provavelmente é solução, não problema. Reescreva perguntando “por quê” mais uma vez.
Solução: o que muda, não como foi construído
A solução descreve o resultado do ponto de vista de quem usa, não a arquitetura técnica. “Adicionar um endpoint REST que retorna um blob PDF” é implementação. “O usuário consegue baixar um PDF do relatório filtrado, com um clique, da própria tela de transações” é solução. A arquitetura vai nas notas técnicas, mais abaixo.
Histórias de usuário: o formato força clareza
O formato “Como [perfil], quero [ação], para [benefício]” parece burocrático, mas cada parte tem uma função. Perfil evita specs genéricas que tentam servir todo mundo. Ação obriga a ser concreto. Benefício garante que a história ainda faz sentido se você reler daqui a três meses. Uma história sem o “para” claro costuma ser sinal de que ninguém validou se aquilo resolve algo de verdade.
Critérios de aceite: mensuráveis, não vagos
“O sistema deve ser rápido” não é um critério de aceite, é uma esperança. Um critério de aceite bom responde: como alguém, testando manualmente, sabe que está pronto? “PDF gerado em menos de 5 segundos para até 1000 transações” é testável. O formato Given/When/Then ajuda: dado que o usuário selecionou um filtro, quando clica em exportar, então o PDF reflete exatamente esse filtro.
Sem critérios testáveis, “pronto” vira uma negociação em vez de um fato. É aí que nasce o retrabalho.
Escopo: o que fica de fora é tão importante quanto o que entra
A seção “fora de escopo” existe para prevenir scope creep no meio do desenvolvimento. Sem ela documentada, cada “ah, mas dava pra adicionar só mais isso” vira uma discussão do zero. Liste explicitamente o que essa versão não faz, mesmo que pareça óbvio.
Notas técnicas: edge cases antes de virarem bugs em produção
O que quebra quando os dados são inesperados? Zero resultados, volume muito grande, caracteres especiais, timeout de rede. Pensar nisso na spec é mais barato do que descobrir em produção. Não precisa ser exaustivo, mas os 3 ou 4 casos mais prováveis de quebrar já economizam uma rodada inteira de retrabalho.
Estimativa de complexidade: um sinal, não uma promessa
Baixa, média ou alta complexidade não é sobre prever prazo exato, é sobre dar ao time contexto suficiente pra priorizar. Uma spec sem nenhuma noção de complexidade força quem prioriza a adivinhar, e adivinhação de prioridade é onde specs boas morrem na fila do backlog.
Uma spec com essas sete partes bem resolvidas elimina a maior parte das idas e vindas entre quem pede a feature e quem constrói. O Feature Spec gera esse documento completo a partir de uma descrição em linguagem natural. Vale ver como cada seção fica preenchida na prática.