Como pedir refatoração ao Claude Code sem receber o arquivo inteiro reescrito

Você pediu pra ajustar UMA função e voltou um diff com o arquivo inteiro reescrito, import trocado, helper novo que ninguém pediu e aquele bônus generoso: "aproveitei e melhorei mais umas coisinhas" 😅

Fala aí, beleza? Se essa cena te é familiar, a boa notícia é que o problema quase nunca é o modelo

É o pedido sem fronteira

Refatorar é a tarefa mais fácil de escapar do controle, porque "melhora esse código aqui" é um convite aberto: não diz onde começa, não diz onde termina e não diz o que NÃO pode ser tocado

Então bora fechar esse escopo em três momentos: antes de qualquer edição, durante a execução e depois que o estrago já aconteceu

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

Nada de PC da Nasa aqui, é bem simples:

• Claude Code instalado e rodando dentro do projeto que você quer mexer
• O alvo identificado: qual arquivo, qual função, qual trecho
• Uma forma de VERIFICAR o resultado (um teste que roda, uma saída esperada, um comportamento na tela)
• Controle de versão ativo no projeto

Esse último item não é frescura de purista

O Claude Code faz checkpoint automático do estado do código antes de cada prompt seu, mas o checkpointing cobre apenas as edições feitas pelo Claude: não cobre o que VOCÊ editou na mão nem o que rodou via comandos bash

A recomendação oficial é justamente combinar checkpointing com controle de versão, então mantenha o git aí do lado

Passo a passo: pedir refatoração com escopo fechado

Pré-inscrição Formação Claude Code

Domine o Claude Code do básico ao avançado

Você vai aprender a criar sistemas completos com Claude Code, sem precisar ser programador. Inscreva-se para ter acesso a um desconto de lançamento e bônus especiais!

Quero minha vaga

1. Mapear antes de editar

Antes de pedir mudança, peça leitura

O subagente Explore é rápido e SOMENTE LEITURA, otimizado pra buscar e analisar base de código, e aceita nível de profundidade: quick, medium e very thorough

Como ele não escreve nada, dá pra soltar sem medo:

Use o subagente Explore, profundidade medium:
mapeie quem chama a função calcularFrete em src/services/frete.ts
quero a lista de arquivos e linhas que dependem dela
não edite nada

Detalhe que vale saber: Explore e Plan são os únicos subagentes que omitem o CLAUDE.md e o git status

Ou seja, as suas regras de projeto não chegam neles, o mapeamento é só reconhecimento de terreno

Erro comum deste passo: pular direto pro "refatora isso aí" sem saber quem depende do trecho, e aí a IA "conserta" os chamadores também, porque ninguém disse que eles estavam fora

2. Nomear o alvo com nome e sobrenome

A documentação é bem direta nisso: instruções mais específicas elevam a taxa de acerto, principalmente na PRIMEIRA tentativa, e reduzem correção depois

O que conta como específico? Referenciar arquivos específicos, citar restrições e apontar padrões de exemplo

Instrução vaga gera correção de rota, e correção de rota é onde o diff engorda

Refatore APENAS a função calcularFrete em src/services/frete.ts
objetivo: extrair a regra de faixa de peso pra uma função separada no mesmo arquivo
siga o padrão de src/services/desconto.ts
assinatura pública de calcularFrete não muda

Erro comum deste passo: escrever "refatore o serviço de frete"

"O serviço" é um bairro inteiro, não um endereço

3. Declarar o intocável dentro do próprio pedido

Escopo não é só dizer o que fazer, é dizer o que fica de fora

Essa parte a maioria não escreve, e é justamente a que segura o scope creep:

Não altere:
- nenhum outro arquivo além de src/services/frete.ts
- os testes existentes
- nomes de funções exportadas
se achar que algo fora disso precisa mudar, me avise em vez de mudar

Repare no final: pedir pra AVISAR em vez de agir sozinho

É o mesmo espírito de pedir os estados da tela em vez de aceitar só o caso feliz: o que não é dito, é decidido pela IA do jeito dela

Erro comum deste passo: achar que isso é uma trava

Não é, é um acordo em texto

Trava de verdade tem seção própria mais abaixo

4. Peça o plano antes do código

Esse é o passo que mais muda o resultado

A orientação da própria documentação é pedir um plano antes de escrever código e dizer EXPLICITAMENTE pra não codar até você confirmar que o plano está bom

E tem o modo dedicado pra isso: aperte Shift+Tab até a barra de status mostrar ⏸ plan mode on

Se preferir já começar a sessão assim:

claude --permission-mode plan

Pra sair, você aprova o plano ou aperta Shift+Tab de novo

E quando NÃO usar? A documentação também é clara: plan mode serve quando existe incerteza sobre a abordagem, quando a mudança altera múltiplos arquivos ou quando o código é desconhecido

