Primeiro dia com Claude Code num repositório alheio: como escolher a 1ª tarefa sem quebrar nada

No meu terceiro dia de empresa nova, me jogaram umas 150 arquivos de código ligados a pagamento. Documentação, quase nenhuma. Qualquer pessoa a quem eu perguntava dizia a mesma coisa: “está funcionando, melhor não mexer”. Então pedi pro Claude Code: “entenda esse repositório e arruma o que estiver estranho”.

Dez minutos depois, o Claude respondeu cheio de confiança: “organizei 20 arquivos”. Abri o diff e fiquei branco. Ele tinha reformatado os arquivos SQL de migração, reordenado o .env.example e, de quebra, “otimizado” por conta própria o tempo de espera do retry de pagamento, cortando pela metade. Era código que funcionava. Mas se aquilo tivesse ido pra produção, o telefone não pararia de tocar com reclamações de cobrança dupla.

O problema não foi a inteligência do Claude. Foi simplesmente que o escopo que eu entreguei no primeiro dia era largo demais. Para delegar com segurança o código gigante de outra pessoa, antes de procurar uma IA mais esperta, decida em 30 minutos a “ordem de leitura, as zonas intocáveis, a primeira tarefa pequena e como conferir”. Só isso já elimina quase todos os acidentes do dia um. Hoje vou destrinchar o conteúdo desses 30 minutos num formato que você copia e cola.

Pontos principais

• No primeiro dia num código existente, “olhe tudo e conserte” é o pedido mais perigoso. Você dispara com o escopo vago.
• Nos primeiros 30 minutos você não cria um documento de arquitetura, e sim uma nota de uma página só para escolher com segurança a primeira tarefa.
• A nota tem só quatro itens: ordem de leitura, zonas intocáveis, primeira tarefa pequena e o comando que confirma que terminou.
• A primeira tarefa fica restrita a um “lugar fácil de reverter”. Texto, rótulo de botão ou nome de teste caem bem aqui.
• Você delega à IA até “investigar e rascunhar”. Banco de produção, cobrança, exclusão e o botão de publicar são pressionados por uma pessoa.

Por que o primeiro comando do dia um já dá errado

O Claude Code é rápido. E é justamente por ser rápido que, se a informação inicial for ampla, ele vai produzir até os diffs mais irrelevantes com toda a energia.

Um novato humano pergunta: “posso mexer aqui?”. A IA não pergunta. Por gentileza, ela alarga o escopo. Se você diz “organize”, ela organiza mesmo até os cantos. A reformatação da migração, a “otimização” do retry de cobrança, tudo isso ela faz achando que está ajudando.

Por isso, o que fazer no dia um não é ler o código a fundo, nem montar um plano de melhoria impressionante. É traçar fronteiras. Até onde ela pode agir sozinha e a partir de onde precisa perguntar para uma pessoa. Quando você desenha essa linha antes, o pedido ao Claude muda de “pense livremente” para “trabalhe dentro deste limite e deixe prova”. Traçar a linha leva 30 minutos. Não é preciso entender o código inteiro.

A nota de uma página do dia um, feita em 30 minutos

Pode ser num papel ou num bloco de notas. Você preenche só estes quatro campos. A ordem também tem significado.

1. Defina uma ordem de leitura estreita. Em vez de todos os arquivos de cara, só README e package.json. Isso já mostra qual linguagem é, como se inicia e que ferramentas usa. Depois, duas ou três telas ou rotas principais. É o suficiente.
2. Escreva as zonas intocáveis. Cobrança, autenticação de login, variáveis de ambiente, migrações de banco de dados. Aqui você deixa explícito: “pode ler, mas não reescreva”. Se você não escrever, o Claude trata essas áreas como alvo normal de edição.
3. Escolha uma única primeira tarefa pequena. Restrita a um lugar fácil de reverter. O texto no fim de um artigo, o rótulo de um botão, um nome de teste confuso. Algo que, se der errado, volta na hora.
4. Decida como conferir que terminou. O build passa? O diff está dentro do esperado? A tela quebrou? Você julga pelo resultado de um comando, não pelo “clima”.

Quando você preenche esses quatro, some a maior parte da insegurança do dia um. Porque você passa a controlar não “o que o Claude vai aprontar”, mas “até onde eu deleguei pro Claude”.

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

Deixar a fronteira escrita em palavras evita que você hesite toda vez. A divisão que eu uso é esta.

Atividade	Delegar ao Claude	Decisão humana
Ler o código e resumir a estrutura	Sim, deixe rascunhar	A compreensão final você confirma
Sugerir as zonas intocáveis	Sim, peça candidatos	Cobrança e auth quem fecha é sempre a pessoa
Corrigir textos e rótulos	Sim, pode delegar	Você olha o diff e aprova
Escrever no banco de produção	Não	Pessoa executa na mão
Exclusão, publicação, cobrança	Não	Pessoa pressiona o botão

