# 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.

---

## 1. 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.

---

## 2. 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.

---

## 3. 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.

---

## 4. 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.

---

## 5. 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.

---

## 6. 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.

---

## Diretrizes 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.


---

## Roteiro 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.

### Prompt de aplicação

```text
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]
```


### Como 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.

### Exemplo preenchido

```text
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.
```