.agent/rules/design-patterns-pragmatico.md

type	name	description	scope	trigger	updatedAt
rule	design-patterns-pragmatico	Aplicar Design Patterns GoF apenas quando há problema concreto que o justifique	local	model_decision	2026-09-28

Regra: Design Patterns Pragmático

Contexto

Os 22 Design Patterns GoF são soluções comprovadas para problemas recorrentes. Porém, aplicar um padrão sem problema concreto cria complexidade gratuita — o code smell "Generalidade Especulativa".

Regra

Antes de introduzir qualquer Design Pattern:

1. Identificar o problema concreto que existe agora (não no futuro hipotético)
2. Nomear o code smell que o padrão resolve
3. Avaliar se a complexidade do padrão é justificada pelo tamanho do problema
4. Documentar a decisão com o formato: Problema → Padrão → Justificativa

Nunca introduzir padrão porque:

• "Pode ser útil no futuro" → Generalidade Especulativa
• "É elegante" → Over-engineering
• "Eu conheço esse padrão" → Hammer/Nail antipattern

Guia de Decisão por Sintoma

Sintoma no Código	Padrão Candidato	Aplicar Se...
if/switch crescente por variação	Strategy	3+ variações com tendência de crescer
Criação condicional de objetos	Factory Method	2+ tipos com interface comum
Construção complexa passo a passo	Builder	4+ parâmetros ou construção condicional
Comportamento que muda com estado	State	3+ estados com transições definidas
Pipeline de validações/filtros	Chain of Responsibility	3+ etapas com combinações variáveis
Comportamento adicional sem modificar	Decorator	2+ comportamentos combináveis
Interface incompatível com sistema	Adapter	Integração com API externa
Subsistema com muitas dependências	Facade	3+ módulos coordenados por um cliente
Notificação de mudanças de estado	Observer	2+ interessados em mudanças

Exemplos

✅ Correto — Padrão justificado

Problema: cálculo de taxa varia por 5 tipos de licença e cresce com novos tipos.
Code smell: switch crescente (violação Open/Closed).
Padrão: Strategy via dispatch table.
Justificativa: elimina switch, cada novo tipo é arquivo separado.

❌ Incorreto — Padrão especulativo

Problema: nenhum. Temos apenas 1 tipo de notificação.
Padrão: Observer com EventEmitter customizado.
Motivo: "talvez no futuro tenha mais tipos".
Resultado: 4 arquivos novos para resolver 0 problemas.

Impacto

Padrões aplicados sem critério geram código mais complexo sem benefício proporcional, violando o princípio YAGNI (You Aren't Gonna Need It).

Referências

• Alexander Shvets — "Mergulho nos Padrões de Projeto" (Refactoring.Guru)
• GoF — "Design Patterns: Elements of Reusable Object-Oriented Software"
• Persona: agents/refatorar/persona