Como ler e escrever User Stories

Nível: Iniciante | Duração estimada de leitura: 15 minutos | Categoria: Trilha Iniciante — Módulo 2

Introdução

Era uma terça de tarde, refinamento com o time. A PO abriu o card no Jira e leu em voz alta:

"Eu, como usuário, quero ver meus pedidos, para que eu possa acompanhá-los."

Silêncio.

Então o dev sênior falou: "Tá, mas o que exatamente ele precisa ver? Todos os pedidos? Só os ativos? Tem filtro? Tem paginação? O que acontece se não tiver pedido nenhum?"

A PO olhou para o card. Não tinha resposta para nenhuma dessas perguntas.

Essa cena acontece em todo time que confunde a User Story com o requisito completo. A fórmula existe. O conteúdo falta.

Neste módulo, você vai aprender a escrever histórias que chegam ao refinamento com contexto, saem com clareza e vão ao desenvolvimento sem retrabalho.

O que é (e o que não é) uma User Story

Antes de escrever, você precisa entender o que está criando.

User Story não é um documento de requisitos. Não é uma especificação técnica. Não é uma lista de funcionalidades. Não é uma tarefa para o desenvolvedor.

User Story é uma promessa de conversa.

O conceito foi criado por Ron Jeffries, um dos signatários do Manifesto Ágil, que descreveu a User Story como tendo três componentes — o que ele chamou de 3 Cs:

Card — O cartão com a descrição resumida. É o lembrete, não o requisito completo.

Conversation — A conversa que acontece entre PO, time e stakeholders para refinar o entendimento. O cartão é o ponto de partida dessa conversa, não o fim.

Confirmation — Os critérios de aceitação que confirmam quando a história está pronta e funcionando como esperado.

A maioria dos POs escreve o Card, esquece a Conversation e deixa a Confirmation vaga. Aí o retrabalho começa.

A fórmula clássica: Eu, Quero, Para

A estrutura mais conhecida de User Story é simples:

Eu, como [persona ou papel], Quero [ação ou funcionalidade], Para que [benefício ou resultado esperado].

Cada parte tem uma função específica.

"Eu, como [persona]" — Identifica quem é o usuário que se beneficia da história. Não é o sistema. Não é a empresa. É uma pessoa real com um contexto real. "Eu, como cliente que faz compras frequentes" é diferente de "Eu, como usuário". O contexto importa.

"Quero [ação]" — Descreve o que o usuário quer fazer, não o que o sistema precisa fazer. "Quero filtrar meus pedidos por status" está centrado no usuário. "O sistema deve exibir filtros de pedido" está centrado na implementação. A diferença parece pequena, mas muda o foco de quem escreve e de quem lê.

"Para que [benefício]" — Este é o elemento mais negligenciado e o mais importante. Ele responde ao "por quê". Quando o time entende o benefício esperado, consegue tomar decisões melhores durante o desenvolvimento. Se a história mudar de direção, o "para que" é o norte que mantém todos alinhados ao objetivo real.

Mas atenção: a fórmula é só o começo.

Por que a fórmula sozinha não basta

"Eu, como cliente, quero filtrar meus pedidos, para acompanhá-los melhor."

Ok. Mas o que acontece quando o cliente aplica um filtro e não tem resultado? O sistema mostra tela em branco? Uma mensagem? Qual mensagem?

O que acontece se o cliente tiver 500 pedidos? Tem paginação? Quantos por página?

O que "filtrar" significa aqui? Por data? Por status? Por produto? Tudo ao mesmo tempo?

A fórmula captura a intenção. Os critérios de aceitação definem o que "pronto" significa. Os cenários de homologação mostram como validar que funcionou.

Sem esses três elementos juntos, a história é uma promessa sem contrato.

Os 5 elementos de uma história completa

As histórias que chegam ao desenvolvimento sem retrabalho têm sempre os mesmos cinco componentes. Veja cada um.

1. Situação Atual — A Dor

Antes de descrever o que vai ser construído, descreva o que está errado hoje.

Por quê? Porque o time precisa entender o contexto do problema para tomar boas decisões. Se o dev sabe que o problema é que clientes ligam para o SAC porque não conseguem achar pedidos antigos, ele pensa diferente do que se souber apenas "precisa ter filtro".

Uma boa descrição da dor:

• É específica, não genérica
• Quantifica o impacto quando possível (volume de atendimentos, tempo perdido, taxa de erro)
• Conecta o problema ao usuário real e ao negócio

