Como pedir refatoração ao Claude Code sem mudar o comportamento do código

Aceitar um "Refatorado!" bonito e descobrir meia hora depois que o endpoint agora devolve outra coisa é um tipo específico de susto 😅

Refatorar é mudar a FORMA sem mudar o resultado

esse é o contrato, e é um contrato que o agente só respeita se o teu pedido disser isso com todas as letras

Quando você escreve "refatore esse arquivo" e mais nada, você não pediu refatoração, você pediu melhoria, e melhoria na cabeça de um modelo inclui "arrumar" aquele if estranho que, adivinha, existia por um motivo

Aqui vai o roteiro de pedido que separa o que pode e o que não pode mudar, os sinais no diff de que o agente passou do combinado, e como voltar atrás quando passou

O que você precisa antes de pedir a refatoração

Antes de sair pedindo, quatro coisas na mesa

• Código versionado no git, com o trabalho atual já commitado. Sem isso você não tem com o que comparar nem para onde voltar
• Uma forma de verificar comportamento: suíte de testes ou, na falta dela, um roteiro manual de conferência escrito antes (abro a tela X, clico em Y, tem que aparecer Z)
• A lista de arquivos que entram no escopo. Se você não sabe dizer quais são, o problema não é a refatoração, é o mapa
• A noção clara dos limites do checkpoint interno do Claude Code

Esse último merece parada

O Claude Code salva checkpoints do estado do código e deixa você reverter, porém ele rastreia apenas as edições feitas pelas ferramentas de edição de arquivo dele

Alterações feitas por comandos como rm, mv e cp não podem ser desfeitas pelo rewind

E ao restaurar, qualquer caminho rastreado que seja symlink ou hard link é pulado, com direito a aviso de arquivos pulados

Traduzindo: o checkpoint é o cinto, o git é o airbag

O git cobre exatamente o buraco que o rewind não cobre, por isso ele é pré-requisito e não "boa prática opcional"

Formação Recomendada

Formação Claude Code

Domine Claude Code do absoluto zero até o avançado

• 116 aulas
• 4 projetos
• 9h 23min

Conhecer formação

Como pedir a refatoração passo a passo

O roteiro inteiro cabe em sete passos. A ideia é sempre a mesma: decidir a fronteira antes de o agente escrever a primeira linha

1. Entre em plan mode antes de qualquer coisa. Três caminhos documentados: pressionar Shift+Tab para ciclar entre os modos de permissão até chegar no plan mode, prefixar o prompt com /plan, ou já abrir a sessão com claude --permission-mode plan. Nesse modo o Claude lê arquivos e roda comandos de shell somente leitura para explorar e montar um plano, sem editar o código-fonte, e delega a pesquisa no código ao subagente Plan para manter a conversa principal somente leitura. Erro comum deste passo: mandar o pedido no modo accept edits, que aceita automaticamente edições de arquivo e comandos comuns de filesystem dentro do diretório de trabalho. Aí quando você lê a proposta, ela já virou commit na tua cabeça e já virou arquivo no disco
2. Escreva o pedido em duas listas. Uma de "pode mudar" (nomes de variáveis internas, extração de função, ordem dos blocos, remoção de duplicação) e uma de "não pode mudar" (assinaturas públicas, formato de retorno, mensagens exibidas, tratamento de erro, qualquer comportamento observável). Duas listas explícitas valem mais que três parágrafos de contexto. Erro comum deste passo: só escrever a lista do que pode. O que o pedido não proíbe, o agente entende como convite
3. Defina o critério de pronto dentro do próprio pedido. Algo como: nenhuma mudança de comportamento observável e o mesmo resultado nos testes que já passavam. Sem critério escrito, o critério vira "o código ficou mais bonito", e isso é opinião, não verificação. Erro comum deste passo: deixar o critério implícito porque "óbvio que é pra continuar funcionando". Não é óbvio pra quem não roda o teu produto
4. Leia o plano antes de aprovar, e edite o plano. O Ctrl+G abre o plano proposto no editor de texto padrão, então dá pra cortar na mão tudo que passou do escopo antes do Claude prosseguir. Se o plano cita um arquivo que não estava na tua lista, corta ali mesmo. Erro comum deste passo: aprovar o plano no automático porque ele está bem escrito. Plano bem escrito e plano dentro do escopo são coisas diferentes
5. Aprove escolhendo a revisão manual. Ao apresentar o plano, o Claude Code pergunta como prosseguir e oferece três saídas: aprovar e seguir em modo auto, aprovar e aprovar cada edição manualmente, ou continuar planejando. Em refatoração, a do meio 👈 Você quer ver cada edição antes de ela existir. Erro comum deste passo: liberar o modo auto num arquivo que você não conhece. No modo auto um classificador revisa as ações em segundo plano e bloqueia as arriscadas, só que "arriscado" ali é sobre o sistema, não sobre a regra de negócio que só você conhece
6. Peça commits de progresso com mensagens descritivas. A Anthropic descreve essa prática como a forma de o modelo usar o git para reverter mudanças ruins e recuperar estados funcionais do código. Refatoração em vinte arquivos num commit só é refatoração que você não consegue desfazer pela metade. Erro comum deste passo: deixar tudo acumular pra "commitar no final"
7. Rode /code-review no diff antes de aceitar o conjunto. O comando embutido verifica o diff atual em busca de bugs de correção e limpezas, e pode aplicar os achados com --fix. Tem também o /security-review, que verifica o diff em busca de vulnerabilidades. Erro comum deste passo: rodar a revisão e aceitar o --fix sem olhar. Você acabou de criar um segundo diff não revisado em cima do primeiro 🙃

