Simplificação de Código

Inspirado pelo plugin Claude Code Simplifier. Adaptado aqui como uma habilidade agnóstica de modelo e orientada a processos para qualquer agente de codificação de IA.

Visão Geral

Simplifique o código reduzindo a complexidade, mas preservando o comportamento exato. O objetivo não é ter menos linhas — é ter um código mais fácil de ler, entender, modificar e depurar. Cada simplificação deve passar em um teste simples: "Um novo membro da equipe entenderia isso mais rápido do que o original?"

Quando Usar

• Depois que uma funcionalidade estiver funcionando e os testes passarem, mas a implementação parecer mais pesada do que o necessário
• Durante a revisão de código, quando problemas de legibilidade ou complexidade forem sinalizados
• Ao encontrar lógica profundamente aninhada, funções longas ou nomes pouco claros
• Ao refatorar código escrito sob pressão de tempo
• Ao consolidar lógica relacionada espalhada por vários arquivos
• Após mesclar alterações que introduziram duplicação ou inconsistência

Quando NÃO usar:

• O código já está limpo e legível — não simplifique por simplificar
• Você ainda não entende o que o código faz — compreenda antes de simplificar
• O código é crítico para o desempenho e a versão "mais simples" seria mensuravelmente mais lenta
• Você está prestes a reescrever o módulo inteiro — simplificar código descartável desperdiça esforço

Os Cinco Princípios

1. Preservar o Comportamento Exatamente

Não mude o que o código faz — apenas como ele se expressa. Todas as entradas, saídas, efeitos colaterais, comportamento de erro e casos extremos devem permanecer idênticos. Se você não tem certeza se uma simplificação preserva o comportamento, não a faça.

ASK BEFORE EVERY CHANGE:
→ Does this produce the same output for every input?
→ Does this maintain the same error behavior?
→ Does this preserve the same side effects and ordering?
→ Do all existing tests still pass without modification?

2. Seguir as Convenções do Projeto

Simplificar significa tornar o código mais consistente com a base de código, não impor preferências externas. Antes de simplificar:

1. Read CLAUDE.md / project conventions
2. Study how neighboring code handles similar patterns
3. Match the project's style for:
   - Import ordering and module system
   - Function declaration style
   - Naming conventions
   - Error handling patterns
   - Type annotation depth

Simplificação que quebra a consistência do projeto não é simplificação — é confusão.

3. Preferir Clareza a Sagacidade

Código explícito é melhor do que código compacto quando a versão compacta exige uma pausa mental para ser interpretada.

// UNCLEAR: Dense ternary chain
const label = isNew ? 'New' : isUpdated ? 'Updated' : isArchived ? 'Archived' : 'Active';

// CLEAR: Readable mapping
function getStatusLabel(item: Item): string {
  if (item.isNew) return 'New';
  if (item.isUpdated) return 'Updated';
  if (item.isArchived) return 'Archived';
  return 'Active';
}

// UNCLEAR: Chained reduces with inline logic
const result = items.reduce((acc, item) => ({
  ...acc,
  [item.id]: { ...acc[item.id], count: (acc[item.id]?.count ?? 0) + 1 }
}), {});

// CLEAR: Named intermediate step
const countById = new Map<string, number>();
for (const item of items) {
  countById.set(item.id, (countById.get(item.id) ?? 0) + 1);
}

4. Manter o Equilíbrio

A simplificação tem um modo de falha: a super-simplificação. Fique atento a essas armadilhas:

• Inline excessivo — remover um helper que deu nome a um conceito torna o local da chamada mais difícil de ler
• Combinar lógica não relacionada — duas funções simples mescladas em uma função complexa não é mais simples
• Remover abstração "desnecessária" — algumas abstrações existem para extensibilidade ou testabilidade, não para complexidade
• Otimizar para contagem de linhas — menos linhas não é o objetivo; compreensão mais fácil é

5. Escopo ao que Foi Alterado

Por padrão, simplifique o código modificado recentemente. Evite refatorações "de passagem" de código não relacionado, a menos que seja explicitamente solicitado a ampliar o escopo. Simplificação sem escopo cria ruído nas diferenças e arrisca regressões não intencionais.

O Processo de Simplificação

Passo 1: Entender Antes de Tocar (A Cerca de Chesterton)

Antes de alterar ou remover qualquer coisa, entenda por que ela existe. Isso é a Cerca de Chesterton: se você vê uma cerca em uma estrada e não entende por que ela está lá, não a derrube. Primeiro, entenda o motivo e, em seguida, decida se o motivo ainda se aplica.

ANTES DE SIMPLIFICAR, RESPONDA:
- Qual é a responsabilidade deste código?

…