diff --git a/agents/ag-agente/persona.md b/agents/ag-agente/persona.md index 1e96e6c..4d18f80 100644 --- a/agents/ag-agente/persona.md +++ b/agents/ag-agente/persona.md @@ -236,3 +236,15 @@ Algumas aparentes sobreposições são **intencionais**: - [ ] As fronteiras de escopo entre agentes continuam não sobrepostas? - [ ] As colaborações (recebe de / entrega para) formam um grafo coerente sem ciclos? - [ ] Conteúdo repetido em mais de um agente foi movido para `global/rules/`? + +## Checklist de feedback visível (verificar em qualquer implementação auditada) + +Todo agente ao revisar código deve garantir que feedbacks importantes não fiquem ocultos: + +- [ ] **Frontend:** todo `catch` resulta em mensagem visível ao usuário? Nenhum erro é engolido silenciosamente? +- [ ] **Frontend:** estados de loading, erro e vazio estão explícitos na UI? Nunca fica preso em carregamento silencioso? +- [ ] **Backend:** toda exceção capturada tem `console.error()` ou `console.warn()` com contexto (operação + ID + erro)? +- [ ] **Backend:** erros internos são traduzidos antes de chegar ao cliente? Stack trace nunca vaza para o frontend? +- [ ] **Fila (se aplicável):** há handler configurado para `failed` e `error` nos jobs? Falhas de jobs são registradas com jobId, tentativas e payload relevante? + +> Referência: `global/rules/feedback-visivel.md` diff --git a/global/rules/feedback-visivel.md b/global/rules/feedback-visivel.md new file mode 100644 index 0000000..87129cb --- /dev/null +++ b/global/rules/feedback-visivel.md @@ -0,0 +1,130 @@ +--- +type: rule +name: feedback-visivel +description: Feedbacks importantes nunca ficam ocultos — devem ser visíveis no front, no console e no log de fila. +scope: global +trigger: always_on +updatedAt: "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** | `@ag-front` + `@ag-ux` | Toast, banner, mensagem inline, estado de erro visível | +| **Backend** | `@ag-back` | `console.error()` / `console.warn()` com contexto suficiente | +| **Log de fila** | `@ag-back` + `@ag-deploy` | Registrar falha no job com payload + stack trace | + +--- + +## Exemplos + +### ✅ Correto — frontend mostra, backend registra + +```ts +// 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') +} +``` + +```ts +// frontend +catch (erro) { + mensagem.value = extrairMensagemErro(erro) // nunca silenciar + mostrarFeedback('erro', mensagem.value) +} +``` + +### ❌ Errado — engolir o erro silenciosamente + +```ts +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 + +```ts +// frontend +catch (erro) { + alert(erro.stack) // nunca expor stack trace ao usuário +} +``` + +### ✅ Correto — log de fila (BullMQ) + +```ts +// 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 (`@ag-front` + `@ag-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 (`@ag-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 (`@ag-back` + `@ag-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/ag-front/persona.md` (estados de UI) +- Persona: `agents/ag-back/persona.md` (tratamento de erros) +- Persona: `agents/ag-ux/persona.md` (feedback imediato como princípio) diff --git a/manifesto.json b/manifesto.json index 0d6e8fd..7082486 100644 --- a/manifesto.json +++ b/manifesto.json @@ -1,12 +1,13 @@ { "versao": "2.0.0", "base_url": "https://paiol.idz.one/desenvolvimento/agent-ia", - "gerado_em": "2026-06-18T19:14:27-03:00", + "gerado_em": "2026-06-18T19:24:02-03:00", "artefatos": { "global": { "rules": [ "global/rules/autonomia-agente.md", "global/rules/carta-principios-agente-azteca.md", + "global/rules/feedback-visivel.md", "global/rules/fronteiras-monorepo.md", "global/rules/limite-linhas.md", "global/rules/regras-negocio-md.md",