Ruim: "O processo atual tem problemas."

Bom: "Clientes que realizam mais de 5 compras por mês precisam rolar manualmente toda a lista de pedidos para encontrar um item específico. Isso gera frustração e aumenta o volume de contatos no SAC com perguntas sobre pedidos já entregues."

2. Objetivo da Tarefa — O Valor de Negócio

Depois de descrever o problema, descreva o que vai ser construído e por que isso resolve o problema. Aqui você conecta a solução ao resultado esperado para o negócio. Não só "vamos fazer X" — mas "vamos fazer X porque isso vai impactar Y".

Quando o time entende o valor de negócio, deixa de ser executor de tarefas e passa a ser co-responsável pelo resultado.

3. A História de Usuário — Eu / Quero / Para

Aqui entra a fórmula clássica — agora com contexto. Com a dor e o objetivo já descritos, a história resume a essência do que o usuário precisa de forma clara e centrada na pessoa.

4. Critérios de Aceitação — O que "pronto" significa

Este é o coração da história. Aqui você define, em linguagem não técnica, tudo que o sistema precisa fazer para a história ser considerada completa.

Um critério de aceitação bem escrito é:

• Testável — Alguém consegue verificar se está funcionando sem interpretação
• Específico — Sem margem para ambiguidade ("deve funcionar corretamente" não é critério)
• Focado no comportamento — Descreve o que o sistema faz em resposta a uma ação do usuário

Organize em Requisitos (REQ) e Sub-Requisitos (Sub-REQ):

• REQ define a funcionalidade de alto nível: o quê
• Sub-REQ detalha as regras de negócio: o como

Perceba que cada Sub-REQ deve ser verificável. Ou está certo ou está errado. Sem interpretação.

5. Cenários de Homologação — BDD

O BDD — Behavior-Driven Development — é uma forma de escrever cenários de teste em linguagem próxima do natural, usando a estrutura Dado / Quando / Então:

• Dado que o usuário está em uma situação específica
• Quando ele realiza uma ação
• Então o sistema deve se comportar de determinada forma

Esses cenários servem para dois públicos: o time de desenvolvimento, que sabe o que precisa construir; e o time de QA, que usa esses cenários como base para os testes de homologação.

Escreva cenários para os caminhos de sucesso e para os caminhos alternativos — erros, estados vazios, exceções. O que acontece quando o filtro não retorna nenhum resultado? Esses cenários revelam casos que muitas vezes não foram pensados até o momento do desenvolvimento.

Erros mais comuns — e como evitá-los

1. Escrever do ponto de vista do sistema, não do usuário

Errado: "O sistema deve exibir uma lista de pedidos com opção de filtro por status." Certo: "Eu, como cliente, quero filtrar meus pedidos por status, para encontrar rapidamente o que estou procurando."

2. Critérios vagos que não se pode testar

Errado: "O filtro deve funcionar corretamente e de forma intuitiva." Certo: "Ao selecionar o filtro 'Entregue', apenas pedidos com status 'Entregue' devem aparecer na lista. A atualização deve ocorrer em até 2 segundos."

Se você não consegue criar um teste para verificar o critério, ele não é um critério — é uma intenção.

3. Histórias gigantes disfarçadas de User Story

Uma história que leva mais de uma sprint para ser entregue provavelmente é um épico. Quebre em histórias menores, cada uma com valor independente. Sinal de alerta: mais de 10 Sub-REQs em uma única história.

4. Esquecer os cenários de erro

A maioria dos POs escreve o caminho feliz. Mas o que acontece quando a API cai? Quando o usuário não tem pedidos no período filtrado? Os cenários de erro são onde os bugs moram. Antecipe-os na história.

5. Não ter o "Para que"

Sem o benefício esperado, o time não tem bússola para decidir. Quando surgir uma dúvida durante o desenvolvimento — e vai surgir — a pergunta que resolve é sempre: "qual era o objetivo do usuário?"

O que separa uma história boa de uma ruim

Uma boa User Story passa no teste INVEST:

• I — Independent: Pode ser desenvolvida sem depender de outra história em progresso.
• N — Negotiable: Os detalhes de implementação ainda podem ser discutidos com o time.
• V — Valuable: Entrega valor real para o usuário ou para o negócio.
• E — Estimable: O time consegue estimar o esforço necessário.
• S — Small: É pequena o suficiente para caber em uma sprint.
• T — Testable: Os critérios de aceitação permitem verificar claramente se está pronto.