O ponto é colocar todas as operações perigosas, desde o início, do lado de “perguntar para uma pessoa”. Só as operações que você confirmou serem seguras são promovidas depois para automático. O contrário não. Liberar amplo no começo e apertar depois do acidente é fazer na ordem errada.

Quem quiser entender essa lógica com mais calma pode ler junto o Guia do primeiro passo com Claude Code e o Checklist dos primeiros 30 minutos com Claude Code. Aí o movimento do dia um fica bem mais conectado.

Modelo de pedido pronto para copiar e colar

O truque é não deixar a IA editar logo de cara. No começo você pede só para “ler e resumir numa tabela”.

É a primeira vez que mexo neste repositório. Ainda não edite nada.
Leia na ordem abaixo e devolva o resultado em uma tabela.

1. Leia o README e o package.json e liste a linguagem, o comando de inicialização e as dependências principais
2. Liste, com o caminho do arquivo, as áreas perigosas de tocar (cobrança, autenticação, variáveis de ambiente, migrações de banco)
3. Aponte 3 candidatos a "primeira tarefa pequena" fáceis de reverter, com a justificativa de cada um
4. Para cada candidato, escreva o comando que confirma a conclusão (build, conferência de diff etc.)

Repito: nesta etapa, não edite um único caractere.

Quando a tabela voltar, confira com seus próprios olhos se nenhuma “zona intocável” ficou de fora. Se faltou, acrescente, e só então delegue uma única tarefa.

Dos candidatos anteriores, avance apenas com ◯◯ (corrigir o texto no fim do artigo).
Não toque em nada de cobrança, autenticação, variáveis de ambiente ou migrações.
Depois de editar, rode `npm run build` e mostre o diff com `git diff --stat`.
Se algo quebrar, explique a causa e a correção em uma linha e então pare.

Se você já deixar as “zonas intocáveis” escritas no CLAUDE.md, não precisa colar esse aviso toda vez. A forma de escrever está reunida em Boas práticas de CLAUDE.md.

Um pequeno código que deixa a máquina conferir

Se você confiar na memória humana para “só entregar depois de preparar direito”, num dia corrido isso vai falhar. Então deixe a máquina julgar se a nota de uma página tem o mínimo necessário. O código abaixo roda direto no Node.js.

// Confere por máquina se a nota de uma página do dia um está "pronta para entregar ao Claude"
const repoMap = {
  goal: "escolher uma única primeira tarefa fácil de reverter",
  readFirst: ["README.md", "package.json", "src/routes/"],
  protectedAreas: [".env", "billing/", "migrations/", "wrangler.toml"],
  firstTask: "corrigir o texto no fim do artigo (sem tocar no código de pagamento)",
  proofCommands: ["npm run build", "git diff --stat"],
};

function isReady(map) {
  const reasons = [];
  if (map.readFirst.length < 2) reasons.push("ordem de leitura estreita demais/não definida");
  if (map.protectedAreas.length === 0) reasons.push("zonas intocáveis vazias");
  if (!map.proofCommands.some((c) => c.includes("build"))) {
    reasons.push("falta comando de conferência de build");
  }
  if (!map.firstTask) reasons.push("primeira tarefa não escolhida");
  return { ready: reasons.length === 0, reasons };
}

const result = isReady(repoMap);
console.log(result.ready ? "Pode entregar" : "Ainda não entregue: " + result.reasons.join(", "));

Ao rodar, sai assim.

node check-repo-map.mjs
# => Pode entregar

Se você esvaziar o protectedAreas e rodar, aparece “Ainda não entregue: zonas intocáveis vazias”. É só isso, mas já barra antes de entregar o acidente mais comum de todos: “rodar tudo no automático tendo esquecido de escrever as zonas intocáveis”. Cole essa nota no CLAUDE.md ou na issue e o seu eu de amanhã, e os colegas, reutilizam a mesma decisão.

Três situações em que isso funcionou de verdade

1. Operação de blog: protegendo o link do artigo que dá dinheiro Quando eu quero corrigir só a chamada no fim de um artigo popular e peço ao Claude “melhore o texto”, ele acaba mexendo até na URL do link do produto. Aí eu fecho o escopo: “pode corrigir o texto, mas não mude um caractere da URL de destino. Depois mostre o build e o diff”. Assim eu refino só o texto sem quebrar o link que está ligado direto à receita.

