Como pedir ao Claude Code para mexer em um único arquivo

“Dá uma melhorada na introdução desse post do blog, por favor.”

Foi isso que eu digitei numa sexta-feira, dez da noite. O que eu queria ajustar eram só os três primeiros parágrafos de um arquivo. Mas na manhã seguinte, quando abri o diff, doze arquivos tinham mudado. Não só o texto do post: o layout compartilhado, a lista de tags e, sabe-se lá por quê, até o arquivo de configuração de publicação. E eu tinha ido dormir sem nem checar se aquilo ainda funcionava.

Levei trinta minutos para reverter tudo. O que deu errado? Não foi o Claude Code que mancou. O problema foi que a minha instrução não dizia uma palavra sequer sobre até onde ele podia mexer. A IA, esperta, só fez o que parecia gentil: “melhorar a introdução significa também arrumar o que está em volta”.

Neste artigo eu entrego, prontinho para copiar e colar, o “brief para mexer em um único arquivo com segurança” que nasceu daquela noite. Defina um escopo estreito, peça que ele mesmo valide ao terminar e deixe um caminho de volta caso esteja errado. Só com isso os acidentes da madrugada praticamente sumiram.

Pontos principais

• Quando uma tarefa delegada à IA sai do controle, o culpado não é o modelo: é o prompt que não escreveu até onde se pode mexer.
• Todo brief precisa de cinco pontos: “arquivos para ler”, “arquivos para alterar”, “o que não tocar”, “comando de validação” e “como reverter”.
• Exija que ele rode o comando de validação antes de relatar sucesso e você evita virar o testador depois que o agente já saiu.
• Comece por tarefas pequenas com ponto de parada claro: melhorar a intro de um post, organizar um relatório de bug, reescrever o texto de um produto.
• Estreitar o escopo não reduz o valor do trabalho. Pelo contrário, fica mais fácil o leitor adaptar ao próprio ambiente.

Por que “deixa melhor” dá errado

O pedido “deixa melhor” não tem linha de chegada.

Um editor humano, ao receber esse pedido numa sexta corrida, confirmaria: “são só os três parágrafos da introdução, né?”. A IA, porém, sai correndo sem perguntar. E como ela é boa em ser prestativa, amplia o escopo por conta própria: “se é para melhorar a introdução, então arrumar as tags e acrescentar os links relacionados também seria mais atencioso”. Zero má intenção. É justamente isso que a torna perigosa.

O que resolve aqui é uma ideia simples: escrever o “ponto de parada” dentro da própria instrução. Não precisa de um prompt longo e rebuscado. Curto é melhor, inclusive. Em vez disso, separe logo de cara, com clareza, os arquivos que podem ser tocados dos que não podem. Só isso já freia a derrapagem.

Quem quiser se aprofundar na escrita de prompts em si vai entender, lendo também o design de prompts do Claude Code, como esse “estreitar o escopo” se conecta com outras técnicas.

Os cinco pontos que nunca faltam no brief

O brief que eu uso hoje sempre carrega estes cinco itens. E a ordem também tem um motivo.

Item	Conteúdo	O que acontece se faltar
Arquivos para ler	O que pode ser lido para entender o contexto	Lê coisas irrelevantes e faz correções fora do alvo
Arquivos para alterar	Os 1 ou 2 arquivos que podem ser reescritos	Acontece o acidente dos doze arquivos
O que não tocar	Configs, artefatos gerados, segredos, ajustes de publicação	Arquivos que não podem sumir são “organizados”
Comando de validação	O comando único que roda após a mudança	Ele relata “pronto” com tudo quebrado
Como reverter	O passo a passo para voltar quando errar	A recuperação leva trinta minutos

O ponto-chave é fazer com que ele devolva um “plano” antes de começar a editar. Não deixe que ele reescreva de cara. Faça-o dizer primeiro: “quais arquivos vou ler, quais vou alterar e, se eu errar, o que quebra”. Se o plano voltar fora do alvo, você para ali mesmo. Sai muito mais barato do que perceber depois de já ter reescrito.

O que delegar à IA e o que decidir você mesmo

Você não precisa entregar tudo à IA. Eu traço a linha assim.

O que pode delegar à IA

• Ler arquivos para entender o contexto
• Montar e verbalizar o plano da mudança
• Escrever o texto ou o código de fato
• Rodar o comando de validação e relatar o resultado

O que você segura na mão

• Quais arquivos entram no alvo da mudança (a decisão de escopo)
• Apertar o botão de publicar ou subir para produção
• O julgamento sobre mexer em arquivos de config ou segredos
• A decisão de barrar a publicação quando a validação falha

Essa divisão é ainda mais importante para quem está delegando trabalho à IA pela primeira vez. Como separar o que se delega do que a pessoa decide aparece como ideia básica em Claude Code para quem não é desenvolvedor também. Enquanto não pega o jeito, uma régua grossa basta: “ler e escrever é da IA; apagar e publicar é do humano”.

Template de brief para copiar e colar

Cole como está e troque só os nomes de arquivo pelo seu ambiente. Tanto no PowerShell quanto no bash, basta colocar o texto numa variável e conferir.

brief=$(cat <<'EOF'
Objetivo: fazer uma única edição segura, em um só lugar.
Arquivo que pode ser alterado: site/src/content/blog/example.mdx
O que não tocar: arquivos de package, artefatos gerados, segredos, configs de publicação/deploy.

Antes de começar a editar, devolva:
1. Os arquivos que vai ler para entender o contexto
2. O único arquivo que vai alterar de fato
3. O que quebra se essa mudança estiver errada
4. O comando de validação que vai rodar após a mudança

Ao terminar a edição, devolva:
- Resumo do diff
- Resultado da execução do comando de validação
- Passo a passo para reverter
EOF
)