Modelos de pedido para os três tipos de refatoração mais comuns

Três textos prontos pra copiar e adaptar. Repare que a estrutura é sempre a mesma: escopo, pode mudar, não pode mudar, critério de pronto

Renomear e extrair funções dentro de um arquivo:

Entre em plan mode e proponha uma refatoração apenas em src/checkout/pricing.js

Pode mudar:
- nomes de variaveis e de funcoes internas (nao exportadas)
- extrair trechos repetidos em funcoes auxiliares privadas
- ordem dos blocos dentro do arquivo

Nao pode mudar:
- nome, ordem e quantidade de parametros de qualquer funcao exportada
- formato do objeto retornado
- textos de mensagem e codigos de erro
- as condicoes de cada if (mesmo que pareçam redundantes)

Criterio de pronto: nenhuma mudanca de comportamento observavel
e os testes existentes passando sem serem editados

Nao altere arquivos de teste

Quebrar um arquivo grande em módulos:

Entre em plan mode e proponha quebrar src/services/order.ts em modulos menores

Pode mudar:
- criar arquivos novos dentro de src/services/order/
- mover funcoes internas para esses arquivos novos
- ajustar os imports internos

Nao pode mudar:
- o que o modulo exporta hoje (nomes e tipos precisam continuar identicos)
- o caminho de import usado por quem consome o modulo
- qualquer logica dentro das funcoes movidas (mover é copiar sem editar)

Criterio de pronto: quem importa esse modulo nao precisa mudar
nenhuma linha para continuar funcionando

Liste no plano todos os arquivos que voce pretende criar ou tocar,
antes de editar qualquer coisa

Trocar a implementação interna mantendo a assinatura:

Entre em plan mode e proponha trocar a implementacao interna de
fetchUserPermissions (hoje em serie) por uma versao paralela

Pode mudar:
- o corpo da funcao
- funcoes auxiliares privadas usadas so por ela

Nao pode mudar:
- a assinatura e o tipo de retorno
- a ordem dos itens no array retornado
- o comportamento em caso de falha (hoje ela propaga a excecao,
  precisa continuar propagando a mesma excecao)

Criterio de pronto: mesmo retorno e mesmo comportamento de erro
que a versao atual, verificados pelos testes existentes

E quando vale a pena montar todo esse ritual?

A documentação de boas práticas é bem direta: planeje quando houver incerteza sobre a abordagem, quando a mudança alterar múltiplos arquivos ou quando o código não for familiar

E peça direto, sem plano, quando o escopo é claro e o diff cabe em uma frase

Renomear uma variável local não precisa de plan mode, beleza? 😀

Sinais no diff de que o agente passou do combinado

Essa é a parte que salva a pele. São padrões que aparecem no diff e que quase sempre significam mudança de comportamento disfarçada de limpeza

Esse último não é paranoia minha

A própria Anthropic documenta a tendência do Claude de marcar uma feature como completa sem teste adequado, e conta que tratou isso com um pipeline de CI mais estrito, pra que novos commits não quebrassem o código existente

Ou seja: a verificação precisa ser externa ao agente, sempre

Quando algum desses sinais escapa e a edição já está no disco, o caminho é o menu de rewind: /rewind, ou Esc duas vezes com o campo de prompt vazio

Lá dentro você escolhe Restore code ou Restore code and conversation

Detalhe importante: as duas opções de restaurar código só aparecem quando o checkpoint selecionado tem alterações de arquivo rastreadas

Prevenir é mais barato que restaurar, e a prevenção são duas coisas só: escopo escrito no pedido e revisão manual por edição

A lógica é a mesma que vale pra remover código legado com segurança e pra correção de bug sem efeito colateral: o combinado precisa existir ANTES do diff

