Claude Code na primeira hora em código alheio: desenhe o mapa antes de consertar

No meu primeiro dia depois de herdar um projeto, abri o repositório de uma ferramenta interna que o desenvolvedor anterior tinha deixado. O README tinha três linhas e a última atualização era de oito meses atrás. Pedi ao Claude Code, meio na esperança, “entenda este projeto e ajuste o texto da tela de login”. Cinco minutos depois ele já tinha “aproveitado para organizar” os arquivos de configuração de autenticação e até um script de deploy de produção que ninguém encostava havia meses.

Por sorte percebi pelo git status e revertí tudo. Mas só de pensar que, se eu não tivesse notado e tivesse feito git commit, ainda hoje me dá um frio na espinha. O problema não era a inteligência do modelo. O problema era que eu deleguei o trabalho sem saber onde eu podia mexer.

A primeira hora dentro de um código alheio não é hora de consertar, é hora de desenhar o mapa. Neste artigo eu reúno como desenhar esse mapa, num passo a passo que evita acidentes mesmo num repositório que você está vendo pela primeira vez.

Pontos principais

• Na primeira hora você não “conserta”, você “desenha o mapa”. Separe antes os lugares onde pode mexer dos lugares onde não pode.
• O que se delega ao Claude Code é só “ler e listar”. Quem decide o que vira área protegida é a pessoa.
• Antes de começar a consertar, escolha sempre um comando de prova (build ou teste). É ele que vira a evidência de que “ficou pronto”.
• O primeiro conserto fica limitado a algo pequeno, que dá para reverter com um único comando do git.
• Anote o que você entendeu em uma única nota. Assim a próxima pessoa a entrar no mesmo repositório (incluindo o seu eu futuro) não precisa refazer a mesma investigação.

Por que o acidente acontece logo na primeira hora

Os tropeços num repositório novo quase nunca vêm da dificuldade do código. Vêm de não enxergar o formato do repositório.

Qual pasta é a tela, onde fica a lógica de bastidores, qual arquivo é a configuração de produção. Sem saber isso, quando você pede “conserta aí de um jeito legal”, o Claude Code reescreve uma área ampla de boa fé. A IA, a menos que você diga “aqui não pode mexer”, entende que é um lugar onde pode mexer.

Projetos herdados são especialmente perigosos. As regras implícitas do desenvolvedor anterior, os vícios de nomenclatura, aquele comentário desativado que sobrou por algum motivo. Esse contexto não está escrito em lugar nenhum do código. Nem mesmo um humano entende tudo no primeiro dia. Justamente por isso, a primeira coisa a fazer não é editar, e sim desenhar o mapa.

Os 4 passos para desenhar o mapa

A ordem importa. Defina o que ler, defina a área protegida, defina o comando de prova e, só no fim, conserte uma coisinha pequena. Siga nesta sequência.

Passo 1: escreva a meta de hoje em uma frase

“Entender este projeto” é amplo demais. Tanto o Claude Code quanto a pessoa perdem o ponto de parada com uma meta tão larga.

Em vez disso, escreva assim: “ajustar o texto da tela de login em um único lugar e confirmar que o build passa”. Uma meta que cabe em uma frase também deixa óbvio, num relance, se você terminou.

Passo 2: separe o que pode ler do que não pode tocar

Aqui está o centro do mapa. Antes de entregar ao Claude Code um “pode ler tudo”, você coloca em palavras, primeiro, os lugares onde não se pode mexer.

O que eu coloco como área protegida toda vez é: autenticação, cobrança, arquivos de variáveis de ambiente (.env) e os scripts de deploy de produção. Errar nesses pontos causa um estrago grande e, ainda por cima, é difícil de reverter. Por isso, no começo, deixo explícito: “pode ler, mas não escreva”.

Passo 3: decida o comando de prova primeiro

Mesmo que digam “está consertado”, o que prova que está? Decida isso antes.

Na maioria dos projetos, o comando de build ou o comando de teste serve de prova. O npm run build passa, o npm test fica verde. Se você decidir esse único comando antes de consertar, não precisa engolir o “pronto, terminei” do Claude Code de boa fé, e sim julgar pelo veredito da máquina.

Passo 4: apenas um conserto pequeno e reversível

Com o mapa pronto, o primeiro conserto não pode ser ganancioso. Escolha uma coisa só que dê para reverter com um único git checkout: ajuste de texto, adição de comentário, correção de um erro de digitação óbvio.

Segure o impulso do “já que estou aqui, faço aquilo também”. Diffs grandes ninguém consegue revisar, e o retorno em caso de acidente fica trabalhoso.

