Como escrever histórias de usuário que um construtor de apps com IA consegue usar

Uma boa história de usuário já traz quase tudo de que um construtor de apps com IA precisa: quem é o usuário, o que ele quer e por quê. O que costuma faltar são os dados, os caminhos de erro e uma definição de pronto que dá para conferir clicando.

A mesma história, antes e depois

Esta é aquela história que passa batida no refinamento e depois decepciona todo mundo.

Como gestor, quero ver os pedidos de férias do meu time.

Entregue isso a um dev e ele vem à sua mesa com seis perguntas. Entregue a um construtor com IA e ele responde as seis sozinho, em silêncio, no chute. Vai escolher os campos, inventar os status e decidir o que significa 'ver'. Parte dos palpites vai estar certa. Você só descobre qual quando clicar.

Agora a versão com as perguntas já respondidas:

Como gestor de time, quero uma lista dos pedidos de férias da minha equipe, para aprovar ou recusar antes do fim da semana.

Dados e campos

Nomeie todos os campos e diga que valores cada um aceita. Essa é a melhoria que mais rende, porque o modelo de dados é o que sai caro de mudar depois. No StarBuild, por exemplo, o que você descreve vira uma tabela de verdade no Postgres, então campo vago vira coluna vaga.

• Nome do colaborador, texto, obrigatório.
• Data de início e data de fim, datas, com o fim nunca antes do início.
• Tipo: férias ou licença não remunerada.
• Status: pendente, aprovado ou recusado. Nasce pendente. Nenhum outro.
• Justificativa, texto, opcional, preenchida quando o gestor recusa.
• Criado em, preenchido pelo sistema, ninguém digita.

Linhas de exemplo ajudam mais do que parece. Três pedidos inventados, um de cada status, mostram ao construtor o tamanho de um nome e como é um intervalo de datas realista.

Estados vazio, carregando e erro

É aqui que o protótipo começa a parecer de mentira, então diga o que quer em uma frase para cada. Vazio: 'Nenhum pedido ainda. Quando alguém do seu time pedir folga, aparece aqui.' Carregando: algumas linhas cinza no lugar da tabela, não um spinner numa página em branco. Erro: 'Não conseguimos carregar os pedidos. Tente de novo', com botão de tentar novamente, e a lista continua como estava se uma aprovação falhar.

Esse último caso pesa. Se o gestor clica em Aprovar e o salvamento falha, o selo não pode ficar verde. Escreva isso. Senão você vai descobrir na hora da demonstração.

Permissões e fora de escopo

Regra não dita é o que mata em silêncio. Quem pode ver a página? O gestor vê só o time dele, não a empresa inteira. O colaborador cria o pedido mas não aprova o próprio. Escreva em frases simples. Se o app tem login, o construtor precisa saber qual papel enxerga qual tela.

Depois, trace a cerca. Fora do escopo desta história: visão de calendário, notificação por e-mail, cálculo de saldo de férias, feriados, importação de outro sistema. Uma lista curta de 'agora não' evita muito trabalho extra entusiasmado que você depois tem de revisar e apagar.

Critérios de aceite que se checam com cliques

Um critério é bom se alguém que não o escreveu consegue dizer, em menos de um minuto e só com o mouse, se ele é verdadeiro. Compare 'a aprovação funciona bem' com 'ao clicar em Aprovar num pedido pendente, a linha passa a mostrar Aprovado sem recarregar a página, e depois de atualizar continua Aprovado.' O segundo é um teste. O primeiro é um humor.

• Dados três pedidos pendentes, a lista mostra o de início mais antigo primeiro.
• Quando eu escolho o filtro Recusado, só sobram linhas recusadas e o contador do cabeçalho bate.
• Quando eu recuso um pedido, aparece o campo de justificativa e não consigo confirmar com ele vazio.
• Quando não existe nenhum pedido, vejo a mensagem de vazio e nenhum cabeçalho de tabela.
• Quando entro como colaborador, não vejo os botões Aprovar nem Recusar.

O StarBuild roda typecheck, lint, build e um teste no navegador a cada mudança e mostra um recibo, o que diz que a coisa roda. Não diz que ela está certa. Isso quem diz são os seus critérios, então escreva como se fosse você quem vai dar o aceite.

Itere no chat

Trate a primeira versão como rascunho. Abra o preview, percorra os critérios um por um e escreva cada correção como numa review: 'o selo de status deve ser verde para aprovado e cinza para pendente.' Uma mudança por mensagem é mais fácil de conferir e de desfazer. Todas as versões ficam guardadas, então dá para voltar quando um experimento der errado.

Uma segunda rodada realista é mais ou menos assim. Você clica e percebe que os pedidos aprovados caem para o fim da lista, o que esconde justamente o que o gestor quer conferir da semana passada. Escreve: 'mantenha os pendentes primeiro, mas ordene o resto pela data de início, o mais recente em cima.' Depois nota que uma recusa salva sem justificativa, o que quebra o seu próprio critério. Escreve isso também, em outra mensagem. Duas correções pequenas, dois diffs pequenos, e você sempre sabe qual delas causou a surpresa.

Quando o construtor errar, resista à vontade de reescrever a história inteira. Cite o critério que ele não cumpriu e diga o que você viu no lugar. Isso é um relato de bug, e relato de bug ele resolve bem.

Onde esses pedidos costumam dar errado

• Vago demais. 'Um dashboard bonito para o RH' dá licença para o construtor inventar tudo. Sai algo plausível e errado.
• Histórias demais de uma vez. Aprovação, calendário, saldo e notificação numa mensagem só viram um monte impossível de revisar. Uma história, olha, depois a próxima.
• Regra não dita. Tudo que o time 'já sabe', como prazo de antecedência ou quem cobre quem, precisa ser escrito, porque o construtor não estava na sua reunião de planejamento.
• Critério de sentimento. O que não dá para checar com um clique volta para reescrever.
• Pular o caminho triste. O caminho feliz sempre funciona na demo. Peça de propósito o salvamento que falha e a lista vazia.

Nada disso é novidade. É para isso que o refinamento sempre serviu. A diferença é que um colega de carne e osso perguntaria, e o construtor não pergunta, então as respostas têm de estar na mensagem antes de você enviar.