.agent/rules/solid-compliance.md

type	name	description	scope	trigger	updatedAt
rule	solid-compliance	Todo código deve aderir aos 5 princípios SOLID do Refactoring.Guru	local	model_decision	2026-09-28

Regra: Conformidade SOLID

Contexto

Os princípios SOLID são o alicerce de software manutenível. Violações geram acoplamento, rigidez e fragilidade que crescem exponencialmente com o tempo.

Regra

Ao analisar ou modificar código, verificar conformidade com cada princípio:

S — Responsabilidade Única

• Cada arquivo tem uma única razão para mudar
• Funções fazem uma única coisa
• Composables encapsulam um único domínio de estado

Indicador de violação: arquivo que precisa mudar quando regras de negócio E regras de apresentação mudam.

O — Aberto/Fechado

• Novas funcionalidades adicionadas por extensão (novos arquivos), não por edição de existentes
• Usar dispatch tables, strategy pattern ou plugins

Indicador de violação: if/else ou switch que cresce a cada nova variação.

L — Substituição de Liskov

• Subtipos podem ser usados onde o tipo base é esperado
• Funções que aceitam um tipo base funcionam com qualquer subtipo

Indicador de violação: instanceof ou type guards que verificam subtipos para mudar comportamento.

I — Segregação de Interface

• Tipos/interfaces contêm apenas os membros que seus consumidores usam
• Nenhum módulo é forçado a depender de métodos que não utiliza

Indicador de violação: tipo com campos opcionais demais (?) que na prática são obrigatórios em alguns contextos.

D — Inversão de Dependência

• Módulos de lógica de negócio não importam de módulos de infraestrutura diretamente
• Dependência flui através de abstrações (interfaces, tipos, schemas Zod)

Indicador de violação: serviço de negócio importando driver de banco ou cliente HTTP diretamente.

Exemplos

✅ Correto — Princípio O (Aberto/Fechado)

// dispatch table: extensível sem editar código existente
const calculadores: Record<TipoLicenca, CalculadorFn> = {
  ambiental: calcularAmbiental,
  sanitaria: calcularSanitaria,
  // nova licença? adicionar aqui sem tocar nas funções existentes
}

❌ Incorreto — Violação do Princípio S (Responsabilidade Única)

// arquivo que faz validação + cálculo + formatação + envio de email
export function processarLicenca(dados: DadosLicenca) {
  validar(dados)        // validação
  const valor = calcular(dados)  // cálculo
  const pdf = gerarPDF(valor)    // formatação
  enviarEmail(pdf)      // notificação
  // 4 razões para mudar = 4 responsabilidades
}

Impacto

Código que viola SOLID se torna cada vez mais caro de manter: cada mudança exige mais esforço e introduz mais risco de regressão.

Referências

• Robert C. Martin — "Agile Software Development, Principles, Patterns, and Practices"
• Refactoring.Guru — https://refactoring.guru/pt-br/design-patterns
• Persona: agents/refatorar/persona