Como usar o Claude Code para entender um projeto legado que você acabou de herdar?

Fala aí, beleza? Aquele frio na barriga de clonar um repositório que não é seu, abrir a pasta e não achar um README que preste, acho que todo dev já sentiu

O time original não está mais lá, a documentação virou wiki morto e o primeiro card da sprint já pede alteração bem no meio daquilo

A proposta aqui é usar o Claude Code no modo mais chato e mais útil que existe: leitura e diagnóstico

Nada de sair gerando código novo em cima de um sistema que você ainda não entende

Primeiro o mapa, depois a picareta =)

Se a sua dúvida ainda é outra, mais de fundo, tipo se vale a pena num projeto legado, esse papo é de outro post

Aqui a gente já assume que você herdou o troço e precisa se orientar antes de quebrar alguma coisa

O que você precisa antes de começar

A lista é curtinha, não precisa de PC da Nasa nem de setup mirabolante:

• o repositório clonado e o terminal aberto na raiz do projeto
• o Claude Code instalado e rodando a partir dessa raiz, porque é de lá que o arquivo CLAUDE.md é lido automaticamente no início da sessão
• paciência pra ler o que ele responde, e não só aceitar

Uma dica boba que economiza tempo: digite / no prompt vazio

Ele lista todos os comandos disponíveis na SUA instalação, incluindo os personalizados, os que vieram de plugins e os que chegaram via MCP

Isso importa porque cada máquina tem um conjunto diferente, e é melhor ver a lista real do que decorar comando de tutorial

Pré-inscrição Formação Claude Code

Domine o Claude Code do básico ao avançado

Você vai aprender a criar sistemas completos com Claude Code, sem precisar ser programador. Inscreva-se para ter acesso a um desconto de lançamento e bônus especiais!

Quero minha vaga

Passo a passo: como mapear um projeto legado com o Claude Code

A ordem aqui é sagrada: leitura primeiro, escrita depois

A própria documentação recomenda separar pesquisa de escrita em problemas complexos, e projeto herdado é o exemplo perfeito de problema complexo

1. Entre no modo de planejamento antes de qualquer coisa

O plan mode é o modo em que o Claude pesquisa e propõe mudanças sem executá-las: ele lê arquivos e roda comandos de exploração, mas não edita o código-fonte

Pra entrar, aperte Shift+Tab ou prefixe um único prompt com /plan

/plan me explique a estrutura geral deste projeto: pastas principais e o que cada uma parece fazer

O Shift+Tab cicla entre os modos nesta ordem: default, acceptEdits e plan

Dentro do plan mode, comandos que estão fora do conjunto embutido de comandos somente leitura pedem aprovação, então você continua no controle

O erro comum deste passo: apertar Shift+Tab de novo achando que está confirmando o plano

Não está! Apertar de novo SAI do modo de planejamento sem aprovar plano nenhum

2. Rode /init pra ter um primeiro retrato do projeto

O /init analisa o projeto e gera um CLAUDE.md inicial

Depois, o /memory serve pra refinar esse arquivo

/init

Pensa nele como o caderno de anotações do projeto: é o que vai ser carregado como contexto no começo de cada sessão, sem você ter que reexplicar tudo de novo toda santa vez

O erro comum deste passo: tratar o arquivo gerado como verdade absoluta

Ele é material bruto pra você corrigir, não laudo

Se o Claude entendeu errado qual é a pasta do domínio, isso vai te assombrar em toda sessão futura, então conserte cedo com o /memory

3. Delegue a varredura pesada ao subagente Explore

O Explore é um subagente embutido do Claude Code, somente leitura, otimizado pra busca e análise de bases de código

Ao acionar, o Claude define um nível de profundidade, e vale saber o que cada um significa pra entender a resposta que volta:

O erro comum deste passo: achar que a profundidade é um botão na sua mão

Quem define o nível ao acionar é o Claude

O que está com você é a pergunta: se quer o mapa inteiro, peça o mapa inteiro, se a dúvida é pontual, faça a pergunta pontual e pronto

4. Faça as perguntas de mapeamento em paralelo

Vários subagentes podem rodar simultaneamente, e cada um roda numa conversa própria

Isso é MUITO importante: as chamadas de ferramenta e os resultados intermediários ficam dentro do subagente, e só a mensagem final volta pra conversa principal

Ou seja, você recebe a conclusão, não trinta arquivos despejados no seu contexto

A recomendação oficial pra bases grandes é exatamente essa: delegar a exploração a subagentes pra manter a conversa principal limpa

Na prática, em vez de uma pergunta gigante, dispare frentes separadas: ponto de entrada, camada de dados, autenticação, jobs em segundo plano

5. Desça ao detalhe com menções @

Depois do mapa vem a lupa

As menções com @ dão contexto sobre arquivos ou pastas específicos: você digita @ seguido do nome, o Claude lê aquele conteúdo e responde perguntas sobre ele

no @authService, quem chama o método de refresh do token? e o que acontece se ele falhar?

A menção aceita correspondência aproximada (fuzzy), então nome parcial funciona, tipo @auth casando com auth.js ou AuthService.ts

Dá pra referenciar vários arquivos na mesma mensagem, o que é ótimo pra pedir comparação entre dois módulos que parecem fazer a mesma coisa

Não lembra o caminho? Digite @ e aperte Tab que o autocompletar mostra os arquivos ao alcance

