User Stories definem o comportamento esperado do sistema na perspectiva de quem o usa. São a fonte que alimenta telas, fluxos, entidades e contratos — se a história está vaga, tudo que vem depois nasce vago.
Fase: 2 — Requisitos
Pré-requisito: Docs/project.md aprovado
Template: Templates/Full/user-stories.md ou Templates/Quick/user-stories.md
Artefato oficial: Docs/user-stories.md
Próximos artefatos: Docs/pages.md · Docs/flow.md · Docs/entities.md
Quando criar ou revisar
- Após aprovação de
Docs/project.md - Novo módulo ou jornada identificada
- Mudança de escopo que afeta comportamento do usuário
- Discovery que revelou necessidade não mapeada
Full vs Quick
| Situação | Template |
|---|---|
| Produto com múltiplos perfis, jornadas e edge cases | Templates/Full/user-stories.md |
| Feature pontual com contexto já compartilhado | Templates/Quick/user-stories.md |
| Ambiguidade surgiu durante o Quick | Migrar para Full na mesma task |
Regra de escrita de toda história
Como [perfil]
quero [ação / capacidade]
para [benefício / valor gerado]Cada história deve conter além da frase:
- Contexto — quando essa necessidade aparece
- Valor gerado — o que o usuário ou o negócio ganha
- Pré-condições — o que precisa ser verdade antes
- Pós-condições — o que se espera após a ação
- Critérios de aceite — verificáveis, não subjetivos
- Edge cases — o que acontece nos casos limítrofes
- Dependências — histórias que precisam existir antes
Estrutura — User Stories Full
O template Full tem 12 seções.
1. Identificação
Nome do projeto:
Versão do documento:
Status: [rascunho | revisando | aprovado]
Documento base: Docs/project.md
Data de criação:
Última atualização:2. Objetivo do Documento
Define o que Docs/user-stories.md cobre e o que não cobre:
Cobre: perfis, histórias, objetivos funcionais, critérios de aceite, dependências, prioridades.
Não cobre: layout, arquitetura técnica, modelagem de entidades, contrato de API, tasks de implementação.
3. Perfis de Usuário
Para cada perfil relevante do projeto:
### Perfil N — [nome do perfil]
Descrição: [quem é esse usuário]
Objetivo principal: [o que ele quer alcançar]
Contexto de uso: [quando, como e em qual situação usa o sistema]
Principais dores:
- [dor 1]
- [dor 2]Dica
Defina no mínimo os perfis listados em Docs/project.md seção 5. Se um perfil não tiver objetivo claro, não crie histórias para ele — volte ao Project e esclareça antes.
4. Regras de Escrita das Histórias
Regras que toda história do projeto deve seguir (definidas na seção 4 do template):
- Estrutura "Como / quero / para" obrigatória
- Critério de aceite sempre verificável
- Contexto explicitado
- Edge cases mapeados quando relevantes
- Dependências funcionais declaradas
5. Histórias de Usuário
Estrutura completa de cada história (US-001, US-002, ...):
### US-001 — [título da história]
Perfil: [perfil principal]
História:
Como [perfil], quero [ação], para [benefício].
Objetivo funcional:
[o que essa história precisa entregar na prática]
Valor gerado:
[qual valor real isso entrega ao usuário ou ao negócio]
Contexto:
[quando essa necessidade aparece]
Pré-condições:
- [pré-condição 1]
Pós-condições esperadas:
- [resultado 1]
Critérios de aceite:
- [critério verificável 1]
- [critério verificável 2]
Exceções / edge cases:
- [edge case 1]
Dependências:
- [US-XXX ou artefato]
Prioridade: [alta | média | baixa]
Observações: [preencher]6. Agrupamento por Jornada / Módulo
Após escrever as histórias individuais, agrupá-las em jornadas ou módulos:
### Jornada / Módulo: [nome]
Objetivo da jornada: [descreva]
Histórias relacionadas:
- US-001
- US-0027. Priorização Inicial
Alta prioridade:
- US-001 — [título]
- US-002 — [título]
Média prioridade:
- US-003 — [título]
Baixa prioridade:
- US-004 — [título]
Justificativa da priorização:
[explique o critério — valor, risco, dependência estrutural ou desbloqueio]8. Dependências Funcionais Entre Histórias
Dependências conhecidas:
- US-002 depende de US-001
- US-004 depende de US-003
Bloqueios potenciais:
- [bloqueio 1]9. Regras Funcionais Transversais
Regras que afetam múltiplas histórias e não pertencem a uma única:
Regras transversais:
- [regra 1]
- [regra 2]
Permissões / restrições por perfil:
- [regra de acesso]
Estados comuns esperados no sistema:
- loading
- vazio
- erro
- sucesso
- sem permissão
- indisponibilidade externa10. Diretrizes para os Próximos Documentos
Docs/pages.md — quais telas precisam nascer dessas histórias
Docs/flow.md — quais jornadas e transições precisam ser modeladas
Docs/design-system.md — quais componentes ou padrões parecem necessários
Docs/tokens.json — necessidades de temas, escala ou semântica visual
Docs/entities.md — quais conceitos de domínio surgem dessas histórias
Docs/contract.yaml — quais capacidades de API ou integração são sugeridas
Docs/plan.md — histórias fundacionais, críticas ou com dependências11. Síntese Operacional para Dev e AI
Perfis principais:
- [perfil 1]
- [perfil 2]
Jornadas principais:
- [jornada 1]
- [jornada 2]
Histórias de maior prioridade:
- US-001
- US-002
O que precisa ser garantido na implementação:
- [garantia 1]
- [garantia 2]
O que ainda está indefinido:
- [ponto 1]12. Aprovação
Status: [pendente | aprovado | revisando]
Aprovado por:
Data de aprovação:
Observações finais:Exemplo preenchido — US completa
### US-007 — Registrar atendimento com foto e assinatura
Perfil: Técnico de campo
História:
Como técnico de campo, quero registrar o atendimento com foto do local
e assinatura do cliente, para ter comprovação da visita vinculada ao chamado.
Objetivo funcional:
Permitir que o técnico capture foto e colete assinatura digital no app mobile,
vinculando ambos ao chamado em andamento.
Valor gerado:
Comprova execução do serviço sem papel. Elimina contestações de atendimento.
Contexto:
Ao finalizar o trabalho no local — antes de marcar o chamado como concluído.
Pré-condições:
- Técnico autenticado no app
- Chamado no status "em andamento"
- Câmera e touch disponíveis no dispositivo
Pós-condições esperadas:
- Foto e assinatura vinculadas ao chamado no backend
- Chamado movido para status "aguardando confirmação"
Critérios de aceite:
- Foto deve ser tirada pela câmera do app (não galeria)
- Assinatura deve ser coletada via canvas touch
- Ambos devem ser enviados ao backend antes de avançar o status
- Timeout de upload exibe mensagem de erro com opção de reenvio
Edge cases:
- Câmera sem permissão → exibir instrução de ativação nas configurações
- Falha no upload → manter dados localmente e exibir opção de reenvio
- Cliente recusa assinar → campo opcional com justificativa obrigatória
Dependências:
- US-003 (autenticação do técnico)
- US-005 (abertura e consulta de chamado)
Prioridade: altaEstrutura — User Stories Quick
Para features pontuais com contexto já compartilhado:
## Perfis principais
- [perfil 1]
- [perfil 2]
## Histórias principais
### US-001 — [título]
Como [perfil]
quero [ação]
para [benefício]
Critérios de aceite:
- [critério verificável 1]
- [critério verificável 2]
Prioridade: [alta | média | baixa]
---
## Agrupamento por jornada
### [nome da jornada]
- US-001
- US-002
## Regras funcionais transversais
- [regra 1]
## Dependências entre histórias
- [dependência]
## Direção para os próximos documentos
Docs/pages.md: [orientação]
Docs/flow.md: [orientação]
Docs/entities.md: [orientação]
Docs/contract.yaml: [orientação]
## Síntese para Dev e AI
Perfis mais importantes: [perfil]
Histórias prioritárias: US-001, US-002
O que precisa funcionar bem: [item]
O que está indefinido: [ponto]Prompt para gerar com agente
Atue como ProductAgent.
Objetivo: criar Docs/user-stories.md com base em Docs/project.md
Carregue contexto base:
- GUIDE.md
- Skills/user-stories.md
- Templates/Full/user-stories.md
- Docs/project.md
Preencha as 12 seções do template Full.
Seção 3: defina todos os perfis do Docs/project.md seção 5.
Seção 5: crie as histórias com estrutura completa incluindo edge cases.
Seção 9: mapeie estados comuns (loading, vazio, erro, sucesso, sem permissão).
Seção 10: preencha orientação por artefato para os próximos documentos.
Critérios de aceite devem ser verificáveis — sem adjetivos subjetivos.
Marque [indefinido] onde houver lacuna.Definição de pronto
O user-stories está pronto quando:
- Todos os perfis de
Docs/project.mdtêm objetivo e contexto de uso documentados - Cada história tem estrutura "Como / quero / para" + critérios de aceite verificáveis
- Edge cases e pré-condições mapeados nas histórias de alta prioridade
- Seção 6 agrupa histórias em jornadas ou módulos
- Seção 9 lista estados comuns do sistema
- Seção 10 tem orientação objetiva por artefato seguinte
- Aprovação registrada na seção 12
Atenção
Critério de aceite como "funcionar bem" ou "carregar rápido" não é critério — é desejo. Substitua por: "carregar em menos de 1 segundo com 4G" ou "exibir spinner por até 3 segundos antes de mostrar mensagem de timeout".
Erros comuns
| Erro | Correção |
|---|---|
| História grande demais ("como usuário quero usar o sistema") | Quebrar em histórias menores por capacidade específica |
| Critério de aceite subjetivo | Usar verbo verificável: listar, exibir, redirecionar, salvar, validar |
| Descrever implementação em vez de necessidade | O "quero" deve ser comportamento do usuário, não decisão técnica |
| Edge cases ausentes | Mapear pelo menos: erro de rede, dado inválido, sem permissão |
| Perfil genérico ("usuário") | Nomear o perfil com contexto real: "técnico de campo", "gestor", "admin" |
| Seção 10 em branco | Cada artefato seguinte perde a orientação funcional do produto |
Documentos que nascem das User Stories
Docs/user-stories.md (aprovado)
↓
Docs/pages.md — telas derivadas das jornadas e histórias
Docs/flow.md — navegação e transições entre estados
Docs/entities.md — domínio e dados mapeados pelas histórias
Docs/contract.yaml — capacidades de API inferidas pelos critérios de aceite