.agent/rules/literatura-tecnica-e-usabilidade.md

type	name	description	scope	trigger	priority	updatedAt
rule	literatura-tecnica-e-usabilidade	Toda execução de prompt deve observar o que preconiza a literatura de tecnologia e as melhores práticas de desenvolvimento e usabilidade.	global	always_on	alta	2026-08-11

Regra: Embasamento em Literatura Técnica, Boas Práticas e Usabilidade

Contexto

Cada solicitação de funcionalidade, componente, API, fluxo ou refatoração deve ser planejada e executada com rigor técnico. O agente não deve criar soluções empíricas ou improvisadas sem consultar e aplicar os padrões consagrados da literatura de tecnologia, engenharia de software e usabilidade.

Diretrizes Obrigatórias para Toda Execução de Prompt

Em toda execução de prompt, o agente DEVE observar rigorosamente os três pilares fundamentais:

1️⃣ Observância da Literatura de Tecnologia (Rigor Técnico)

• Consenso da Indústria: Identificar e aplicar padrões e especificações formais de referência para o domínio da funcionalidade (ex.: GoF Design Patterns, Clean Architecture, Domain-Driven Design, RESTful APIs RFCs, 12-Factor App, OWASP Guidelines).
• Justificativa Baseada em Literatura: Projetar arquiteturas, estruturas e funções fundamentadas nas melhores referências teóricas e científicas consolidadas.
• Evitar Anti-patterns: Evitar explicitamente os anti-padrões catalogados na literatura (ex.: God Object, Spaghetti Code, Anemic Domain Model, Circular Dependencies, Feature Envy).

2️⃣ Boas Práticas de Desenvolvimento (Engenharia de Software)

• Princípios SOLID: Aplicar S (Single Responsibility), O (Open/Closed), L (Liskov Substitution), I (Interface Segregation) e D (Dependency Inversion).
• Clean Code & Manutenibilidade: Escrever código autoexplicativo, modular, de responsabilidade única e desacoplado.
• Tipagem Forte e Defensiva: Utilizar TypeScript e validação de schemas Zod para garantir integridade em runtime e compilação.
• Tratamento de Erros e Diagnóstico: Seguir a regra de diagnosticar a causa raiz antes de corrigir, tratando exceções de forma graciosa sem engolir erros.

3️⃣ Boas Práticas de Usabilidade e UX/UI (Experiência do Usuário)

• Heurísticas de Usabilidade (Nielsen):
  1. Visibilidade do estado do sistema (loading, feedback imediato).
  2. Correspondência entre o sistema e o mundo real (linguagem do domínio).
  3. Controle e liberdade do usuário (cancelamento, desfazer, confirmações).
  4. Consistência e padrões (componentes coesos do design system).
  5. Prevenção de erros (validação preventiva via Zod/form).
  6. Reconhecimento em vez de memorização (rótulos claros, contexto visível).
  7. Flexibilidade e eficiência de uso (fluxos fluidos, ações diretas).
  8. Estética e design minimalista (interface limpa, sem ruído).
  9. Diagnóstico e recuperação de erros (mensagens claras e orientadoras).
• Hierarquia Visual e Despoluição de UI (Refactoring UI — Steve Schoger & Adam Wathan):
  • Aplicar obrigatoriamente a regra global/rules/refactoring-ui-hierarquia-despoluicao (pirâmide de ações com apenas 1 primária sólida por vista, eliminação de bordas e cards aninhados, consolidação de colunas em tabelas, Lei da Proximidade no espaçamento e rótulos como último recurso).
  • Obra completa de referência para consulta: https://adm.paiol.idz.one/estaticos/Refactoring-UI-Steve-Schoger-Adam-Wathan.pdf
• Acessibilidade & Clareza Cognitiva: Respeitar padrões de acessibilidade (WCAG) e garantir interface responsiva com feedbacks compreensíveis.

Processo de Execução em 3 Etapas

1. Análise Téorico-Funcional: Mapear qual padrão ou especificação da literatura se aplica à funcionalidade solicitada.
2. Construção Segura: Codificar aplicando SOLID, tipagem estrita e diagnóstico prévio.
3. Validação de Usabilidade: Verificar se a interface e contratos atendem às heurísticas de UX e feedback visual.

Impacto

Garante soluções robustas, sustentáveis no longo prazo, escaláveis e alinhadas aos mais altos padrões globais de tecnologia e experiência do usuário.