Guia de Referência: Refatoração Segura e Evolutiva (Martin Fowler)

Este guia transforma os princípios de refatoração em regras operacionais para IA. Refatorar significa melhorar a estrutura interna do software preservando o comportamento observável, trabalhando em passos pequenos e verificáveis.

subdirectory_arrow_right1. Definição e Objetivo

• Preservação de comportamento: A refatoração muda estrutura, nomes, distribuição de responsabilidades ou dependências sem adicionar funcionalidade observável.
• Design contínuo: O design pode ser aperfeiçoado durante o desenvolvimento conforme a equipe aprende mais sobre o problema.
• Dois chapéus: Separe mentalmente o momento de adicionar funcionalidade do momento de refatorar; evite misturar objetivos em um único passo grande.

subdirectory_arrow_right2. Sinais de que Refatorar é Necessário

• Nomes misteriosos: Nomes que exigem comentários ou conhecimento implícito devem ser tornados explícitos.
• Código duplicado: Conhecimento repetido em vários lugares aumenta risco de divergência.
• Funções ou classes longas: Blocos que acumulam responsabilidades dificultam entendimento e teste.
• Listas longas de parâmetros: Podem indicar agrupamentos de dados, abstrações ausentes ou interfaces instáveis.
• Dados globais e mutáveis: Aumentam acoplamento oculto e tornam o comportamento difícil de prever.
• Switches repetidos: Podem sinalizar variação que merece polimorfismo ou Strategy, quando a complexidade justificar.

forms_add_on3. Catálogo de Transformações

• Extração: Extraia função, variável, classe ou fase para tornar responsabilidades e passos explícitos.
• Encapsulamento: Encapsule variáveis, registros e coleções para controlar acesso e invariantes.
• Movimentação: Mova funções, campos e responsabilidades para o módulo que possui o conhecimento adequado.
• Simplificação condicional: Decomponha condicionais, introduza casos especiais ou polimorfismo quando isso reduzir duplicação e complexidade.
• Herança e delegação: Suba/desça membros, extraia superclasses ou substitua herança por delegação quando o relacionamento ficar mais claro.

fact_check4. Testes como Base

• Código autotestável: Tenha uma suíte automatizada capaz de acusar rapidamente mudanças comportamentais indesejadas.
• Antes e depois: Execute testes antes, faça uma pequena transformação e execute novamente.
• Integração contínua: Compartilhe refatorações cedo para que interfaces em mudança não gerem trabalho paralelo sobre premissas antigas.

account_tree5. YAGNI e Arquitetura Evolutiva

• Necessidade atual: Não adicione flexibilidade especulativa sem um problema concreto.
• Opções reversíveis: Prefira decisões que possam evoluir por refatoração quando o conhecimento aumentar.
• Padrões como alvo: Um padrão pode ser destino de uma sequência de refatorações; não precisa ser introduzido inteiro de uma vez.

school6. Como Usar com IA

Use este arquivo quando a tarefa envolver melhorar código existente, preparar uma feature, reduzir dívida técnica ou evoluir em direção a um padrão. Exija da IA uma sequência de pequenos passos, comportamento preservado e testes executados entre as etapas.

subdirectory_arrow_rightDiretrizes de Execução para IA

Ao criar, revisar ou reestruturar uma aplicação, garanta:

1. Declare o comportamento que deve permanecer igual antes de alterar a estrutura.
2. Faça uma transformação por vez e mantenha o sistema executável.
3. Use testes como feedback, não como etapa final.
4. Pare quando a necessidade atual estiver atendida; não refatore por perfeccionismo.
5. Não misture feature e refatoração extensa no mesmo passo sem justificar.

schoolRoteiro de Uso Operacional com IA

1. Contextualize o projeto: informe domínio, stack, arquitetura atual, restrições e objetivo da mudança.
2. Selecione o recorte: diga qual princípio/capítulo deste guia deve orientar a tarefa; não aplique tudo ao mesmo tempo.
3. Peça diagnóstico antes do código: a IA deve identificar sintomas, riscos, dependências e alternativas.
4. Defina critérios de aceite: comportamento, testes, acessibilidade, performance, segurança ou operação conforme o tema.
5. Implemente incrementalmente: mudanças pequenas, reversíveis e verificadas.
6. Faça revisão final: peça à IA que confronte a solução com este guia e liste desvios deliberados.

smart_toyPrompt de aplicação

Use este guia como referência técnica para a tarefa abaixo.
Não copie regras mecanicamente. Primeiro diagnostique o problema e selecione apenas os princípios aplicáveis.
Mostre: (1) diagnóstico, (2) decisão, (3) implementação proposta, (4) testes/verificações, (5) trade-offs e (6) checklist final.

Contexto: [DESCREVA o sistema, stack, estado atual e cenário da mudança]
Objetivo: [DESCREVA o resultado esperado e o comportamento que deve existir]
Restrições: [DESCREVA limites de escopo, compatibilidade, segurança, prazo e o que não pode mudar]

schoolComo preencher os campos

• Contexto: descreva o tipo de sistema, stack/versões, arquitetura atual, onde a mudança acontece e o comportamento relevante já existente.
• Objetivo: descreva o resultado observável que deve existir ao final, não apenas a tecnologia que você quer usar.
• Restrições: informe o que não pode mudar, compatibilidade, prazo, segurança, acessibilidade, performance, legado, dependências e limites de escopo.

lightbulbExemplo preenchido

Contexto: Sistema legado de atendimento em produção; o mesmo cálculo aparece em três funções e alterações recentes geraram regressões.
Objetivo: Refatorar a duplicação sem alterar o comportamento externo e preparar o código para uma nova regra de cálculo.
Restrições: Primeiro criar testes de caracterização; não misturar nova funcionalidade com refatoração; permitir rollback por etapas.