Como usar o Claude Code para entender um código que você nunca viu antes

Fala aí, beleza? Tu clona o repositório da empresa nova, abre a pasta e aparecem centenas de diretórios que não dizem absolutamente nada 😅

Tem packages/, tem legacy/, tem três pastas com nome parecido e um README que parou de ser atualizado em alguma era geológica anterior

A vontade é sair abrindo arquivo aleatório até algo fazer sentido

Aqui a proposta é outra: usar o Claude Code como guia de leitura do projeto, não como gerador de código

No primeiro dia o valor dele não está em escrever linha nova, está em responder pergunta

É como contratar um dev sênior que já leu o projeto inteiro, sentar do lado e ficar perguntando até o mapa fechar na tua cabeça

E isso não é gambiarra minha, a documentação oficial recomenda exatamente esse fluxo pra quem chega numa base de código nova: navegar até a raiz do projeto, iniciar o Claude Code, pedir uma visão geral de alto nível e só depois aprofundar em componentes específicos

Bora montar o roteiro?

O que você precisa antes de começar

O mínimo é bem curto:

• o projeto clonado na tua máquina
• o terminal aberto na raiz do repositório (ou no subdiretório do pacote, se for monorepo)
• o Claude Code rodando ali

Formação Recomendada

Formação Claude Code

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

• 110 aulas
• 4 projetos
• 9h 2min

Conhecer formação

Se tu nunca abriu a ferramenta, vale dar uma passada nos primeiros passos com o Claude antes de seguir, o roteiro aqui já assume que a sessão sobe

O Claude Code roda em terminal, em extensões de IDE, em aplicativo desktop e na web

O roteiro deste post vale pra qualquer uma dessas superfícies, porque o que muda é a janela, não o jeito de perguntar

Por que o diretório de onde você inicia importa:

Essa parte é a que mais pega gente desprevenida

O Claude Code carrega os arquivos CLAUDE.md do diretório de trabalho e de TODOS os diretórios pais no início da sessão

Os de subdiretório não entram junto, eles carregam sob demanda, quando o Claude lê um arquivo daquele diretório com a ferramenta Read

Traduzindo: o lugar de onde tu dispara a sessão define quais instruções do projeto o agente já conhece antes da tua primeira pergunta

Abrir no lugar errado é começar a conversa com o contexto capado sem perceber

Passo a passo: como mapear um código desconhecido com o Claude Code

1. Inicie na raiz certa: vá até a raiz do repositório (ou até a pasta do pacote que tu vai mexer, em monorepo) e só então suba o Claude Code

cd ~/projetos/o-tal-repo-que-eu-nao-entendo
# agora sim, inicie o Claude Code a partir daqui

O erro comum deste passo: subir a sessão de qualquer lugar do disco e ficar bravo porque o agente não sabe as convenções do time

2. Entre em plan mode ANTES de perguntar qualquer coisa: o modo de planejamento faz o Claude pesquisar e propor mudanças sem executar nada

Existem duas formas documentadas de entrar: pressionar Shift+Tab ou prefixar um único prompt com /plan

Apertar Shift+Tab de novo sai do modo sem aprovar o plano, então dá pra entrar e sair à vontade

Ele lê arquivo, ele monta plano, ele não edita nada até você aprovar

É a fase de leitura pura, exatamente o que tu quer no primeiro contato

O erro comum deste passo: já chegar pedindo alteração e sujar o repositório antes de entender o que aquilo faz

3. Peça a visão geral de alto nível e deixe a busca agêntica trabalhar: o Claude Code mapeia estrutura e dependências do projeto por busca agêntica, sem exigir que você selecione manualmente os arquivos de contexto

Me dê uma visão geral de alto nível deste projeto:
o que ele faz, como está organizado e quais são as
dependências principais entre as partes

Repare que não tem arquivo nenhum apontado no prompt

É de propósito 🙂

O erro comum deste passo: sair colando arquivo aleatório com @ antes de saber o que importa

O @ serve pra referenciar arquivo no prompt, e é ótimo, mas ele só ajuda depois que você já sabe qual arquivo tem peso na história

4. Aprofunde por componente, uma pergunta por vez: com o mapa grosso na mão, desce um nível

Explique a arquitetura da camada de autenticação

Quais são os modelos de dados principais e como eles se relacionam?

Como o recurso de exportação de relatório é tratado, do request até a resposta?

Arquitetura, modelos de dados, como um recurso específico é tratado: são três perguntas diferentes e vale fazer separadas

O erro comum deste passo: mandar as três de uma vez e receber um resumão genérico que não serve pra nada

5. Delegue investigação pesada a subagentes: quando a pergunta exige varrer meio projeto, peça explicitamente

Use subagentes para investigar como o sistema de permissões
é aplicado em cada rota

Subagentes exploram em contexto separado e devolvem só o resumo

Isso mantém a conversa principal limpa, porque busca, log e leitura de arquivo não ficam entulhando o histórico da tua sessão

É o mesmo motivo de você não copiar o log inteiro do build no chat, o resumo basta

