User stories foram formalizadas por Mike Cohn (User Stories Applied, 2004) e Kent Beck no movimento XP. Gherkin (Given/When/Then) foi popularizado pelo Cucumber e SpecFlow para BDD. A combinação story + acceptance criteria em Gherkin é hoje o formato dominante em equipes ágeis maduras. A virtude do formato é forçar três coisas: quem usa, o que quer, e por quê — sem isso, stories viram tarefas sem contexto que ninguém sabe como avaliar.
Template
# Story: [Título curto e ativo]
**ID:** US-NNN
**Epic:** [Link para epic ou tema maior]
**Sprint:** [Sprint planejado]
**Story Points:** [estimativa relativa]
**Priority:** Must / Should / Could / Won't
## User story (formato canônico)
> Como **[persona/usuário]**,
> eu quero **[capacidade]**,
> para que **[benefício/outcome]**.
### Exemplo concreto:
> Como **gerente de vendas**,
> eu quero **filtrar pedidos por intervalo de data**,
> para que **eu possa gerar relatórios mensais sem exportar tudo**.
## Contexto adicional
[1-2 parágrafos. Por que essa story importa? Há dependências?
Decisões de design relevantes? Links para PRD, mockups.]
## Acceptance Criteria (Gherkin / Given-When-Then)
### Cenário 1: [Caso feliz]
```gherkin
Given que estou logado como gerente de vendas
And o sistema tem pedidos nos últimos 30 dias
When eu seleciono o intervalo "últimos 7 dias"
And clico em "filtrar"
Then a lista mostra apenas pedidos dos últimos 7 dias
And os totais no rodapé refletem apenas esses pedidos
```
### Cenário 2: [Caso de borda — sem resultados]
```gherkin
Given que estou logado como gerente de vendas
And não há pedidos nos últimos 7 dias
When eu seleciono o intervalo "últimos 7 dias"
Then a lista mostra mensagem "Nenhum pedido neste período"
And os totais ficam zerados
```
### Cenário 3: [Caso de erro]
```gherkin
Given que estou logado como gerente de vendas
When eu seleciono uma data final ANTERIOR à data inicial
Then o botão "filtrar" fica desabilitado
And uma mensagem de erro é exibida: "Data final deve ser posterior à inicial"
```
## Out of scope
- [O que esta story NÃO cobre — para evitar scope creep]
- [Ex: relatório agregado mensal — outra story]
## Definition of Done (específica desta story)
- [ ] Código mergeado com aprovação de revisor
- [ ] Testes unitários cobrindo cenários acima
- [ ] Teste E2E do cenário 1 (caso feliz)
- [ ] Mensagens em PT-BR e EN-US (i18n)
- [ ] Logs estruturados na rota
- [ ] Documentação atualizada (PRD ou Wiki interna)
- [ ] PM e design validaram em staging
## Dependencies
- [Outra story bloqueante: US-XXX]
- [Decisão pendente: ADR-YYY]
## Notas técnicas
- [Considerações especiais de performance, segurança, etc.]
- [Sugestão de implementação se útil — sem amarrar engenharia]
Bill Wake propôs o critério INVEST para boas user stories: Independent (não depende crítica de outra), Negotiable (detalhes ajustáveis), Valuable (entrega valor real), Estimable (time consegue estimar), Small (cabe em um sprint), Testable (acceptance criteria verificáveis). Story que falha em qualquer letra precisa revisão antes de entrar em sprint.
Referências
- Mike Cohn, User Stories Applied: For Agile Software Development (2004)
- Cucumber — Gherkin reference
- Agile Alliance — INVEST in Good Stories (Bill Wake)
- Dan North, Introducing BDD (2006) — origem de Given/When/Then