Exemplo completo: a história no padrão profissional

Agora que você conhece os componentes, veja como tudo isso se une em um exemplo fictício — usando o padrão que POs experientes aplicam no dia a dia.

A história abaixo é de uma empresa de e-commerce fictícia chamada Mercaloop. O contexto: o time de produto identificou alto volume de contatos no SAC de clientes que não conseguiam encontrar pedidos antigos no aplicativo.

[MLP-42] História: Filtro de Pedidos por Status no Aplicativo do Cliente

Situação atual (Dor)

Atualmente, a tela "Meus Pedidos" do aplicativo exibe todos os pedidos do cliente em ordem cronológica, sem nenhuma opção de filtro ou busca.

Comentário para o PO: descreva aqui a dor de forma específica. Quanto mais você quantificar o problema, mais o time entenderá a urgência e o impacto da solução.

Clientes que realizam compras recorrentes precisam rolar manualmente por dezenas de pedidos para localizar um item específico. Essa fricção gera frustração e aumenta o volume de atendimentos no SAC — aproximadamente 18% dos contatos registrados no último trimestre foram de clientes perguntando sobre o status de pedidos já entregues.

A ausência de filtro impacta diretamente a experiência pós-compra e sobrecarrega a operação de atendimento com demandas que poderiam ser resolvidas pelo próprio cliente no app.

Objetivo da tarefa (Contexto e valor agregado ao negócio)

Implementar um sistema de filtro por status na tela "Meus Pedidos" do aplicativo Mercaloop.

Comentário para o PO: conecte a solução ao resultado esperado. O time precisa saber por que aquilo importa para o negócio, não só o que precisa ser feito.

O objetivo é permitir que o cliente localize qualquer pedido de forma autônoma, filtrando por status: Em andamento, Entregue ou Cancelado. Com isso, esperamos reduzir o volume de contatos no SAC relacionados a status de pedido e melhorar a avaliação de experiência pós-compra no aplicativo.

História de Usuário

Comentário para o PO: a fórmula "Eu / Quero / Para" deve ser específica. Evite personas genéricas como "usuário" — prefira descrever o contexto real de quem se beneficia.

Eu, como cliente que realiza compras frequentes no aplicativo Mercaloop,

Quero filtrar o meu histórico de pedidos por status (Em andamento, Entregue ou Cancelado),

Para que eu possa encontrar rapidamente um pedido específico sem precisar navegar por toda a lista manualmente.

Links Importantes (Documentações, Figma, Fluxogramas...)

Comentário para o PO: centralize aqui todos os artefatos relacionados à história. O time de desenvolvimento não deve precisar caçar informação em outros lugares.

• Protótipo de Alta Fidelidade (Figma): [Link do protótipo — Fluxo de Filtro de Pedidos]
• Documentação da Regra de Negócio (Confluence): [Link do DOC — Política de Exibição de Pedidos por Status]
• Dependência (API): [Link da Task — API de Consulta de Pedidos por Cliente]
• Épico Relacionado: [Link do Épico — Experiência do Cliente Pós-Compra]

Critérios de Aceitação

Requisitos de história

Comentário para o PO: os REQs definem as funcionalidades — o "O quê". Os Sub-REQs definem as regras de negócio — o "Como". Cada Sub-REQ deve ser verificável: ou está certo ou está errado, sem interpretação possível.

REQ 1 — Exibição e Seleção dos Filtros (Os REQs definem as Funcionalidades — "O quê")

• Sub-REQ 1.1: (Os Sub-REQs definem as Regras de Negócio — "O como") Na tela "Meus Pedidos", o cliente deve ver opções de filtro no topo da lista, com as seguintes opções: "Todos", "Em andamento", "Entregue" e "Cancelado".
• Sub-REQ 1.2: O filtro padrão ao abrir a tela deve ser "Todos", exibindo todos os pedidos sem restrição.
• Sub-REQ 1.3: Apenas um filtro pode estar ativo ao mesmo tempo. Ao selecionar um novo filtro, o anterior é automaticamente desativado.
• Sub-REQ 1.4: O filtro ativo deve ter destaque visual diferenciado (ex: fundo colorido ou borda em destaque) em relação aos filtros inativos.

REQ 2 — Resultado da Filtragem