Pra escopo pequeno e claro (corrigir um typo, adicionar um log, renomear uma variável) é pedir direto e pronto

Cerimônia demais em tarefa de 10 segundos só queima contexto

Erro comum deste passo: pedir o plano e não dizer pra esperar confirmação

Aí ele te mostra o plano e já sai executando, todo feliz, enquanto você ainda estava lendo o item 2 haha

5. Fatie em partes verificáveis

Uma refatoração inteira de uma vez é um diff que ninguém revisa de verdade

O Claude Code funciona melhor quando tem um alvo claro pra iterar, tipo um teste ou uma saída esperada: ele altera, avalia o resultado e melhora incrementalmente até passar

Então amarre cada fatia num critério:

Parte 1 de 3: extraia só a validação de CEP pra uma função privada
não mude comportamento
rode npm test -- frete e me mostre o resultado antes de seguir

Erro comum deste passo: fatiar sem alvo de verificação

Sem teste ou saída esperada, "parte 1 concluída" é opinião

6. Interrompa no segundo em que o diff começa a crescer

Essa é a tecla mais subutilizada do Claude Code: Esc

Ela interrompe em QUALQUER fase (raciocinando, chamando ferramenta, editando arquivo) e preserva o contexto, permitindo redirecionar ou ampliar as instruções

Viu ele abrindo um terceiro arquivo que você não citou? Esc

Não precisa deixar terminar pra depois reclamar do resultado, se liga nisso

Erro comum deste passo: esperar a execução acabar por educação

Quanto mais tarde você para, maior o diff pra desfazer

7. Desfaça sem drama

Se já passou do ponto, tem volta: aperte Esc duas vezes ou use /rewind

O menu te oferece restaurar a conversa (mantendo o código), restaurar o código (mantendo a conversa), resumir a partir daqui, resumir até aqui, ou cancelar

Essa separação entre conversa e código é ouro: dá pra jogar o código fora e MANTER o entendimento que vocês construíram, ou o contrário

Dois limites pra ter na cabeça: são guardados snapshots dos 100 checkpoints mais recentes da sessão, e a cobertura alcança só o que o Claude editou

Por isso o git continua sendo o plano A

Erro comum deste passo: tratar o checkpointing como backup do projeto

Ele é rede de segurança da sessão, não substituto de versionamento

Barreiras duras: quando avisar não basta

Tem arquivo que não pode ser tocado nem por acidente: migration, arquivo gerado, config de produção, aquele legado que segura o prédio

Pra esses, frase no prompt não serve

O que serve é configuração

As regras de permissão seguem o formato Tool ou Tool(especificador), e a avaliação é nesta ordem: deny primeiro, depois ask, depois allow

Detalhe importantíssimo: a primeira regra que casa decide o resultado, independentemente de ser mais ou menos específica

Então dá pra negar edição em caminho específico no settings.json:

{
  "permissions": {
    "deny": ["Edit(caminho/ou/padrao)"]
  }
}

Se você quer algo mais bruto e temporário, a CLI aceita desabilitar ferramenta na sessão inteira:

claude --disallowedTools "Edit"

Bom pra sessão de leitura e análise, onde você quer conversa e diagnóstico sem NENHUMA escrita

E existe ainda a camada dos padrões de exclusão de arquivos: os caminhos que casam ficam fora da descoberta e da busca, têm leitura negada e têm Edit e Write bloqueados ali

É o nível mais forte: o arquivo simplesmente não existe pro Claude

Tome cuidado com um efeito colateral: se você exclui um arquivo que o código realmente precisa entender, ele vai refatorar às cegas em volta

Barreira dura é ótima pro que não pode mudar, não pro que ele precisa LER

Transformar a regra em hábito: CLAUDE.md e memória

Repetir "não mexa em outros arquivos" em todo prompt cansa, e você vai esquecer justo no dia em que importava

O lugar disso é o CLAUDE.md

Ele é lido no começo de cada conversa e serve exatamente pra regra persistente do tipo "sempre faça X", além de comandos de build, convenções e layout do projeto

A descoberta é hierárquica, subindo a árvore de diretórios, então dá pra ter regra geral lá em cima e regra específica dentro do módulo sensível

Um exemplo de regra de escopo pra colar no seu:

## Refatoração
- Só altere os arquivos citados no pedido
- Se outro arquivo precisar mudar, pergunte antes em vez de editar
- Apresente o plano e aguarde confirmação antes de codar
- Nenhuma melhoria fora do que foi pedido

E aqui vai a parte que muita gente ignora: a recomendação é manter cada arquivo abaixo de 200 linhas

Porque arquivo longo consome mais contexto e pode PIORAR a aderência às instruções

