Como colocar o Claude Code para trabalhar em um projeto legado que você não escreveu

Você clonou o repositório, abriu o editor e bateu de frente com 4 pastas que ninguém sabe explicar, zero README útil e um utils.js de 2 mil linhas

É o clássico: o dev que escreveu aquilo saiu da empresa faz dois anos, e agora o legado é seu

Aí bate a tentação de soltar o agente na base inteira e pedir "refatora isso aqui"

Tome cuidado! Numa base grande e desconhecida, esse é o caminho mais rápido pra receber uma mudança errada com cara de mudança certa: o código compila, o teste (se existir) passa, e três semanas depois alguém descobre que uma regra de negócio silenciosa foi pro espaço

A tese deste post é simples: primeiro você faz o Claude Code mapear e EXPLICAR, depois deixa ele editar, e sempre dentro de uma área delimitada

Bora ver na prática?

O que você precisa ter antes de começar

Nada aqui exige mexer no código do projeto ainda, beleza? A ideia é justamente não mexer nos primeiros passos

O checklist mínimo:

• repositório clonado e rodando localmente (nem que seja só o build, sem o ambiente completo)
• Claude Code instalado e autenticado na sua máquina
• a decisão de ONDE você vai iniciar a sessão

Esse terceiro item parece bobo, mas é o que mais muda o resultado

Os arquivos CLAUDE.md do diretório atual e dos diretórios acima dele são lidos no início da sessão e entregues ao modelo logo depois do system prompt

Formação Recomendada

Formação Claude Code

Domine Claude Code do absoluto zero até o avançado

• 120 aulas
• 4 projetos
• 9h 45min

Conhecer formação

Ou seja: abrir o terminal em packages/api/ ou na raiz do monorepo não é a mesma coisa, o contexto que entra é diferente

Mais um detalhe de calendário que vale anotar: hoje o auto mode ainda NÃO é o padrão

Ele passa a ser o modo de permissão padrão em novas sessões do Claude Code nos planos Pro, Max e Team a partir de 14 de agosto de 2026

Nesse modo, um modelo classificador separado revisa as ações antes de executá-las

Repare que isso mexe no modo em que a sessão NOVA começa, e não no ciclo de modos que você vê no Passo 1

Então dá uma olhada em que modo sua sessão está antes de assumir qualquer coisa 🙂

Passo a passo para colocar o Claude Code num projeto legado

A sequência abaixo é a régua inteira: mapear, validar, documentar, delimitar, e só então editar

1. Abra a sessão em plan mode

É o passo que separa "exploração segura" de "estrago silencioso"

No plan mode o agente pesquisa e propõe: ele lê arquivos, roda comandos de exploração e escreve um plano, mas não edita o código-fonte até o plano ser aprovado (a exceção são sessões com bypass permissions)

claude --permission-mode plan

Já dentro de uma sessão, Shift+Tab cicla entre os modos: default → acceptEdits → plan

Esse é o ciclo que a documentação de modos de permissão lista, e o auto mode não aparece nele: se o auto mode entra nessa tecla depois de 14 de agosto, a doc de modos ainda não diz, então confira na hora

O erro comum deste passo: achar que "vou tomar cuidado" substitui o modo

Não substitui, o cuidado é você, o bloqueio é o modo

2. Peça o mapa da base delegando ao subagente Explore

O Claude Code tem um subagente Explore embutido, somente leitura, feito exatamente pra buscar e entender uma base de código sem fazer alterações

O Claude delega pra ele quando precisa entender o terreno, e na invocação especifica o nível de profundidade: quick, medium ou very thorough

Para um legado grande, profundidade maior no primeiro mapeamento faz sentido: é uma base que você não conhece, não adianta um passeio raso

Um aviso importante que quase ninguém lê na doc: o subagente Explore PULA os arquivos CLAUDE.md e o git status da sessão principal, pra manter a pesquisa rápida e barata

O erro comum deste passo: escrever suas convenções no CLAUDE.md e esperar que o Explore siga elas

Ele não vai ver aquilo, então o que for regra pra pesquisa tem que estar no seu pedido

3. Valide o entendimento em pedaços pequenos

Aqui é onde o legado te agradece