echo "$brief"

Esse texto não tem nada de chamativo. O valor dele é conseguir colocar a fronteira em palavras antes de começar o trabalho. Reescreva os nomes de arquivo, o que não tocar e o comando de validação para o seu repositório e entregue ao Claude Code. Quando voltar um bom plano, faça-o repetir as mesmas restrições uma vez mais antes de pôr a mão na massa.

Se você escrever essas mesmas restrições no CLAUDE.md, elas valem automaticamente sem precisar colar toda vez. Como fazer isso está resumido em boas práticas de CLAUDE.md.

Um pequeno script para validar ao terminar

Não acredite no “pronto”. Esse é o segundo pilar.

Depois da edição, confirme de forma mecânica se realmente apenas um arquivo mudou. O script abaixo só conta quantos arquivos não commitados foram alterados e para se houver mais do que o esperado. Funciona como está, com comentários em português.

#!/usr/bin/env bash
# Confirma se apenas um arquivo foi alterado. Para se houver demais.
set -e

# Número de arquivos que se espera alterar (1 para edição de um arquivo)
expected=1

# Conta os arquivos alterados e ainda não commitados
changed=$(git status --porcelain | grep -c .)

echo "Arquivos alterados: $changed (esperado: $expected)"

if [ "$changed" -gt "$expected" ]; then
  echo "Mais arquivos do que o esperado mudaram. Confira o diff."
  git status --porcelain
  exit 1
fi

echo "Dentro do escopo."

Indique esse script como o “comando de validação” do brief e a IA passa a rodá-lo sozinha e a relatar o resultado. Se doze arquivos mudaram, o texto vermelho aparece já na hora do relatório. Em vez de eu descobrir ao acordar de manhã, ele para na hora. É isso que faz diferença.

Quem quiser automatizar mais a validação e a rotina do dia a dia encontra outros moldes em técnicas de produtividade com Claude Code.

Três cenários em que isso funciona

Todos são trabalhos com “ponto de parada” bem nítido. Dito de outro jeito: tarefa sem ponto de parada visível é sinal de que ainda não dá para jogar de bandeja para a IA.

1. Reescrever a introdução de um post Escreva logo no começo que só muda a introdução de um arquivo. Junte o público-alvo e o comando de validação. Assim a mão dele não escorrega para o texto inteiro nem para o layout. O meu acidente dos doze arquivos simplesmente não teria acontecido com essa única linha.

2. Organizar um relatório de bug Mostre apenas o arquivo de log e um template, e escreva: “proibido organizar código sem relação”. Se ele aproveita a faxina do relatório para fazer refactor, a revisão pesa de uma vez. Limite o que ele vê e a saída se limita junto.

3. Testar texto de página de produto Em vez de refazer a página inteira, peça só “uma versão da chamada principal” e “a conferência de como ficou após a mudança”. Como o escopo está travado em uma versão, fica fácil comparar quando você for testar em A/B.

Perguntas frequentes

P. Não é chato colar esse brief comprido toda vez? As restrições que você usa sempre podem ir para o CLAUDE.md e passam a valer sem colar nada. O que sobra para colar é só “o nome do arquivo que pode tocar desta vez”.

P. Estreitar o escopo não mata o que a IA tem de bom? Foi o contrário. Quanto mais estreito o escopo, mais a IA corrige fundo, sem hesitar. Instrução ampla só a faz titubear em “por onde começar”.

P. O que coloco como comando de validação? No começo, “checar o número de arquivos alterados” já basta. Conforme pega o jeito, vá somando, um comando por vez: se o build passa, se os testes não quebram, se não há links quebrados.

P. E se, mesmo assim, um arquivo inesperado mudar? Se você escreveu como reverter no brief, é só seguir aquele passo a passo. O truque é já deixar o comando de volta na instrução, algo como git restore ..

P. Por onde é melhor começar? Escolha uma tarefa pequena que dá para reverter se der errado. Corrigir um post em rascunho ou trocar um texto são opções leves. Se você está inseguro com a operação básica, começar pelo guia de introdução ao Claude Code prepara o terreno.

O que aconteceu quando coloquei em prática

Depois daquele acidente dos doze arquivos, passei a escrever o brief sempre com “arquivos para alterar”, “o que não tocar” e “comando de validação”.

Desde que indiquei o script de validação como “comando de validação”, os casos de arquivo inesperado entrando passaram a parar na hora. Semana passada mesmo, quando mandei corrigir o texto de uma página de produto, a IA quase estendeu a mão até um componente compartilhado, mas no instante em que o número de arquivos alterados chegou a dois o script ficou vermelho e parou. Acabou aquilo de acordar de manhã, ver o diff e perder a cor do rosto.

A outra coisa que confirmei foi que estreitar o escopo não derruba a qualidade da saída. Nos dias em que amarrei “só os três parágrafos da introdução”, as correções voltaram até mais certeiras. Em vez de delegar amplamente para uma IA esperta, peça estreito e faça-a validar sozinha. Parece o caminho mais longo, mas é o mais rápido para mim. É essa a minha conclusão de hoje.

Se você quer montar, no trabalho da empresa, um sistema para delegar edição e operação à IA, dá para construir o passo a passo concreto junto em treinamento e consultoria de adoção. Antes disso, experimente uma vez, na sua própria máquina, um brief de um único arquivo.

Como referência, a informação oficial da ferramenta usada aqui está na documentação oficial do Claude Code.