Ou seja, CLAUDE.md gigante não te dá mais obediência, te dá menos

Vale lembrar também que são dois sistemas complementares: o CLAUDE.md, escrito por você, e a auto memory, que é a nota que o próprio Claude escreve a partir das suas correções e preferências

Os dois são carregados no início de cada conversa

O que aprendi na prática brigando com o escopo

Eu gravei um vídeo justamente sobre isso, porque o incômodo era diário: peço uma mudança e a IA mexe em vários arquivos, complica mais do que precisava, altera coisa que não estava no pedido e ainda entrega sem testar

Quando fui listar, deu pra fechar em quatro comportamentos: suposição silenciosa (ela interpreta do jeito dela, não confirma e não mostra os tradeoffs), over engineering, scope creep (você pede uma coisa e ela mexe no arquivo inteiro) e entrega sem verificação

Repara que hoje já virou rotina a gente precisar pedir explicitamente pra IA PERGUNTAR quando tiver dúvida, em vez de sair executando

Isso diz muito sobre o padrão que a gente aceitou

No vídeo eu testo um arquivo de regras nesse sentido, instalado só naquele projeto e não global, porque eu queria avaliar antes de espalhar pra tudo

Detalhe que me pegou: só valeu depois que reiniciei a sessão, na conversa que já estava em andamento não mudou nada

O teste foi num projeto meu de gestão de produtos, um CRUD simples de itens, com um pedido bem específico: adicionar um botão de exportar CSV na tabela de produtos, exportando apenas os produtos visíveis (os filtrados)

Como a tarefa era simples, não veio nenhuma pergunta: foi direto pra execução, mostrando etapa por etapa o que estava alterando

No fim veio um relatório do que mudou, e a própria IA verificou que as colunas exportadas batiam com as colunas visíveis da tabela

Cliquei no botão, abri o CSV dentro do VS Code e o arquivo saiu com exatamente os produtos que eu queria, nas 5 colunas da tabela (nome, categoria, preço, estoque, status)

Sendo honesto: foi demonstração simples e não provocou nenhuma pergunta

Pra ver o comportamento de questionar, o caminho seria um pedido vago do tipo "adicione um sistema de autenticação neste projeto", que é onde a suposição silenciosa aparece de verdade

O contraste que ficou na minha cabeça é esse: sem regra de escopo, muitas linhas alteradas, vários arquivos mexidos, zero pergunta e um diff impossível de revisar

Com regra de escopo, menos linhas, menos arquivos, algumas perguntas pra tirar dúvida e um diff limpo, só com o que eu pedi

Na minha experiência isso economiza token e chega no resultado mais rápido, com menos idas e vindas

No vídeo tu vê o pedido do CSV rodando do zero, o relatório final e o arquivo aberto no VS Code pra conferir se saiu o que eu pedi mesmo

Quando o contexto é o culpado, não o pedido

Tem um cenário onde você faz tudo certo e mesmo assim o negócio começa a reescrever demais: a sessão está longa

Contexto entupido de tentativa antiga, arquivo que você nem discute mais e decisão que já foi revertida deixa a IA misturando assunto

Aí a ferramenta certa não é um prompt melhor, é limpeza

• /compact resume as mensagens antigas da conversa preservando o contexto importante, e precisa de pelo menos duas trocas anteriores, senão ele devolve a mensagem de que não há o que compactar
• /clear reseta a conversa pra contexto vazio, e a conversa anterior continua em disco, podendo ser retomada pelo session ID

O critério é simples: se o histórico ainda importa pro que você está fazendo, /compact

Se você vai começar OUTRA tarefa, /clear

Continuar uma refatoração nova em cima do lixo da anterior é pedir pra ele "lembrar" de decisões que você já jogou fora

E sim, conversa mais enxuta é menos token gasto por rodada, o que ajuda quem está de olho no consumo

Se esse é o seu caso e você está avaliando baixar ou cancelar o plano do Claude, vale entender o que muda na hora antes de mexer

Conclusão

Escopo é uma instrução, não uma esperança 🙂

O resumo da ópera: mapeie antes com o Explore (somente leitura), nomeie arquivo e função no pedido, escreva o que é intocável, peça o plano dizendo pra não codar até você confirmar, fatie em partes com verificação, aperte Esc no primeiro sinal de diff crescendo e use Esc duas vezes ou /rewind quando passar do ponto

Pro que não pode mudar de jeito nenhum, a resposta é configuração: permissions.deny com Edit(caminho/ou/padrao) e --disallowedTools na sessão

Próximo passo, bem concreto: abra o CLAUDE.md do seu projeto agora, escreva as quatro linhas da regra de escopo e faça o próximo pedido em plan mode, lendo o plano ANTES de deixar qualquer edição acontecer

Faz o teste e me conta como foi

até o próximo post!