User stories: exemplos e critérios de aceitação.
Edvaldo Freitas
Uma user story descreve o comportamento que uma funcionalidade precisa entregar: quem é o usuário, o que ele precisa fazer e qual resultado espera alcançar.
O problema é que esse contexto muitas vezes fica separado do pull request. A tarefa está no Jira, no Linear ou em outro sistema de gestão, enquanto a revisão acontece no Git. Quando o PR chega sem uma descrição clara ou sem link para a tarefa, quem revisa precisa descobrir pelo diff qual era o comportamento esperado.
Isso deixa o review mais fraco. O time ainda consegue olhar estilo, testes, arquitetura e possíveis bugs, mas perde parte do contexto que explica por que aquela mudança existe. Uma boa user story ajuda justamente nisso: ela transforma o comportamento esperado em critérios que podem ser usados para implementar, testar e revisar a entrega.
Com a Kodus, esse contexto também pode entrar no fluxo de revisão. A Kody pode usar a tarefa, a especificação ou os critérios de aceite para comparar o PR com as regras de negócio e apontar lacunas antes do merge. Vou explicar como você pode fazer isso durante o artigo.
O que é uma user story
Uma user story é uma descrição curta de uma necessidade do usuário. O formato mais comum é:
Como [tipo de usuário], eu quero [ação] para [benefício].Exemplo:
Como cliente recorrente, eu quero visualizar meu histórico de compras para recomprar itens sem procurar tudo de novo.Esse formato ajuda o time a sair da tarefa técnica pura. Em vez de escrever apenas “criar tela de histórico”, a história mostra quem vai usar aquela tela e qual resultado a pessoa espera alcançar.
A diferença parece pequena, mas muda a conversa. “Criar tela de histórico” pode significar muita coisa. “Cliente recorrente quer recomprar itens” já sugere pedidos anteriores, filtros, produtos indisponíveis, mobile, dados da própria conta e estados vazios.
Quando user stories ajudam de verdade
User stories ajudam quando descrevem um comportamento que alguém consegue validar depois. Produto entende o que pediu, engenharia entende o recorte, QA sabe o que testar e quem revisa o PR sabe o que procurar.
Quando a história é preenchida só porque a ferramenta exige, ela vira ruído. Uma frase genérica como “como usuário, quero notificações” não ajuda muito na implementação e ajuda menos ainda no review. Cada pessoa pode entender uma coisa diferente.
Isso ficou mais importante com IA escrevendo código. Gerar código ficou mais barato, mas validar se aquele código deveria existir continua sendo o trabalho difícil. O gargalo não é só escrever mais rápido. É confiar no que entra em produção.
O que uma boa user story precisa ter
Uma boa user story tem três partes principais.
Persona: quem precisa da funcionalidade.
Ação: o que essa pessoa quer fazer.
Benefício: por que isso importa.
Exemplo fraco:
Como usuário, eu quero notificações.Exemplo melhor:
Como usuário de uma conta empresarial, eu quero escolher quais notificações recebo para acompanhar eventos importantes sem receber alertas irrelevantes.A segunda versão ainda é simples, mas dá mais contexto para o time. A partir dela, já dá para discutir tipos de evento, canais de notificação, frequência, permissões e exceções.
Modelos de user stories
Modelo clássico
Use quando a história é pequena e direta.
Como [persona], eu quero [ação] para [benefício].Exemplo:
Como cliente, eu quero visualizar o histórico de pedidos para acompanhar compras anteriores.Esse modelo funciona bem quando o comportamento esperado é conhecido e não depende de muitas regras de negócio.
Modelo com contexto de negócio
Use quando existe alguma regra, restrição ou detalhe que muda a forma de construir.
Como cliente recorrente, eu quero visualizar compras dos últimos 12 meses para encontrar pedidos anteriores e recomprar itens com menos esforço.Contexto:
O histórico deve mostrar apenas pedidos do usuário autenticado. Compras canceladas devem aparecer com status claro. A tela será usada principalmente no mobile.Esse contexto reduz ambiguidade. Também evita uma situação comum: produto esperava uma regra, engenharia implementou outra e o review não tinha contexto suficiente para perceber.
Modelo de épico
Um épico agrupa um trabalho maior. Ele ajuda a organizar o backlog, mas normalmente precisa ser dividido antes de virar desenvolvimento.
Exemplo de épico:
Como administrador, eu quero gerenciar perfis de usuários para controlar acesso dentro da plataforma.Esse épico pode virar histórias menores:
Como administrador, eu quero criar novos perfis de usuário.
Como administrador, eu quero editar permissões de perfis existentes.
Como administrador, eu quero desativar perfis que não devem mais ser usados.Histórias menores tendem a gerar PRs menores. PRs menores costumam ser mais fáceis de revisar com atenção.
Critérios de aceitação
Critérios de aceitação dizem o que precisa ser verdade para a história ser considerada pronta.
Exemplo de história:
Como cliente recorrente, eu quero visualizar meu histórico de compras para recomprar itens sem procurar tudo de novo.Critérios de aceitação:
1. O usuário deve acessar o histórico apenas depois de fazer login.
2. O histórico deve exibir compras dos últimos 12 meses.
3. Cada compra deve mostrar data, itens, quantidade e valor total.
4. O usuário deve conseguir filtrar por data e categoria.
5. A tela deve funcionar em dispositivos móveis.
6. O usuário não pode visualizar compras de outra conta.Esses critérios ajudam no desenvolvimento, nos testes e no review. No PR, cada critério vira uma checagem: a query limita o período? O backend filtra pelo usuário autenticado? O filtro lida com data vazia? Existe teste impedindo acesso a compras de outra conta?
O review sai do “parece ok” e passa a olhar evidência.
Como critérios de aceitação ajudam no code review
A user story não precisa ter uma seção chamada “code review”. A conexão acontece porque critérios bons geram perguntas boas durante a revisão.
Critério ruim:
O histórico deve funcionar corretamente.Critério melhor:
O histórico deve listar apenas compras do usuário autenticado realizadas nos últimos 12 meses.No code review, isso vira perguntas naturais:
A consulta filtra pelo ID do usuário autenticado?
O limite de 12 meses está aplicado no backend?
O frontend mostra estado vazio quando não há compras?
Há teste cobrindo tentativa de acesso a dados de outro usuário?Essas perguntas não precisam estar escritas no ticket. Elas nascem do critério. Esse é o ponto prático: uma user story bem escrita diminui a parte subjetiva do review, porque o PR passa a ser comparado com uma intenção explícita.
Exemplos de user stories com critérios de aceitação
Histórico de compras
História:
Como cliente recorrente, eu quero visualizar meu histórico de compras para acompanhar pedidos anteriores e recomprar itens com mais facilidade.Critérios de aceitação:
1. O usuário deve acessar o histórico pela área logada.
2. O histórico deve exibir compras dos últimos 12 meses.
3. Cada item deve incluir data, produto, quantidade, status e valor total.
4. O usuário deve filtrar o histórico por data e categoria.
5. Compras canceladas devem aparecer com status claro.
6. O histórico deve ser compatível com mobile.
7. O usuário não deve conseguir acessar compras de outra conta.No review, o time pode olhar se o backend filtra por usuário, se o período está aplicado no lugar certo, se a interface trata lista vazia e se existe cobertura para acesso indevido.
Preferências de notificações
História:
Como usuário de uma conta empresarial, eu quero configurar minhas preferências de notificações para receber apenas alertas relevantes para meu trabalho.Critérios de aceitação:
1. O usuário deve acessar as preferências pelo menu de configurações.
2. A tela deve permitir ativar ou desativar tipos específicos de notificação.
3. As alterações só devem ser salvas ao clicar em "Salvar preferências".
4. O sistema deve confirmar visualmente que as preferências foram salvas.
5. Novas notificações devem respeitar as preferências atualizadas.
6. Preferências de um usuário não devem afetar outros usuários da mesma conta.No review, o time pode checar se as preferências são salvas por usuário, se erro de salvamento tem tratamento, se notificações futuras usam a nova configuração e se uma conta não vaza configuração para outra.
Recuperação de senha
História:
Como usuário, eu quero redefinir minha senha quando esquecê-la para recuperar acesso à minha conta sem criar um novo cadastro.Critérios de aceitação:
1. O usuário deve solicitar recuperação pela tela de login.
2. O sistema deve enviar um link seguro por e-mail.
3. O link deve expirar em 24 horas.
4. O link só pode ser usado uma vez.
5. A nova senha deve seguir a política mínima de segurança.
6. Após redefinir a senha, o usuário deve receber confirmação.
7. Tokens expirados ou inválidos devem retornar mensagem segura, sem expor dados da conta.No review, o time pode olhar expiração, uso único do token, armazenamento seguro, política de senha e respostas que não revelem se uma conta existe.
Template de user story em markdown
Se o time ainda não tem um padrão, comece simples. O template deve ajudar a escrever melhor, não virar burocracia.
# User story
## História
Como [persona ou tipo de usuário], eu quero [ação ou funcionalidade] para [benefício esperado].
## Contexto
[Explique o problema, regra de negócio ou cenário que levou à criação desta história.]
## Critérios de aceitação
1. [Comportamento esperado e testável]
2. [Regra, restrição ou permissão importante]
3. [Estado de erro, vazio ou exceção relevante]
## Regras de negócio
- [Regra obrigatória que o código deve respeitar]
- [Limite, permissão, cálculo, exceção ou comportamento esperado]
## Casos de borda
- [Cenário incomum que precisa ser tratado]
- [Estado vazio, erro, duplicidade, limite ou conflito]
## Fora de escopo
- [O que esta história não deve resolver]
- [Funcionalidade relacionada que ficará para outra tarefa]
## Observações técnicas
- [Dependências, limitações ou decisões técnicas relevantes]
- [Links para design, documentação, API, issue relacionada ou conversa importante]
## Perguntas em aberto
- [Decisão que ainda precisa ser tomada]
- [Dependência de produto, design, dados ou engenharia]O template não precisa ter checklist de code review. A revisão vem depois, quando alguém compara o PR com os critérios e regras descritos na história.
Como usar user stories no code review com IA
Uma user story bem escrita pode alimentar a revisão de código. O PR deixa de ser avaliado só pelo diff e passa a ser avaliado contra a intenção da tarefa.
Na Kodus, a Kody pode usar contexto de ferramentas como Jira, Linear, Notion, ClickUp, Google Docs, Slack ou de uma especificação colada diretamente no comentário do PR. Quando a validação de regras de negócio está habilitada, a Kody compara o diff do pull request com os requisitos da tarefa e sinaliza problemas antes do merge.
Exemplo com uma tarefa externa:
@kody -v business-logic https://linear.app/time/issue/PROJ-123Exemplo com requisitos inline:
@kody -v business-logic
Usuários admin podem cancelar pedidos pendentes.
Pedidos já enviados não podem ser cancelados.
O cliente deve receber uma notificação quando o cancelamento for concluído.Nesse fluxo, a user story vira uma referência objetiva para validar o PR. A Kody pode verificar se o código cobre os critérios de aceitação, se há requisitos atendidos só pela metade, se o PR saiu do escopo da tarefa e se algum caso de borda descrito não aparece no diff.
Usando MCP e plugins
Muitas histórias não estão no Git. Elas estão em Jira, Linear, Notion, Google Docs, Slack ou ferramentas internas. O PR nem sempre carrega esse contexto.
Plugins baseados em MCP trazem esse contexto para o review. Na Kodus, plugins são servidores Model Context Protocol que expõem capacidades específicas para a Kody, como buscar uma tarefa, ler uma spec ou consultar uma fonte interna autorizada.
Todo workspace conta com o Kodus MCP conectado para os provedores Git suportados. Times também podem conectar plugins do catálogo ou adicionar servidores MCP próprios quando precisam buscar contexto em sistemas internos.
O fluxo fica assim:
1. Produto escreve a user story com critérios de aceitação.
2. O desenvolvedor abre um PR ligado à tarefa.
3. A Kody busca o contexto pelo plugin conectado.
4. A Kody compara o diff com os requisitos.
5. O review aponta lacunas rastreáveis antes do merge.A validação melhora quando a história tem critérios claros. Se a tarefa tem só um título vago, a análise fica limitada. Se ela tem descrição, regras e critérios de aceite, o review consegue ser mais objetivo.
Como escrever user stories melhores para validação
Escreva pensando no comportamento que alguém poderá verificar depois.
Critério vago:
O checkout deve ser rápido.Critério verificável:
O checkout deve concluir o pagamento em até 3 segundos após confirmação do provedor.Regra de permissão:
Apenas usuários com papel admin podem cancelar pedidos de outros usuários.Caso de borda:
Se o pedido já foi enviado, o cancelamento deve ser bloqueado.Estado vazio:
Se não houver compras no período, a tela deve mostrar uma mensagem vazia com opção de limpar filtros.Frases como “a experiência deve ser intuitiva” podem orientar design, mas ajudam pouco na hora de validar código. Se ninguém consegue provar no PR, o critério ainda está abstrato demais.
Checklist antes do desenvolvimento
Antes de uma história entrar em desenvolvimento, vale checar:
A persona está clara?
A ação esperada está específica?
O benefício explica o motivo da mudança?
Os critérios de aceitação são testáveis?
Existem regras de permissão?
Existem casos de borda?
Existem estados de erro ou vazio?
A história está pequena o suficiente para caber em um PR revisável?
O link da tarefa estará disponível no PR?Esse checklist não é parte obrigatória da user story. É só uma forma prática de descobrir se a tarefa tem contexto suficiente antes de virar código.
Conclusão
Uma boa user story ajuda o time a preservar contexto até a entrega. Ela deixa claro quem precisa da funcionalidade, qual comportamento precisa existir e como o time vai saber que aquilo ficou pronto.
Quando esses pontos aparecem com clareza, o code review melhora. O revisor não olha só se o código compila ou se os testes passaram. Ele consegue comparar a mudança com o comportamento esperado.
Com a Kodus, esse contexto pode chegar ao review de forma mais direta. A Kody pode usar tarefas, specs e critérios de aceitação para validar pull requests contra regras de negócio, especialmente quando o time conecta suas fontes de contexto por plugins e MCP.