Como fazer a primeira edição segura em um repositório existente com Claude Code

No primeiro dia mexendo num repositório interno que acabei de herdar, eu fiz besteira.

Pedi pro Claude Code “dar uma lida geral e arrumar o que estiver feio”. Trinta minutos depois, 23 arquivos tinham sido reescritos. O conteúdo até que não estava ruim. Só que, “de quebra”, ele também organizou a configuração de deploy de produção e os arquivos de pagamento que ninguém pode encostar. O diff ficou tão grande que nem eu sabia dizer qual mudança era de verdade necessária. No fim, joguei tudo fora e comecei do zero.

Uma IA inteligente não causa acidente por falta de capacidade. O problema é que ninguém tinha decidido, antes de entrar, até onde ela podia mexer. Hoje vamos reconstruir esse primeiro dia de um jeito que dá pra reverter, dá pra conferir e chega ao fim sem sustos.

Pontos principais

No primeiro dia em código alheio, antes de qualquer coisa, escreva em uma página só: “onde posso ler, onde é proibido tocar e qual comando de verificação rodar no final”.
Não entregue uma grande reforma pro Claude Code logo de cara. Comece com uma edição pequena e reversível (ajustar nome de teste, adicionar comentário).
Antes do “pronto, terminei”, rode sempre pelo menos um comando de verificação e guarde o resultado.
Exclusão de arquivos, banco de produção, cobrança e force push ficam fixados em “confirmar com humano” no primeiro dia. Automatize depois só o que provou ser seguro.
Quando o diff começar a inchar, antes de mexer no texto do pedido, reduza os arquivos que a IA pode tocar.

Por que decidir o escopo logo no primeiro dia

Um repositório novo é uma cidade sem mapa. Quais arquivos são o coração do sistema e quais quebram tudo se você encostar? No começo, ninguém enxerga isso.

Se você pede pro Claude Code “olhar o todo e arrumar”, a IA, com boa intenção, mexe em muita coisa. A IA não é a culpada. A culpa é de quem entrou sem passar o escopo. É como dizer pro estagiário no primeiro dia “deixa a loja do jeito que achar melhor” e ele acabar mudando a configuração do caixa. A responsabilidade é de quem deu a ordem, não é?

Por isso, a primeira coisa a fazer não é escrever um prompt esperto, e sim desenhar um mapa. A prateleira que pode ler, a gaveta que não pode abrir, e o que conferir antes de ir embora. Só de colocar esses três pontos no papel, a maioria dos acidentes do primeiro dia some.

As três fronteiras que você decide primeiro

A ordem importa. Vá fixando de cima pra baixo.

O que decidir	Exemplo concreto	Por que decidir antes
Onde pode ler	`src/`, `docs/`, arquivos de teste	Deixar ler tudo faz a IA propor mudanças que não vêm ao caso
Onde é proibido tocar	`.env`, pagamento, autenticação, migrações de banco, config de deploy de produção	Quebrar aqui não tem volta
Verificação ao terminar	`npm run build`, um teste	Para deixar uma “prova de que funciona” toda vez

Esse papel com os três pontos (pode ser texto puro) eu guardo num ONBOARDING.md na pasta de trabalho. É também o primeiro arquivo que faço o Claude Code ler. Compartilho o mapa e só depois deixo a IA andar pela cidade — essa é a ordem.

O que delegar à IA e o que o humano decide

Misturar essas duas coisas é receita de acidente. Vamos traçar a linha com clareza.

Tarefas que pode delegar ao Claude Code

Ler o repositório inteiro por cima e resumir a estrutura.
Procurar “em qual arquivo está esta funcionalidade”.
Rascunhar melhorias pequenas e reversíveis: ajustar nomes de testes, adicionar comentários, completar tipos.
Rodar o comando de verificação, ler o log de falha e levantar uma hipótese da causa.

Tarefas que o humano decide obrigatoriamente

Autorizar (ou não) uma mudança que entra numa área proibida.
Exclusão de arquivos, operação em banco de produção, lógica de cobrança, force push.
A decisão final de fazer merge de uma mudança grande de arquitetura.
Parar ou não quando o diff cresceu mais do que o esperado.