2. SaaS: não chegar perto do processamento de cobrança Quando o texto explicativo de uma tela de configuração está confuso, o alvo da melhoria é só o texto exibido. A lógica de cobrança e de mudança de plano não se toca. Se você colocar billing/ nas “zonas intocáveis” da nota, evita que o Claude, por gentileza, meta a mão no processamento de retry.

3. Ferramenta interna: corrigir só o nome da coluna de saída Um pedido sobre o nome confuso de colunas numa exportação CSV. O que se corrige é só o texto do nome da coluna; a lógica de agregação é outra história. Quando você pede “só o texto exibido do nome da coluna. Não toque na fórmula de cálculo. Mostre a saída com dados de exemplo”, a conferência termina num instante.

O que as três têm em comum não é falta de capacidade do Claude, e sim este único ponto: fronteira fina causa acidente. Quanto mais clara você escreve a fronteira, mais a IA se move com segurança e rapidez.

Armadilhas comuns e como corrigir

Armadilha 1: mandar ler todos os arquivos logo de início. Gasta tempo e tokens com formatação de baixa importância e a mudança que importa fica fraca. A correção é limitar a leitura a README e package.json mais duas ou três rotas principais. A visão geral você amplia aos poucos, depois de terminar a primeira tarefa.

Armadilha 2: não escrever as zonas intocáveis. O Claude trata cobrança, autenticação e configuração de deploy como alvo normal de edição. A correção é escrever a lista de proteção com o caminho dos arquivos e deixá-la fixa no CLAUDE.md. Avisos verbais são esquecidos; o que está escrito permanece.

Armadilha 3: acreditar no “pronto” sem definir o comando de conferência. Você acaba tendo que adivinhar a cada vez se o relatório de conclusão está certo. A correção é incluir, desde o pedido, “rode o build e mostre o diff”. Um HTTP 200 ou uma resposta que parece boa não são prova de sucesso. Confie só no resultado de uma execução de verdade.

Perguntas frequentes

P. Não é mais seguro entender a visão geral do código existente antes de delegar? No ideal sim, mas no dia um a compreensão geral não termina. Se você esperar terminar, nada anda. Então primeiro feche as “zonas intocáveis” e comece por uma tarefa fácil de reverter. Entender enquanto trabalha é mais rápido.

P. Quão pequena deve ser a primeira tarefa? A medida é algo que se resolve em um arquivo, um texto, um comando. Se você pede grande, o Claude gentilmente alarga o escopo. Avance para a próxima só depois de conferir o build e a captura de tela; assim você não perde velocidade e ainda reduz o tempo de reverter.

P. Onde é melhor escrever as zonas intocáveis? Escrever no CLAUDE.md é o que mais dura. Colar no prompt toda vez falha num dia corrido, você esquece. Se ficar num único lugar, como regra do projeto, vale automaticamente até em trabalhos novos.

P. Falei “não toque” e mesmo assim o Claude tocou. Na maioria das vezes a proteção parou no nome do arquivo e você não especificou o diretório inteiro. Em vez de só billing.js, escreva o intervalo, como billing/. Se ainda assim ultrapassar, coloque no começo do pedido um passo a mais: “antes de editar, declare os arquivos-alvo e só então prossiga”. Costuma travar.

P. Preciso refazer essa nota toda vez? Faça uma vez por repositório e depois reaproveite. Colando no CLAUDE.md e na issue, o seu eu de amanhã e os colegas herdam a mesma decisão. Quando surgir uma nova área a proteger, é só acrescentar.

O que aconteceu quando testei de verdade

Depois do caso do código de pagamento lá do começo, testei o mesmo procedimento em outro repositório existente. Primeiro, sem deixar editar nada, pedi só a tabela com o modelo de pedido acima, e ele de fato listou billing/ e migrations/ como candidatos a área protegida. Mas o arquivo de variáveis de ambiente ficou de fora, então eu mesmo acrescentei o .env. Reforçou a importância de seguir assumindo que uma pessoa vai revisar esse ponto.

A primeira tarefa eu restringi a uma única correção de texto no fim de um artigo e conferi até npm run build e git diff --stat. O diff foi de apenas 7 linhas e não tocou um caractere no código de pagamento. Também rodei de verdade o código de conferência e confirmei que, com o protectedAreas vazio, ele trava com “Ainda não entregue”. Em vez de procurar uma IA mais esperta, decidir antes um escopo pequeno que volta na hora se você tropeçar. Foi isso que mais funcionou no primeiro dia delegando código alheio.

Se você está na fase de definir, em equipe, como introduzir o Claude Code no código existente da empresa, em treinamento e consultoria dá para organizar junto a forma de traçar as fronteiras olhando um repositório real. Vale também conferir os pré-requisitos oficiais em Anthropic Claude Code getting started.