.agent/rules/feedback-visivel.md

type	name	description	scope	trigger	updatedAt
rule	feedback-visivel	Feedbacks importantes nunca ficam ocultos — devem ser visíveis no front, no console e no log de fila.	global	always_on	2026-06-18

Regra: Feedback Visível em Todas as Camadas

Contexto

Erros silenciosos e feedback oculto são as piores formas de falha em um sistema. O usuário fica sem saber o que aconteceu, o desenvolvedor não consegue diagnosticar, e o operador não vê nada nos logs.

Esta regra exige que todo feedback relevante seja surfaceado na camada apropriada — sem exceção.

---

Regra

Todo evento relevante (erro, aviso, conclusão de processo, falha de validação) deve aparecer em pelo menos uma das camadas abaixo, e nas todas as camadas que tiverem acesso:

Camada	Responsável	Como
Frontend	@front + @ux	Toast, banner, mensagem inline, estado de erro visível
Backend	@back	console.error() / console.warn() com contexto suficiente
Log de fila	@back + @deploy	Registrar falha no job com payload + stack trace

---

Exemplos

✅ Correto — frontend mostra, backend registra

// backend
try {
  await processarLicenca(dados)
} catch (erro) {
  console.error('[licenca] Falha ao processar', { licencaId: dados.id, erro })
  throw new ErroOperacional('Não foi possível processar a licença')
}

// frontend
catch (erro) {
  mensagem.value = extrairMensagemErro(erro) // nunca silenciar
  mostrarFeedback('erro', mensagem.value)
}

❌ Errado — engolir o erro silenciosamente

try {
  await processarLicenca(dados)
} catch (_) {
  // silêncio — o usuário não sabe, o log não sabe
}

❌ Errado — mostrar erro técnico ao usuário

// frontend
catch (erro) {
  alert(erro.stack) // nunca expor stack trace ao usuário
}

✅ Correto — log de fila (BullMQ)

// processador de fila
processor.on('failed', (job, erro) => {
  console.error('[fila] Job falhou', {
    jobId: job.id,
    nome: job.name,
    tentativas: job.attemptsMade,
    erro: erro.message,
  })
})

---

Camadas e responsabilidades detalhadas

Frontend (@front + @ux)

• Todo catch deve resultar em feedback visível ao usuário
• Nunca usar catch (_) {} sem ao menos logar no console do browser
• Mensagens de erro para o usuário: linguagem do domínio, sem stack trace, sem IDs técnicos
• Estados de carregamento e erro devem ser explícitos na UI (não apenas esconder o spinner)
• Usar o padrão: loading → sucesso | erro, nunca ficar preso em "loading" silencioso

Backend (@back)

• Toda exceção capturada deve ser logada com contexto: qual operação, qual entidade, qual erro
• console.error() para erros operacionais; console.warn() para situações de atenção
• Nunca logar senhas, tokens ou dados pessoais
• O log deve incluir o suficiente para reproduzir o problema: IDs, parâmetros relevantes
• Erros internos não devem vazar para o cliente — traduzir para ErroOperacional ou equivalente

Fila (@back + @deploy)

• Se o sistema usa BullMQ, Redis ou similar: configurar handler de failed e error
• Jobs que falham devem ser registrados com: jobId, nome, tentativas, payload relevante, erro
• Falhas repetidas devem gerar alerta (monitoramento de job.failedReason)
• Nunca deixar um job falhar silenciosamente sem registro

---

Impacto

• Diagnóstico: sem log, nenhum problema pode ser investigado
• Confiança do usuário: feedback ausente = sistema parece travado ou bugado
• Operação: sem log de fila, jobs perdidos são invisíveis

---

Referências

• Rule: global/rules/mensagens-usuario (vocabulário para mensagens ao usuário)
• Persona: agents/front/persona (estados de UI)
• Persona: agents/back/persona (tratamento de erros)
• Persona: agents/ux/persona (feedback imediato como princípio)