O que delegar ao Claude Code e o que decidir por conta própria

No trabalho de desenhar o mapa, o que se delega e o que se segura na mão. Misturar isso é o que gera o acidente do começo.

Tarefa	Responsável	Motivo
Mapear lista de arquivos e estrutura de pastas	Claude Code	A leitura mecânica é rápida e precisa
Investigar “onde fica esta funcionalidade?”	Claude Code	É bom em busca e resumo
Decidir o que vira área protegida	Pessoa	O tamanho do estrago depende de contexto. A IA não conhece
Decisão final do comando de prova	Pessoa	Quem conhece as particularidades do projeto é a pessoa
Mudanças em produção, cobrança e autenticação	Pessoa	Operações difíceis de reverter precisam de aprovação humana

O princípio é simples. Ler e listar você delega. As decisões difíceis de reverter você segura. Só as operações que você confirmou serem seguras é que você vai, depois, promovendo para o Claude Code fazer sozinho.

O desenho detalhado das permissões está em outro artigo. Se ficou na dúvida sobre o que travar primeiro, dê uma olhada no guia de permissões.

Prompt para desenhar o mapa, pronto para colar

Este é o prompt que eu de fato uso na primeira hora. Cole do jeito que está e troque só o nome do repositório pelo seu.

Estou mexendo neste repositório pela primeira vez. Não edite nada ainda.
Investigue os pontos abaixo, em ordem, e me reporte o resultado em tópicos.

1. A estrutura de pastas do nível superior e o papel de cada uma (pode supor, mas indique que é suposição)
2. Os comandos de build, teste e inicialização (a partir do package.json ou do README)
3. A localização dos arquivos ligados a autenticação, cobrança, variáveis de ambiente e deploy de produção
4. Em qual arquivo está o "texto da tela de login"

Depois do relatório, o conjunto de arquivos do item 3 fica, desta vez, "somente leitura, edição proibida".
A única coisa que pode editar é o único arquivo encontrado no item 4.

O ponto é cravar logo na primeira linha “ainda não edite”. Sem isso, existe IA que começa a consertar de carona com a investigação.

Script de verificação que roda quando colado

Com o mapa pronto, dá tranquilidade poder rodar a mesma checagem antes e depois do conserto. O script abaixo verifica se o build passa antes e depois da mudança e se o diff não se espalhou demais. Roda em Node.js.

// verify-edit.mjs
// Confere se o build passa antes/depois do conserto e se o diff nao ficou maior que o previsto
import { execSync } from "node:child_process";

// Defina o limite de arquivos alterados, dentro do que da para reverter com um comando
const MAX_CHANGED_FILES = 3;

function run(cmd) {
  return execSync(cmd, { encoding: "utf8" }).trim();
}

try {
  // Conta o numero de arquivos alterados
  const changed = run("git diff --name-only")
    .split("\n")
    .filter(Boolean);

  console.log(`Arquivos alterados: ${changed.length}`);
  changed.forEach((f) => console.log(`  - ${f}`));

  if (changed.length > MAX_CHANGED_FILES) {
    console.error(
      `O diff esta amplo demais (${changed.length} > ${MAX_CHANGED_FILES}).`,
    );
    console.error("Reverta com git checkout e divida o conserto em partes menores.");
    process.exit(1);
  }

  // Confere se nao houve toque na area protegida
  const protectedHits = changed.filter((f) =>
    /(^|\/)\.env|auth|billing|deploy/i.test(f),
  );
  if (protectedHits.length > 0) {
    console.error("Ha mudancas na area protegida:");
    protectedHits.forEach((f) => console.error(`  - ${f}`));
    process.exit(1);
  }

  // Confere se o build passa (troque conforme o seu projeto)
  console.log("Verificando o build...");
  run("npm run build");
  console.log("Build OK. O conserto ficou dentro do escopo seguro.");
} catch (err) {
  console.error("A verificacao falhou:", err.message);
  process.exit(1);
}

Execute com node verify-edit.mjs. Se houver arquivos alterados demais, ou se a área protegida tiver sido tocada, ele para ali mesmo. O acidente do começo, aquele em que “até os arquivos de autenticação foram organizados”, teria sido barrado de antemão se eu tivesse passado por este script.

Três situações em que funciona

Para deixar concreto em que tipo de repositório isto serve, listo três padrões que eu mesmo testei.

1. Ferramenta interna herdada Quando você entra numa base de código sem documentação. Primeiro mande listar a estrutura de pastas e os comandos de inicialização, e fixe a autenticação e os arquivos de configuração como área protegida. O primeiro conserto deve ser algo cujo resultado se vê a olho nu, como trocar um rótulo da tela de administração.

