tomozard/agent-skills

Guia de Padrões de Design Fullstack

Use esta skill para aconselhar, arquitetar e refatorar sistemas fullstack de ponta a ponta. Aplique padrões estritamente para resolver atritos arquiteturais identificáveis, não para abstração especulativa.

Princípios Centrais

1. Seleção Baseada em Problema: Nunca introduza um padrão de design sem um atrito arquitetural explícito ou code smell (ex.: prop drilling, god-components inchados, acoplamento de API, lógica não testável, falhas de rede em cascata).
2. Juntas Arquiteturais Claras: Mantenha limites nítidos entre:
   • View / Apresentação: Componentes burros e declarativos movidos por props.
   • Estado do Cliente e Interação: Hooks headless, stores centralizadas e cache de estado do servidor.
   • Camada de API / Contrato: Schemas tipados, adaptadores DTO e camadas de anticorrupção.
   • Domínio e Acesso a Dados: Regras de negócio desacopladas e acesso a banco de dados baseado em repositório.
3. Evite Superengenharia: Não aplique abstrações empresariais complexas (como micro-frontends, CQRS ou pub/sub distribuído) a páginas CRUD simples ou aplicativos web padrão.

---

Matriz de Decisão de Padrões e Heurísticas de Gatilho

Camada	Sintoma / Atrito no Código	Padrão Recomendado	Junta Arquitetural
Frontend UI	God-component misturando busca de API, formatação e layout JSX	Container / Presentational	Separar renderização de UI da busca de dados
Frontend UI	Estilos fortemente acoplados dentro de componentes interativos (modais, dropdowns)	Componente Headless / Custom Hooks	Isolar estado e lógica de interação/teclado
Frontend UI	APIs de componentes rígidas exigindo subelementos flexíveis	Componentes Compostos	Compartilhamento declarativo de estado pai-filho (ex.: Tabs, Select)
Frontend UI	Prop drilling profundo ou estados de UI de múltiplos componentes dessincronizados	Observer / Store (Zustand/Redux/Context)	Centralizar estado compartilhado do cliente
Fullstack API	Mudanças no schema da API backend quebram componentes da UI frontend	Padrão Adapter (Mapeador de Dados)	Camada de Anticorrupção traduzindo DTO para View Model
Fullstack API	UI aguarda redes lentas antes de confirmar ação do usuário	Optimistic UI com Rollback	Resposta imediata da UI apoiada por rollback transacional
Backend	Chamadas SQL/ORM espalhadas dentro de route handlers ou serviços	Padrão Repositório	Desacoplar consultas de persistência das regras de negócio
Backend	Instanciar diferentes SDKs de terceiros usando if-else inline	Padrão Factory	Centralizar criação de objetos e clientes
Backend	Cascateamento de if-else / switch para calcular preço, autenticação ou algoritmos	Padrão Strategy	Encapsular algoritmos intercambiáveis por trás de uma interface
Backend / Distribuído	Ação de negócio central aciona 5+ efeitos colaterais não relacionados	Observer / Event-Driven (Pub/Sub)	Desacoplar efeitos colaterais via eventos de domínio ou filas
Backend / Distribuído	Latência de API externa causando starvation de threads e downtime em cascata	Circuit Breaker	Falha rápida, resposta de fallback e sondagem de saúde downstream

---

Aprofundamento: Padrões Fullstack e Regras de Implementação

1. Frontend: Padrão Container / Presentational

• Contexto: Componentes crescendo além de 200 linhas ao combinar useEffect, queries, transformações de dados e layout JSX.
• Regras:
  • Componente Presentacional: Recebe dados e callbacks apenas via props; puro, facilmente testável no Storybook sem mocks de API.
  • Container (ou Page Hook): Busca dados do servidor, gerencia estados de loading/erro e passa dados transformados para baixo.

2. Frontend: Padrão Componente Headless & Custom Hook

• Contexto: Comportamentos interativos complexos (autocomplete, wizards multi-etapas, accordion) que exigem reuso em diferentes designs visuais.
• Regras:
  • Extrair estado, manipuladores de teclado e atributos ARIA para um custom hook headless (ex.: useAutocomplete, useDisclosure).
  • Manter a estilização e o markup DOM completamente nas mãos do consumidor.

3. Frontend: Componentes Compostos

• Contexto: Componentes com subpartes profundamente relacionadas que precisam de estado interno coeso sem passar dezenas de props de configuração.
• Regras:
  • Usar Context do React para comunicação implícita entre pai e filho (<Accordion><Accordion.Item /><Accordion.Panel /></Accordion>).

4. Integração: Padrão Adapter (Camada de Anticorrupção)

• Contexto: Payloads de API REST/GraphQL de terceiros vazando diretamente para props de componentes UI ou modelos de domínio centrais.
• Regras:
  • Nunca permitir que chaves de DTO do backend ditem os formatos de props dos componentes frontend.
  • Criar funções mapeadoras explícitas (ex.: toUserViewModel(dto: UserApiDto): UserVM) para proteger os componentes UI de mudanças de schema.

5. Integração: Optimistic UI com Rollback

• Contexto: Interações frequentes do usuário (curtidas, alternâncias, conclusão de tarefas, reordenação) onde a latência da rede prejudica a responsividade.
• Regras:
  • Atualizar o estado local imediatamente após a interação.
  • Enfileirar a mutação no servidor; se for rejeitada, reverter para o snapshot anterior e notificar o usuário de forma não intrusiva.

6. Backend: Padrão Repositório

• Contexto: Lógica de negócio entrelaçada com consultas ORM (Prisma, TypeORM, Drizzle, SQL).
• Regras:
  • Serviços interagem unicamente com uma interface (ex.: OrderRepository).
  • Manter lógica de domínio fora dos repositórios; manter construção de consultas fora dos serviços.

7. Backend: Padrões Strategy & Factory

• Contexto: Provedores substituíveis (gateways de pagamento, canais de notificação, armazenamento de arquivos).
• Regras:
  • Padronizar o comportamento através de uma interface comum (PaymentGateway).
  • Usar uma Factory/Registry para resolver implementações concretas com base em configuração ou tenant.

8. Backend: Padrão Circuit Breaker

• Contexto: Microsserviços externos ou APIs de terceiros sofrendo intermitência ou latência severa.
• Regras:
  • Rastrear limites de falha. Transições: Closed (normal) -> Open (falha rápida, retornar cache/fallback) -> Half-Open (sonda canário).

---

Workflow de Saída do Agente

Ao ser solicitado a aconselhar sobre arquitetura ou refatorar código fullstack:

1. Identifique a Junta e o Gargalo: Identifique se o atrito está na renderização da UI, sincronização de estado, incompatibilidade de contrato de API ou acoplamento do backend.
2. Selecione o Padrão Correspondente: Proponha o padrão com uma justificativa clara abordando o code smell específico.
3. Forneça Exemplos Antes / Depois: Forneça snippets de código concisos e idiomáticos demonstrando responsabilidades desacopladas.
4. Destaque Testabilidade e Manutenibilidade: Explique como a refatoração simplifica testes unitários/de componentes e protege contra mudanças futuras.