Em vez de "me explica o sistema", pergunte um fluxo por vez: como entra um pedido, o que acontece no login, onde nasce aquele job que roda de madrugada

Um fluxo, uma resposta, uma conferência sua

O histórico do Git também é material de investigação: a documentação da Anthropic cita usar o Claude Code pra buscar no histórico e responder coisas do tipo "quais mudanças entraram na v1.2.3"

Num código sem documentação, o commit é a documentação que sobrou

O erro comum deste passo: aceitar a explicação porque ela soa coerente

Coerente é fácil, correto é o que você confere abrindo o arquivo que ele citou

4. Rode /init e transforme o entendimento em CLAUDE.md

O comando /init analisa a base de código e gera um CLAUDE.md inicial

/init

A própria documentação recomenda tratar esse resultado como PONTO DE PARTIDA e refinar depois com /memory

Faz todo sentido no legado: o /init acerta a estrutura, e você acerta o que só quem apanhou sabe ("esse módulo parece morto mas é chamado por um cron")

O arquivo de projeto mora em ./CLAUDE.md, na raiz do repositório, e o seu pessoal em ~/.claude/CLAUDE.md

A orientação de boas práticas é colocar o do projeto na raiz e commitar na branch principal, assim todo dev que clonar o repositório herda o contexto

O erro comum deste passo: deixar o /init cru e nunca mais voltar nele

Um CLAUDE.md genérico é quase o mesmo que nenhum

5. Delimite a área que ele pode mexer

O Claude Code tem três tipos de regra de permissão: allow (usa sem aprovação), ask (pede confirmação) e deny (impede o uso)

A avaliação segue essa ordem: deny → ask → allow

E elas valem para as ferramentas, incluindo Bash, Read, Edit, WebFetch e MCP

Ou seja: dá pra barrar até a LEITURA de uma área, o que ajuda quando o legado tem pasta de dump, build gerado ou coisa que só serve pra entupir contexto

A precedência das configurações é esta:

Se uma ferramenta é negada em QUALQUER nível, nenhum outro nível libera ela

Isso é ótimo pro time: a trava do projeto não cai porque alguém mexeu na config pessoal

E se o legado depende de pastas fora da raiz (aquele repo irmão que ninguém junta), dá pra conceder acesso de três jeitos: o setting additionalDirectories no .claude/settings.json, a flag --add-dir ao iniciar, ou o comando /add-dir dentro da sessão

claude --add-dir ../lib-interna-legada

Detalhe: o additionalDirectories concede acesso a arquivos e não carrega skills

O erro comum deste passo: liberar geral "só pra destravar" e nunca mais fechar

Vale lembrar que no auto mode as regras de permissão continuam disparando antes do classificador, com uma exceção: regras de allow amplas o bastante pra permitir execução arbitrária de código (tipo python:*) são deixadas de lado nesse modo

6. Aprove o plano e libere UM pedaço pequeno

Agora sim

Plano lido, área delimitada, entendimento conferido: deixa ele editar uma coisa só, pequena, que você consiga revisar inteira

Se der ruim, /rewind reverte código e conversa pra um checkpoint (ou resume parte da conversa)

/rewind

Se você quer ver como isso se encaixa num ciclo completo, do primeiro comando até subir, tem um post aqui sobre o fluxo completo até o deploy

O erro comum deste passo: aprovar o plano e emendar mais três pedidos no mesmo fôlego

Aí você perdeu a unidade de revisão, e revisar virou arqueologia de novo haha

Monorepo, pastas gigantes e times: como dividir o contexto por área

A estratégia muda conforme o formato do legado, se liga

Monorepo: CLAUDE.md aninhado por subpasta

O Claude Code suporta CLAUDE.md aninhado, carregado sob demanda

Iniciando o Claude em packages/api/, ele carrega o packages/api/CLAUDE.md e o CLAUDE.md da raiz, SEM as instruções de packages/web/

E os arquivos CLAUDE.md e CLAUDE.local.md de subpastas abaixo do diretório atual entram em contexto quando o Claude lê arquivos daquelas subpastas

A ordem de carregamento na árvore vai da raiz do sistema de arquivos pra baixo até o diretório de trabalho: foo/CLAUDE.md entra em contexto antes de foo/bar/CLAUDE.md

