Modelos de prompt para refatorar código

Um prompt de refatoração seguro informa a um assistente de programação com IA qual comportamento preservar, onde trabalhar, quais testes definem o contrato e como validar o resultado. “Limpe isto” não é um plano de refatoração. É um convite para alterar coisas que você não revisou.

Use estes modelos como pontos de partida. Substitua os detalhes entre colchetes por fatos da sua base de código e peça análise antes de uma alteração ampla.

Modelo: refatoração segura

Refatore [componente/módulo/função] para melhorar [problema específico de
manutenibilidade].

Preservação de comportamento: Mantenha inalterados [API pública, comportamento
visível, eventos, tratamento de erros, acessibilidade, característica de desempenho].

Escopo: Limite as alterações a [arquivos/limite]. Não altere [itens explícitos
fora do escopo].

Testes: Identifique os testes existentes que comprovam o contrato atual. Adicione
cobertura de regressão focada se um comportamento protegido não estiver coberto.

Critérios de aceitação: A duplicação ou o acoplamento é reduzido, o comportamento
público permanece inalterado e o diff não tem limpeza não relacionada.

Validação: Execute [comando de teste focado], a verificação de tipos e [fluxo manual].
Antes de editar, descreva o contrato atual e a menor extração segura.

Use este modelo quando você conhece a melhoria, mas quer proteger um limite estável da funcionalidade.

Modelo: extraindo um componente

Extraia a [região de interface] repetida de [componentes pais] para o menor
componente reutilizável possível.

Preservação de comportamento: Mantenha idênticos os rótulos visíveis, o foco do
teclado, os atributos aria, o estado de carregamento, os eventos de analytics e
o layout móvel.

Escopo: Apenas [componentes pais], o novo componente e os testes diretos. Não
mova a responsabilidade pela busca de dados ou pelas mutações para o componente extraído.

Testes: Preserve ou adicione testes para os estados [vazio, carregando, erro,
preenchido] e para o comportamento interativo de que os usuários dependem.

Critérios de aceitação: Os componentes pais usam o novo componente, o comportamento
diferente permanece explícito e nenhuma propriedade pública nem link muda inesperadamente.

Validação: Execute testes focados do componente, inspecione os estados renderizados
em larguras de desktop e mobile e relate qualquer comportamento que não pôde ser verificado.

Analise as diferenças existentes antes de extrair qualquer coisa.

A linha sobre responsabilidade evita o erro comum de misturar uma extração visual com uma reescrita de gerenciamento de estado.

Modelo: reduzindo duplicação

Encontre a lógica duplicada em [lista de arquivos] e proponha a menor abstração
compartilhada.

Preservação de comportamento: Preserve o comportamento público de cada chamador,
os valores padrão, o tratamento de erros, a telemetria e o timing.

Escopo: Não generalize além destes chamadores. Mantenha as diferenças visíveis
quando elas representam regras de produto, e não duplicação acidental.

Testes: Mapeie cada teste existente para o comportamento compartilhado que ele
protege. Adicione um teste para cada divergência significativa.

Critérios de aceitação: A lógica repetida é centralizada apenas onde o contrato é
realmente o mesmo; os chamadores permanecem legíveis e equivalentes em comportamento.

Validação: Execute os testes focados dos chamadores e compare a saída observável
antes e depois.

Retorne uma análise das diferenças comuns versus intencionais antes do código.

Código compartilhado não é automaticamente melhor. Um prompt deve fazer o assistente provar que o comportamento é realmente compartilhado.

Modelo: refatoração de desempenho

Investigue um problema de desempenho em [tela/fluxo de trabalho].

Evidências: [medição, trace, timing, relato de usuário ou cenário reproduzível].
Não presuma que [memoização/cache/divisão de código] é a resposta.

Preservação de comportamento: Mantenha inalterados o carregamento visível para o
usuário, a atualização, a acessibilidade, a autorização e o comportamento de erro.

Escopo: Inspecione primeiro [caminhos]. Não introduza cache persistente, uma nova
biblioteca de estado nem uma dependência de servidor sem uma necessidade medida.

Testes: Mantenha os testes de comportamento existentes. Adicione uma verificação de
regressão ou medição apenas se o projeto tiver uma convenção estável para isso.

Critérios de aceitação: Nomeie o gargalo, mostre uma linha de base e um resultado e
mantenha intacto o comportamento protegido.

Validação: Execute os testes relevantes, capture a medição acordada e documente
trade-offs como atualização ou memória.

Este modelo torna a otimização orientada por evidências, em vez de orientada por técnicas.

Modelo: refatoração de código legado

Refatore [módulo legado] para que [risco específico ou custo de manutenção] seja
reduzido sem alterar seu comportamento observado externamente.

Preservação de comportamento: Liste as entradas, saídas, modos de erro, efeitos
colaterais, formatos de arquivo e requisitos de compatibilidade legados de que os clientes dependem.

Escopo: Trabalhe dentro de [módulo/limite]. Não atualize dependências não relacionadas
nem reescreva chamadores na mesma alteração.

Testes: Primeiro caracterize o comportamento atual com testes ou fixtures onde
a cobertura estiver ausente. Inclua casos extremos conhecidos e entrada malformada.

Critérios de aceitação: A nova estrutura é mais fácil de raciocinar, o comportamento
caracterizado permanece estável e as notas de compatibilidade são explícitas.

Validação: Execute testes de caracterização, testes de integração existentes, a
verificação de tipos e um cenário manual ou de linha de comando representativo.

Explique o comportamento desconhecido e o risco antes de propor uma implementação.

Para código legado, um teste que capture um comportamento existente incômodo pode ser mais valioso do que uma reescrita com aparência mais limpa.

Modelo: refatoração grande

Planeje uma refatoração em etapas de [sistema] para alcançar [arquitetura alvo].

Preservação de comportamento: Mantenha [APIs públicas, compatibilidade de dados,
permissões, fluxos de trabalho do usuário, comportamento de implantação e caminho de reversão].

Escopo: Divida o trabalho em marcos que possam ser testados independentemente.
Identifique os arquivos que não devem mudar no primeiro marco.

Testes: Defina os testes focados, testes de contrato, verificações de migração e
fluxos manuais que cada marco deve passar antes de o próximo começar.

Critérios de aceitação: Cada etapa tem uma condição de entrada clara, resultado
observável, estratégia de reversão e nenhuma dependência oculta de uma etapa posterior.

Validação: Revise o plano em relação à arquitetura atual, execute as verificações de
cada etapa e pare se um marco invalidar o pressuposto original.

Não edite código até apresentar as etapas, os riscos e as alternativas.

Este é um prompt de planejamento, não uma solicitação de um único patch gigante. Ele oferece pontos de verificação significativos para quem revisa.

Refatoração ainda é trabalho de produto

Uma refatoração pode quebrar uma interação, perder um evento, enfraquecer uma decisão de autorização ou traduzir incorretamente uma string visível ao usuário. Proteja o comportamento de forma tão deliberada quanto melhora o código.

Use como escrever prompts melhores para IA para a estrutura principal. Para exemplos completos, leia exemplos de engenharia de prompts para engenheiros de software. Se uma refatoração começar por causa de um incidente de produção, combine-a com modelos de prompt para depurar problemas de produção.

Quando uma refatoração alterar um script, primeiro verifique os comandos que ela preserva. Pratique fluxos de trabalho de terminal no navegador para que a validação se baseie em entrada e saída, não na memória.