E quando você quer falar de um trecho, não do arquivo inteiro, use Option+K no Mac ou Alt+K no Windows e Linux: isso insere uma menção com o caminho do arquivo e o intervalo de linhas, no formato @app.ts#5-10

6. Vigie o contexto, não deixe estourar no meio do mapeamento

Mapear projeto legado é conversa longa por natureza

O /context mostra o uso atual de contexto numa grade colorida, com sugestões de otimização pra ferramentas pesadas, excesso de memória e avisos de capacidade

Quando apertar, o /compact libera espaço resumindo a conversa até ali, e ele aceita instruções de foco pra esse resumo

/compact mantenha o mapa de módulos e o fluxo de autenticação, pode descartar o resto

O erro comum deste passo: compactar sem instrução de foco e perder justamente a parte do mapeamento que custou caro pra levantar

7. Feche o ciclo: revise o plano e só então libere a implementação

A abordagem em duas fases (pesquisar e planejar antes de codar) é a recomendada oficialmente, e produz resultado melhor do que partir direto pro código

Então leia o plano na conversa, discuta, corrija o que ficou torto, e aí sim deixa o Claude implementar

Se você quer ver como isso engata com o resto do trabalho, tem um post aqui sobre o fluxo completo até o deploy

E depois de tudo mapeado, rode o /init de novo: em projeto que já tem CLAUDE.md, ele revisa o arquivo atual e sugere melhorias a partir do que aprendeu explorando a base

Perguntas que valem a pena fazer ao herdar o código

O conjunto de recursos é sempre o mesmo, o que muda é a pergunta

Segue uma lista do que costuma destravar as primeiras semanas:

Onde começa o fluxo?

Pergunta clássica de projeto sem documentação: qual é o ponto de entrada da aplicação, quem sobe o servidor, quem registra as rotas

Aqui o Explore dá conta bem, e a resposta vira a primeira linha útil do seu CLAUDE.md

Quem chama quem neste caminho crítico?

Escolha UM fluxo que o negócio não pode perder (o checkout, o login, a geração do relatório) e peça a cadeia de chamadas de ponta a ponta

Use menção com intervalo de linhas quando quiser que ele parta de um trecho específico, em vez de adivinhar por onde começar

O que aqui parece morto?

Seja honesto com a expectativa: não existe botão mágico de dead code

O que dá pra fazer é pedir uma varredura de CANDIDATOS, do tipo funções exportadas sem nenhuma referência encontrada na base, e depois conferir na mão

Tome cuidado! Chamada por reflexão, por string dinâmica ou por rota configurada em arquivo externo não aparece numa busca textual, e apagar isso confiando 100% na IA é pedir pra virar plantão

Como são os dados e do que isso depende lá fora?

Modelo de dados, migrations, integrações externas e variáveis de ambiente

Essa é a parte que mais dói descobrir tarde, então descubra cedo

O que o histórico conta?

O Claude Code trabalha diretamente com git, incluindo preparar mudanças, escrever mensagens de commit, criar branches e abrir pull requests

Use isso a seu favor na fase de leitura: o histórico costuma explicar POR QUE aquele if esquisito existe, coisa que o código sozinho não conta

Subagente sob medida: quando criar o seu próprio explorador

Além do Explore, o Claude Code traz outros subagentes embutidos: um de uso geral, pra tarefas complexas de várias etapas, e um de planejamento, que pesquisa a base antes de apresentar a estratégia

Na maioria dos casos isso basta

Mas se no projeto herdado você repete sempre o mesmo tipo de investigação, aí compensa criar o seu

Subagentes personalizados são arquivos markdown na pasta .claude/agents/, com frontmatter YAML contendo name e description (mais os campos opcionais de modelo e de acesso a ferramentas), e o corpo do arquivo vira o system prompt do subagente

---
name: mapeador-de-fluxo
description: Reconstitui a cadeia de chamadas de um fluxo de ponta a ponta neste projeto
---

Você investiga um fluxo específico da base de código.
Comece pelo ponto de entrada, siga as chamadas em ordem e liste arquivo e função em cada salto.
Quando não encontrar a ligação, diga que não encontrou em vez de supor.

Se você conhece a ideia de um script utilitário no repositório, é bem parecido: fica versionado junto do código e todo mundo do time herda o mesmo comportamento

Pra gerenciar, use o /agents, que abre o gerenciador dos subagentes aos quais o Claude pode delegar tarefas e lista o que está rodando em segundo plano na sessão atual

Próximo passo: transforme o mapa em documentação viva

O resumo do post cabe em uma linha: leia e planeje antes de editar, e delegue a exploração pra manter a conversa principal limpa

O plan mode segura a mão do agente, o Explore faz o trabalho braçal, as menções @ dão a precisão e o /context com o /compact evitam que a sessão morra no meio

Agora o passo que separa quem fez um mapeamento bonito de quem realmente resolveu o problema: consolide tudo no CLAUDE.md

Ele é carregado no início de cada sessão, então o que estiver ali você não precisa reexplicar nunca mais

Ponto de entrada, fluxo crítico, o que é dependência externa, o que ninguém deve encostar sem falar com alguém… tudo isso é ouro pro próximo dev que herdar o projeto, mesmo que o próximo dev seja você daqui a seis meses haha

Bora mapear? 😀

até o próximo post!