6. Vigie o contexto com /context: o comando mostra uma quebra ao vivo do que está ocupando a janela de contexto

Ele separa por categoria: prompt de sistema, ferramentas de sistema, ferramentas MCP, subagentes personalizados com a origem de cada um, arquivos de memória, skills e mensagens da conversa

Cada linha traz nome, tokens usados e tipo, então dá pra ver na hora quem é o gordo da sessão

Quando encher, /compact resume pra liberar espaço e /clear reinicia a conversa num contexto vazio mantendo a memória do projeto

Detalhe importante: a conversa antiga não evapora, ela permanece em disco e pode ser retomada pelo ID de sessão

O erro comum deste passo: insistir numa conversa quilométrica e culpar o modelo pela queda de qualidade, quando o problema é a janela lotada

7. Tenha o /rewind como rede de segurança: ele restaura código, conversa ou ambos pra um ponto anterior

Dá pra voltar código e conversa pra um checkpoint, ou retomar parte da conversa a partir de uma mensagem selecionada

Saber que existe volta atrás muda MUITO a coragem de explorar

8. Rode /init no final pra congelar o que você aprendeu: o comando analisa o codebase e cria um CLAUDE.md inicial com comandos de build, instruções de teste e convenções que ele descobre

O arquivo de projeto pode ficar em ./CLAUDE.md ou em ./.claude/CLAUDE.md, e é compartilhado com o time via controle de versão

Ali moram comandos de build e teste, padrões de código, decisões arquiteturais, convenções de nomenclatura e fluxos comuns

Ou seja: o teu primeiro dia vira documentação viva pro próximo que chegar

O erro comum deste passo: rodar /init logo de cara, antes de explorar, ou travar com medo de sobrescrever um CLAUDE.md que já existe

Se já existir, o /init sugere melhorias em vez de sobrescrever, então relaxa 😀

9. Só então decida como aprovar: quando você finalmente for encostar em código, o Claude apresenta o plano e pergunta como prosseguir

As opções incluem aprovar e iniciar em modo automático, ou aprovar revisando cada edição individualmente

No primeiro dia num projeto que tu mal conhece, revisar edição por edição é o caminho óbvio

Resumo dos comandos do roteiro:

Variações do roteiro conforme o projeto

O roteiro base é sempre o mesmo, o que muda é onde tu começa e quanto tu deixa entrar na janela

Monorepo: comece de dentro do pacote

Em monorepo, iniciar o Claude a partir de um subdiretório carrega o CLAUDE.md local junto com o da raiz, sem trazer instruções dos outros pacotes

Iniciar de packages/api/ carrega packages/api/CLAUDE.md e o CLAUDE.md da raiz, e pronto

As regras do pacote de frontend ficam de fora, e isso é bom, elas só iam competir por espaço

Outra coisa massa: qualquer subdiretório pode definir skills com escopo da própria stack, carregadas sob demanda quando o Claude julga relevante

O que muda no roteiro: o passo 1 vira "raiz do pacote", não "raiz do repo"

Base grande: a configuração padrão trabalha contra você

Em bases grandes, configurações padrão pensadas para projetos pequenos podem encher a janela de contexto com leituras e instruções que não têm nada a ver com a tua tarefa

Aqui o passo 5 (subagentes) e o passo 6 (/context) deixam de ser opcionais

É mapear uma área por vez, delegar a varredura pesada pro contexto separado e limpar a conversa entre um assunto e outro

O que muda no roteiro: tu roda /context MUITO mais cedo, sem esperar a coisa engasgar

A primeira tarefa real depois do mapa

Mapa fechado, chega a primeira demanda de verdade

A recomendação é separar pesquisa e planejamento da implementação, pra não sair resolvendo o problema errado com muita eficiência (que é o pior tipo de produtividade, né? haha)

A própria documentação cita um prompt nesse formato:

Quero adicionar Google OAuth. Que arquivos precisam mudar?
Qual é o fluxo de sessão? Crie um plano.

Repare no desenho da pergunta: primeiro os arquivos afetados, depois o fluxo, e só no fim o plano

Quando a implementação sair, o mesmo agente serve pra passar o pente fino antes de você abrir o PR, que num projeto que tu conheceu ontem faz ainda mais diferença

O que muda no roteiro: aqui a sessão pode sair do plan mode, mas de preferência aprovando edição por edição

Conclusão

No primeiro dia, o agente vale pelas respostas, não pelo código

O roteiro inteiro cabe numa frase: abrir na raiz certa, entrar em plan mode, pedir a visão geral, aprofundar por componente, delegar o pesado a subagentes, vigiar a janela e fechar com /init

Se você quer testar isso hoje, escolhe o repositório que tu menos entende (todo mundo tem um)

Roda o roteiro em plan mode, sem tocar em uma linha sequer

E termina a sessão com um CLAUDE.md commitado, porque aí o teu primeiro dia vira atalho pro próximo dev que chegar

Usar o Claude Code pra entender código que ninguém te explicou é, de longe, o uso mais subestimado da ferramenta…

até o próximo post! =)