Como voltar atrás quando a refatoração saiu do controle

Sequência de recuperação, na ordem

1. Abra o menu de rewind. Use /rewind ou pressione Esc duas vezes com o campo de prompt vazio. Atenção nesse detalhe: se o campo tiver texto, o duplo Esc limpa o texto em vez de abrir o menu. Erro comum deste passo: apertar Esc Esc com o prompt cheio, achar que o rewind não existe e sair catando arquivo na mão
2. Escolha a ação certa no menu. As opções são Restore code and conversation, Restore conversation, Restore code, Summarize from here e Never mind. Se o plano estava bom e só a execução escapou, restaurar apenas o código costuma bastar. Se o rumo da conversa foi o problema, aí é código e conversa juntos. Erro comum deste passo: restaurar só a conversa e continuar com os arquivos alterados no disco
3. Confirme o que o rewind NÃO cobriu. Alterações feitas por comandos bash como rm, mv e cp não podem ser desfeitas pelo rewind, e caminhos que sejam symlink ou hard link são pulados na restauração, com um aviso de arquivos pulados. Leia esse aviso 👀 Erro comum deste passo: ver o "restaurado" na tela e assumir que a árvore inteira voltou
4. Feche a conta pelo git. Compare o estado atual com o último commit bom e resolva na mão o que o rewind deixou passar. É por isso que o pré-requisito lá do começo era o git, e não o checkpoint

Bônus que muita gente não sabe: o /rewind também permite retomar uma conversa de antes do /clear

Então limpar a sessão sem querer no meio de uma refatoração não é ponto sem volta

Como deixar a regra valendo para as próximas sessões

Repetir as duas listas em todo pedido cansa. A saída é virar configuração

1. Escreva a regra no CLAUDE.md. Arquivos CLAUDE.md dão instruções persistentes para um projeto, para o fluxo pessoal ou para a organização, são lidos no início de toda sessão e servem justamente para regras do tipo "sempre faça X", comandos de build, convenções e layout do projeto. Uma linha do tipo "refatoração não muda comportamento observável: assinatura, retorno, mensagens e tratamento de erro ficam idênticos" já faz trabalho. Erro comum deste passo: escrever um manifesto. Arquivos com mais de 200 linhas consomem mais contexto e podem reduzir a aderência, então regra curta ganha de regra completa
2. Conte com a releitura depois do /compact. O CLAUDE.md da raiz do projeto é relido do disco e reinjetado na sessão após a compactação, então a regra sobrevive a sessões longas de refatoração. Erro comum deste passo: deixar a regra só num arquivo fora da raiz do projeto e esperar o mesmo comportamento
3. Endureça o que não é negociável com regras de permissão. As regras do Claude Code são avaliadas em ordem de deny, depois ask, depois allow: deny impede o uso da ferramenta, ask pede confirmação, e isso vale para Bash, Read, Edit, WebFetch, MCP e as demais ferramentas. Erro comum deste passo: tratar permissão como substituta da revisão. Permissão bloqueia ferramenta, não bloqueia má ideia
4. Commite a configuração pro time. Regras em .claude/settings.json na raiz do repositório cobrem todo mundo que trabalha nele. E fica o aviso: quando você escolhe "Yes, and don’t ask again" numa permissão de Bash, o Claude Code salva aquilo como regra allow em .claude/settings.local.json. Erro comum deste passo: ir clicando em "não pergunte de novo" durante uma refatoração e, sem perceber, montar um allow list que você nunca revisou

Agora a ressalva honesta, porque ela muda o que dá pra esperar disso tudo

Os subagentes Explore e Plan pulam os arquivos CLAUDE.md e o git status da sessão pai, pra manter a pesquisa rápida e barata

Ou seja: a tua regra de "não muda comportamento" NÃO governa a fase de pesquisa e de montagem do plano

O plano continua sendo responsabilidade tua na hora de ler e cortar, e o Ctrl+G segue sendo teu melhor amigo ali

Conclusão

Refatoração é mudança de forma, e quem desenha a fronteira entre forma e comportamento é o pedido, não o agente

O agente só sabe o que você escreveu

Dois pares seguram o processo inteiro: plan mode mais revisão manual por edição na ida, e git mais /rewind na volta

O resto é disciplina de escrever as duas listas antes de apertar enter

Próximo passo bem concreto: pega um arquivo pequeno, um que você conhece de cor, escreve a lista do que pode mudar e a do que não pode, roda o ciclo completo uma vez (plan mode, leitura do plano, revisão manual, /code-review) e sente o ritmo

Depois leva a regra curta pro CLAUDE.md e para de repetir o pedido toda sessão

É mto massa quando o diff chega exatamente do tamanho que você combinou 😀

até o próximo post!