Meu critério é simples. O que dá pra reverter com git mesmo se der errado, delego à IA. O que não dá pra reverter, o humano aperta o botão. Só de respeitar essa linha, você não desaba já no primeiro dia.

Modelo de prompt pra copiar e colar

Antes de entrar na primeira edição, eu mando isto. O segredo é não deixar escrever de cara, e sim fazer ela devolver um plano primeiro.

Este é um repositório existente que estou tocando pela primeira vez. Siga estas regras.

[Pode ler] apenas src/ e docs/ e arquivos de teste
[Não toque] .env / autenticação / pagamento / migrações de banco / config de deploy de produção
[Meta desta vez] apenas UMA melhoria pequena e reversível (ex.: ajustar nome de teste)
[Verificação] após a mudança, rode sempre `npm run build` e cole o resultado

Ainda não altere o código.
Primeiro, devolva o plano de "qual arquivo vai corrigir e como" e
reescreva as regras acima com as suas próprias palavras.

Se o plano que voltar repetir corretamente as minhas restrições, passou. Se tentar ampliar o escopo, eu paro ali mesmo. Se o plano estiver bom, sigo com “agora faça exatamente isso e rode até o build”.

Mantenha a fronteira em código

Regra no papel a gente esquece. Por isso eu também guardo o plano de onboarding num formato que a máquina lê. O script abaixo roda como está. Troque o miolo pelos dados do seu repositório.

#!/usr/bin/env bash
# Reúne o plano de onboarding do repositório existente em um único JSON
set -euo pipefail

cat > onboarding-plan.json <<'JSON'
{
  "goal": "concluir com segurança a primeira edição em um repositório existente",
  "readOnlyCommands": [
    "git status --short",
    "git ls-files | head -50",
    "grep -rn \"TODO\\|FIXME\" src | head -20"
  ],
  "protectedAreas": [".env", "billing", "auth", "db/migrations", "deploy/prod"],
  "firstTask": "uma pequena melhoria reversível em doc ou teste",
  "proofCommand": "npm run build",
  "rollback": "git diff -- path/to/changed-file && git checkout -- path/to/changed-file"
}
JSON

echo "=== Plano de onboarding ==="
cat onboarding-plan.json

echo ""
echo "=== Diff atual (vazio = nada editado) ==="
git status --short

Esse script não tem nada de chamativo. O valor está em fixar num arquivo as “áreas proibidas” e os “comandos de prova” antes de começar a trabalhar. Basta trocar protectedAreas pelos lugares perigosos do seu repositório e você já tem o mapa do primeiro dia.

Ter também um comando de verificação dá tranquilidade. Num projeto Node.js, esta checagem mínima confere de forma mecânica se nada quebrou.

// check.mjs : script mínimo que verifica apenas se o build passa
import { execSync } from "node:child_process";

try {
  // troque pelo comando de verificação do seu projeto
  execSync("npm run build", { stdio: "inherit" });
  console.log("Verificação OK: o build passou. Revise o diff.");
} catch (e) {
  console.error("Verificação NG: o build quebrou. Não faça merge e investigue a causa.");
  process.exit(1);
}

Se node check.mjs der verde, mando o diff pra revisão; se der vermelho, paro. Só essa única peça já elimina o acidente de fazer merge no “deve estar funcionando”.

Como usar em três cenários reais

Se algum cenário se parecer com o seu, não refaça o procedimento — só troque os nomes pelo seu contexto.

1. Herança de um site de conteúdo Faça a IA ler primeiro onde ficam os dados dos artigos, a pasta de imagens, o comando de build e as páginas de produto, pra entender o terreno. A primeira edição é só “corrigir um link quebrado”. Se o build passar, mande pra revisão. Reescrita em massa do texto só depois que ficar claro que é seguro.

2. Código de um SaaS Deixe explícito nas áreas proibidas: autenticação, cobrança e migrações de banco. Restrinja a primeira tarefa a algo como “tornar a descrição dos testes mais clara” e só avance após a aprovação de uma pessoa. Afrouxar aqui faz uma “melhoria gentil” cair na lógica de pagamento, e aí o coração gela.