• Sub-REQ 2.1: Ao selecionar um filtro, a lista deve ser atualizada imediatamente — sem necessidade de clique em botão "Aplicar" —, exibindo apenas os pedidos com o status correspondente.
• Sub-REQ 2.2: Se o filtro selecionado não retornar nenhum pedido, o sistema deve exibir a mensagem: "Você não tem pedidos com este status no momento.", acompanhada de um ícone ilustrativo.
• Sub-REQ 2.3: A atualização da lista deve ocorrer em no máximo 2 segundos após a seleção do filtro.

REQ 3 — Persistência do Filtro na Sessão

• Sub-REQ 3.1: O filtro selecionado deve ser mantido durante a sessão ativa. Se o cliente navegar para o detalhe de um pedido e retornar à tela "Meus Pedidos", o filtro ativo deve ser o mesmo de quando saiu.
• Sub-REQ 3.2: Ao fechar e reabrir o aplicativo, o filtro deve voltar para o estado padrão "Todos".

Sugestões Técnicas (Apoio ao Desenvolvimento)

Comentário para o PO: esta seção é opcional, mas muito valorizada pelo time. Aqui você oferece um ponto de partida técnico — não uma especificação fechada. Valide sempre com o Tech Lead antes de assumir que as sugestões são corretas.

Importante: As informações abaixo são sugestões de ponto de partida para a equipe de desenvolvimento e devem ser validadas e/ou refinadas em conjunto com os Tech Leads e o time.

Mapeamento de Dados (Sugestão de Origem)

• Pedidos (REQ 1): Os pedidos para exibição podem ser consultados na tabela TBL_PEDIDO_HEADER, filtrando por ID_CLIENTE e STATUS_PEDIDO.
• Status disponíveis (REQ 1.1): Os status utilizados no filtro devem corresponder aos valores existentes no campo STATUS_PEDIDO: 'EM_ANDAMENTO', 'ENTREGUE', 'CANCELADO'.

Cenários de Homologação (BDD)

Comentário para o PO: escreva cenários para o caminho feliz E para os caminhos alternativos. Estados vazios, erros e exceções são onde os bugs aparecem — antecipe-os aqui.

Cenário 1.1 (Sucesso — Filtro com Resultado)

• Dado que eu sou um cliente logado e acessei "Meus Pedidos".
• E eu tenho pedidos com diferentes status (Em andamento, Entregue e Cancelado).
• Quando eu clico no filtro "Entregue".
• Então o sistema deve exibir apenas os pedidos com status "Entregue".
• E o filtro "Entregue" deve estar com destaque visual ativo.
• E os filtros "Em andamento" e "Cancelado" devem estar visualmente inativos.

Cenário 1.2 (Estado vazio — Filtro sem Resultado)

• Dado que eu sou um cliente logado e acessei "Meus Pedidos".
• E eu não tenho nenhum pedido com status "Cancelado".
• Quando eu clico no filtro "Cancelado".
• Então o sistema deve exibir a mensagem: "Você não tem pedidos com este status no momento."
• E um ícone ilustrativo deve ser exibido junto à mensagem.
• E a mensagem de erro genérico de sistema não deve ser exibida.

Cenário 2.1 (Persistência durante a sessão)

• Dado que eu sou um cliente logado e selecionei o filtro "Em andamento" na tela "Meus Pedidos".
• E a lista exibe apenas pedidos com status "Em andamento".
• Quando eu navego para o detalhe de um pedido e depois pressiono "Voltar".
• Então o filtro "Em andamento" deve continuar ativo.
• E apenas pedidos com status "Em andamento" devem ser exibidos, sem recarregar o filtro padrão "Todos".

Fim do exemplo

Conclusão

User Stories são simples de entender e difíceis de escrever bem. A fórmula cabe em uma linha. O trabalho real está nos critérios, nos cenários, no contexto que você coloca antes e depois da fórmula.

A diferença entre uma história que paralisa o time em dúvidas e uma que vai do refinamento ao deploy sem retrabalho está no quanto o PO trabalhou antes do refinamento. Quanto mais claro você for no papel, mais rápido e melhor o time entrega.

Lembra do refinamento do começo deste módulo? A PO que não tinha resposta para nenhuma pergunta do dev? Com o padrão que você acabou de ver, esse cenário muda completamente. O dev abre o card, lê a dor, entende o objetivo, vê os critérios e já sabe o que construir — inclusive o que acontece quando dá errado.

Isso é uma User Story que funciona.

No próximo módulo, vamos falar sobre backlog: como organizar, priorizar e manter uma lista de histórias que reflete a estratégia do produto — e não só a demanda do stakeholder que gritou mais alto.

Até lá.