2. Primeira contribuição a um repositório público Quando você abre um Pull Request pela primeira vez num projeto open source de outra pessoa. Mande identificar primeiro o comando de teste e envie um conserto pequeno mantendo o npm test verde. Um conserto reversível de um único arquivo costuma ser aceito com mais facilidade do que uma proposta ampla de melhoria.

3. Reinício de um projeto antigo Quando você retoma um código parado há meio ano. Mande o Claude Code investigar “até onde ainda funciona” e mapeie os pontos de entrada quebrados. Conserte começando pelo lugar mais fácil de reverter.

Armadilhas e como corrigir

Armadilha 1: tentar consertar tudo de uma vez Com o “já que estou aqui, faço a refatoração também”, o diff incha para 50 arquivos e ninguém consegue revisar. A correção é, com o script de verificação acima, impor um limite de número de arquivos alterados. Se passar, reverta uma vez e divida.

Armadilha 2: dar por concluído só porque o build passou Mesmo que o build passe localmente, a tela não está necessariamente como você imagina. Num ajuste de texto, fechar o ciclo só acontece quando você abre de fato aquela tela e confere o texto com os próprios olhos.

Armadilha 3: comunicar a área protegida só de boca Mesmo dizendo “não mexa na autenticação” no prompt, isso pode ser esquecido no meio de um trabalho longo. A correção é barrar mecanicamente, pelo script de verificação, qualquer mudança na área protegida. Proteja com um comando, não com a memória das pessoas.

Armadilha 4: não guardar o mapa que você investigou Mesmo gastando uma hora para entender tudo, sem guardar uma nota você refaz a mesma investigação na próxima vez. Escrever a estrutura de pastas, o comando de prova e a área protegida em uma única nota salva o seu eu futuro.

Essa nota com o mapa funciona ainda melhor se você a escrever no CLAUDE.md como regra do projeto. Como escrever está reunido em boas práticas do CLAUDE.md.

Perguntas frequentes

P. Na primeira hora, posso mesmo não consertar nada? R. Pode até consertar, mas que seja só “uma coisinha pequena e reversível”. Usar o resto do tempo desenhando o mapa, no fim das contas, reduz os acidentes e sai mais rápido.

P. É perigoso entregar ao Claude Code um “pode ler tudo”? R. Se for só ler, não é perigoso. O perigoso é a permissão de “escrever”. Leitura ampla, escrita estreita. Essa é a divisão básica.

P. E nos projetos em que eu não sei qual é o comando de prova? R. Primeiro mande o Claude Code levantar candidatos a partir do package.json e do README. Se ainda assim ficar incerto, use por enquanto, como verificação mínima, só conferir que o git status não mostra diff.

P. Dá para fazer a mesma coisa no PowerShell? R. Dá. A lógica de contar o resultado de git diff --name-only e comparar com um limite também se escreve direto no PowerShell. Reescreva o script de verificação conforme o ambiente que você usa.

P. Um iniciante consegue rodar este passo a passo? R. Consegue. Aliás, quanto mais iniciante, mais funciona. Mesmo sem entender o código por completo, se você decidir antes “onde pode mexer”, evita o grande acidente. Quem quer fortalecer a base desde o começo, ler antes o guia para iniciantes deixa tudo mais fluido.

O que aconteceu quando testei de verdade

Este passo a passo foi algo que montei para meu próprio uso depois do acidente do começo. Ao testar, o que mais funcionou foi colocar no script de verificação o “limite de número de arquivos alterados” e a “checagem automática da área protegida”.

De fato, rodando umas três vezes num repositório herdado, em uma delas ele parou porque o número de arquivos alterados ultrapassou o limite. Olhando o conteúdo, o Claude Code tinha reescrito até um componente compartilhado de carona com o ajuste de texto e, se eu tivesse deixado passar, teria virado um diff de alcance imprevisível. Graças à parada, consegui dividir o conserto em dois e enviá-los separados.

Não é “se eu deixar com a IA inteligente, vai dar tudo certo”, e sim “delego dentro de um escopo que eu consigo reverter mesmo se tropeçar”. Só de desenhar o mapa primeiro, a sensação da primeira hora muda por completo. Se você quer, em equipe, compartilhar essa divisão com pessoas que não são da área técnica, a porta de entrada para não desenvolvedores também ajuda.

O jeito oficial de usar o Claude Code você confere também na documentação oficial da Anthropic. Quem quer firmar as próprias regras de operação e deixá-las num formato que a equipe consiga reproduzir, na consultoria e treinamento a gente mapeia juntos um repositório concreto.