Traduzindo pro seu legado: contexto comum sobe pra raiz, regra específica desce pra pasta dela

Área com regra própria: skills por subpasta

Quando um pedaço do sistema tem ritual próprio (aquele serviço que só pode ser buildado de um jeito), skills resolvem bem

Elas ficam em .claude/skills/ dentro do diretório e são versionadas junto ao código daquela área, carregando sob demanda quando o Claude julga relevante

Time inteiro herdando o mesmo caminho

Subagentes personalizados são arquivos markdown em .claude/agents/

Slash commands do projeto são arquivos markdown em .claude/commands/, e podem ser versionados no git pro time inteiro

É o que transforma "o Matheus sabe pedir do jeito certo" em "o repositório sabe pedir do jeito certo"

E aqui está o ponto que amarra a seção: segundo a Anthropic, o ecossistema construído em volta do modelo (o harness) determina o desempenho do Claude Code MAIS do que o modelo isolado

Esse harness é formado por cinco pontos de extensão: CLAUDE.md, hooks, skills, plugins e servidores MCP

Não é coincidência que a própria Anthropic conte que usar o Claude Code pra aprendizado e exploração virou o fluxo central de onboarding interno, melhorando o tempo de rampa e reduzindo a carga sobre outros engenheiros

Se você ainda está na dúvida se vale a pena nesse cenário, esse é justamente o caso de uso que a documentação trata como central

Erros comuns e como evitar nos primeiros dias

As respostas foram piorando no meio da sessão

Sintoma: começou ótimo, e depois de um tempo ele passou a esquecer coisa que você já explicou

Causa: a janela de contexto enche rápido e o desempenho degrada conforme ela enche

Solução: cheque com /context, que mostra o uso atual em grade colorida, com sugestões de otimização e avisos de capacidade

Depois escolha: /clear reseta a conversa pra contexto vazio, e /compact pede ao modelo um resumo da conversa e substitui o histórico por esse resumo (processo com perda)

Como prevenir: trabalhe em sessões por fluxo, não em uma sessão eterna que investiga o sistema inteiro

O agente leu meio repositório e queimou contexto à toa

Sintoma: um monte de leitura, pouca conclusão

Causa: pesquisa acontecendo na conversa principal, que é justamente onde você quer espaço livre pra implementar

Solução: peça explicitamente algo como "use subagents to investigate X"

Cada subagente roda em conversa própria: as chamadas de ferramenta e os resultados intermediários ficam dentro dele, e só a mensagem final volta pro agente-pai

Como prevenir: trate pesquisa e implementação como coisas separadas desde o primeiro dia

Ele mexeu onde não devia

Sintoma: apareceu diff em pasta que você nem tinha citado

Causa: faltou regra de deny e faltou delimitar diretório

Solução: monte a delimitação pelas regras de permissão, lembrando da ordem deny → ask → allow, e do fato de que deny em qualquer nível não é liberado por nenhum outro

Vale saber também que, por padrão, comandos em sandbox só podem escrever no diretório de trabalho atual e no diretório temporário da sessão

Como prevenir: decida a área ANTES de aprovar qualquer plano, não depois do susto

O CLAUDE.md não puxou o arquivo que você esperava

Sintoma: você referenciou um doc interno no CLAUDE.md e o agente age como se ele não existisse

Causa: sintaxe e ponto de partida

Solução: a menção com @ importa o arquivo, enquanto entre crases o texto fica literal

Ou seja, @README entre crases é só texto, sem importação

E os caminhos relativos resolvem a partir do diretório de onde o Claude foi iniciado

Como prevenir: confira de onde você abriu a sessão antes de sair caçando bug em regra que estava certa 😀

Conclusão

A régua cabe em uma frase: mapear, delimitar, validar em pedaços pequenos, e só então editar

É o oposto do impulso natural de quem herda uma base grande, e é exatamente por isso que funciona

Seu próximo passo hoje, no legado que está aberto aí: abre uma sessão em plan mode, pede o mapa de UM fluxo só, confere o que ele te disse abrindo os arquivos citados, e sai dessa sessão com um CLAUDE.md commitado na raiz

Amanhã você começa com contexto, não com arqueologia

até o próximo post!