3. Repositório legado antigo “Modernize o sistema todo” é frase proibida. O diff vira algo grande demais pra ler. Em vez disso, comece com um passo pequeno que dá pra validar no build: corrigir um typo em nome de função, ajustar nome de teste. Deu certo uma vez, dê o próximo passo no mesmo molde.

Todos os exemplos têm um “ponto de parada”. É por existir esse ponto que o trabalho não se espalha sem fim.

Exemplos de erro e como corrigir

Vou ser honesto. Nas primeiras vezes, eu fiz besteira em todas.

Pedi sem escrever as áreas proibidas → o diff ficou grande demais pra revisar e tive que jogar tudo fora. A correção é simples: antes de refinar o texto do pedido, reduza os arquivos que a IA pode ler. Quanto mais estreito o escopo, mais estreita a margem de surto da IA.

Rodei o build só depois de tudo pronto → perdi a noção de qual edição quebrou. Hoje rodo a verificação a cada arquivo corrigido. Como fica registrado o momento exato em que quebrou, a causa aparece na hora.

Confiei a conferência só aos meus olhos → em dia corrido, sempre escapa algo. O que “a máquina consegue saber” eu entrego literalmente à máquina: se o build passa, o resultado dos testes, link quebrado. Reservo os olhos humanos só pras decisões de design que a máquina não pega. Isso cortou muito as revisões de madrugada.

Deixo os tropeços registrados no artigo porque, só com casos de sucesso, o leitor não percebe quando ele mesmo está numa situação perigosa. Anotar em poucas linhas qual pedido se espalhou demais e qual verificação faltou impede que o “eu do futuro” caia no mesmo buraco.

Perguntas frequentes

P. Qual deve ser a primeira edição? R. Escolha algo que “dá pra reverter com git checkout mesmo se errar”. Ajustar nome de teste, adicionar comentário, corrigir um erro de digitação são opções seguras. Funcionalidade nova ou mudança de configuração não combinam com o primeiro dia.

P. Quão detalhadas devem ser as áreas proibidas? R. Basta listar “os lugares sem volta se quebrarem”. .env, autenticação, cobrança, config de deploy de produção e migrações de banco. No começo, cobrir esses cinco já evita quase todo acidente fatal.

P. Dá pra pular a etapa de fazer o Claude Code devolver o plano? R. Recomendo não pular. Esse trabalho extra de fazê-lo reescrever o plano permite descobrir o desvio de escopo antes da edição. É um custo muito mais barato do que perceber depois que o código já foi escrito.

P. O comando de verificação só com o build é suficiente? R. No primeiro dia, um build basta. Quando pegar o jeito, adicione um teste relacionado. Tentar rodar a suíte inteira desde o início pesa demais e você não mantém o hábito. Comece pequeno e aumente quando os logs de sucesso se acumularem.

P. O que cuidar ao adotar em equipe? R. Escreva as fronteiras num arquivo compartilhado como o ONBOARDING.md, pra todo mundo usar o mesmo mapa. Se as áreas proibidas variam de pessoa pra pessoa, o critério de revisão também balança.

O que aconteceu quando testei de verdade

Depois do “acidente dos 23 arquivos” lá do começo, mudei a ordem do onboarding. Parei de caçar o prompt perfeito e passei a fixar antes, no onboarding-plan.json, as áreas proibidas e o comando de verificação. Só com isso, o acidente de mexer em pagamento ou config de produção foi a zero.

No dia em que restringi a primeira edição a “ajustar nome de teste”, o diff coube em 8 linhas e o build passou de primeira. A revisão não levou nem 2 minutos. Já num outro dia em que pedi sem definir o escopo, o diff inchou de novo e joguei tudo fora. A diferença não estava na inteligência do modelo, e sim em ter desenhado o mapa antes de entrar.

Quem quer fixar esse molde de mexer com segurança em código alheio usando casos reais da própria equipe, eu monto junto o caminho de adoção sob medida no treinamento e consultoria. Comece hoje mesmo listando as cinco áreas proibidas do seu próprio repositório.