Neste capítulo você vai aprender a usar o Claude Code como um guia de leitura para projetos que você não conhece ou que são grandes demais para ler de ponta a ponta. Ao final, você saberá fazer perguntas sobre arquitetura, localizar onde uma funcionalidade vive, seguir o caminho de uma requisição pelo código, mapear dependências entre módulos e produzir resumos e diagramas, tudo sem alterar um único arquivo. Vamos aproveitar a mecânica de sessão que você aprendeu no capítulo dois, em especial o modo de planejamento e a referência de arquivo com arroba.
Explorar sem risco
Antes da primeira pergunta, ative o modo de planejamento pressionando Shift Tab. Esse atalho alterna entre os modos disponíveis, então pode ser necessário pressioná-lo mais de uma vez: confirme no rodapé do terminal que o modo indicado é mesmo o de planejamento, porque outro modo do ciclo é o de aceitação automática de edições, que aprova alterações sem perguntar. Nesse modo, o Claude Code lê e busca livremente, mas não edita arquivos nem executa comandos que modifiquem o projeto. Para exploração pura isso é exatamente o que queremos. Mesmo assim, é um bom hábito começar a conversa dizendo algo como: “Quero apenas entender este projeto. Não altere nenhum arquivo.” A frase custa pouco e evita que uma pergunta ambígua vire uma proposta de mudança.
Como o Claude Code enxerga um projeto
O Claude Code não carrega o repositório inteiro na janela de contexto. Ele trabalha como um desenvolvedor experiente diante de um projeto desconhecido: lista arquivos por padrão de nome, faz buscas por texto, abre os arquivos que parecem relevantes e lê trechos deles. Cada resultado dessas operações entra na janela de contexto e ocupa espaço. É por isso que uma pergunta como “explique todo o projeto” funciona mal. Para respondê-la, a ferramenta precisa abrir dezenas de arquivos, o contexto se enche de conteúdo pouco útil, a resposta sai genérica e sobra menos espaço para as perguntas seguintes. Uma pergunta bem delimitada leva a poucas buscas, a uma resposta precisa e a um contexto que dura a sessão inteira. Pense na diferença entre pedir a um colega que leia o repositório completo antes de responder e perguntar diretamente onde fica o cálculo de frete.
Perguntas progressivas: do geral para o específico
A técnica central deste capítulo é perguntar em camadas. Imagine que você acabou de entrar em um time que mantém uma loja virtual escrita em Python com Django, com cerca de quatrocentos arquivos. Uma sequência produtiva seria a seguinte.
- Primeira pergunta: “Dê uma visão geral da organização de pastas deste projeto. Liste os módulos principais e a responsabilidade de cada um. Baseie-se na estrutura de diretórios e nos arquivos de configuração, sem ler o código-fonte inteiro.”
- Segunda pergunta: “Qual framework web, qual banco de dados e qual fila de mensagens este projeto usa? Onde a configuração é carregada?”
- Terceira pergunta, já dentro de um módulo: “Dentro da pasta de pedidos, quais são as classes principais e como elas se relacionam?”
Cada resposta orienta a próxima pergunta. Você decide para onde aprofundar, e a ferramenta gasta contexto apenas com o que interessa. Se uma resposta parecer superficial, peça para ela detalhar um ponto específico em vez de repetir a pergunta ampla.
- Ouça o áudio com a tela desligada
- Ganhe Certificado após a conclusão
- + de 5000 cursos para você explorar!
Baixar o aplicativo
Localizando onde uma funcionalidade é implementada
Quando o objetivo é encontrar um ponto exato do código, seja direto e peça referências verificáveis: “Onde é implementado o cálculo de frete? Cite o arquivo e o número da linha da função principal e de todos os lugares que a chamam.” Pedir arquivo e linha é essencial. A inteligência artificial pode descrever com convicção algo que não existe, e a citação permite que você abra o arquivo com a referência de arroba e confirme em segundos. Se a ferramenta não encontrar o que você procura, dê pistas concretas: um texto que aparece na tela do usuário, o nome de uma rota, uma mensagem de erro que você viu no log. Essas pistas se transformam em buscas por texto muito mais eficazes do que descrições vagas.
Rastreando um fluxo de ponta a ponta
Entender um sistema grande costuma significar seguir um caminho, não olhar uma foto. Peça isso explicitamente: “Rastreie o que acontece quando um cliente finaliza um pedido. Comece na rota HTTP, passe pelas validações, pela gravação no banco e pelo envio de e-mail. Liste cada etapa em ordem, com arquivo e linha.” O mesmo vale para dados: “Siga o campo de desconto de um pedido. Onde ele é lido da requisição, onde é alterado e onde é persistido?” Ao receber a lista, verifique por amostragem duas ou três etapas. Em fluxos longos, é comum a ferramenta inferir uma chamada por semelhança de nome. Conferir alguns pontos custa pouco e revela rapidamente se o rastreamento é confiável.
Dependências, resumos e diagramas
Para entender como os módulos se relacionam, pergunte: “Quais módulos o módulo de pagamentos importa, e quais módulos dependem dele? Existe alguma dependência circular?” A partir daí, peça uma representação visual em texto usando Mermaid, uma linguagem simples em que você descreve um diagrama com linhas de texto, por exemplo indicando que o módulo de pedidos aponta para pagamentos e para estoque, e o resultado é desenhado por plataformas como o GitHub, que renderiza Mermaid nativamente em arquivos Markdown, e por editores como o VS Code, desde que você instale uma extensão de visualização de Mermaid. Diga algo como: “Gere um diagrama Mermaid das dependências entre os módulos principais, mostrando apenas os dez mais importantes.” Limitar a quantidade evita um diagrama ilegível. Você também pode pedir um resumo em Markdown com a arquitetura, os pontos de entrada e os comandos de execução. Como ainda estamos explorando, peça que ele mostre o texto na tela e copie para a sua wiki ou anotações, em vez de criar arquivos no repositório.
Código morto e pontos de acoplamento
Código morto é código que existe no repositório mas nunca é executado: funções que nada chama, arquivos que ninguém importa, rotas desativadas. Peça: “Liste as funções da pasta de utilitários que não são referenciadas em nenhum outro lugar do projeto. Para cada uma, diga qual busca você fez para chegar a essa conclusão.” Pedir a busca realizada é uma forma de auditoria. E atenção: trate a lista como suspeita, nunca como veredito. Código pode ser chamado dinamicamente por nome em texto, por templates, por reflexão ou por outro sistema fora do repositório. A decisão de remover fica para o capítulo de refatoração.
Acoplamento é o grau em que um módulo depende de detalhes internos de outro. Para localizar os pontos críticos, pergunte: “Quais módulos acessam diretamente tabelas ou classes internas de outros módulos, em vez de usar uma interface pública?” Outra abordagem poderosa usa o histórico: “Analise o log do Git dos últimos seis meses e diga quais arquivos costumam mudar juntos no mesmo commit.” Como isso executa um comando do Git, o Claude Code pedirá sua aprovação. Leia o comando proposto antes de aceitar: leituras de histórico, como git log, não modificam nada; já comandos como git checkout, git clean ou git reset alteram o repositório e não deveriam aparecer em uma sessão de exploração.
Onboarding em um time
Todo esse repertório brilha na chegada de uma pessoa nova ao time. Em vez de esperar dias por uma explicação completa, ela pode seguir um roteiro de perguntas do primeiro dia: visão geral das pastas, principais fluxos, como rodar o projeto localmente, onde ficam os testes. Quem recebe o novato também ganha: pode pedir ao Claude Code um guia “por onde começar” e revisá-lo antes de entregar, ou criar exercícios do tipo “encontre onde o cupom de desconto é validado e explique a regra”. Vale reforçar que a ferramenta complementa, mas não substitui, as conversas com o time. Ela mostra o que o código faz; o motivo de cada decisão muitas vezes só existe na cabeça de quem a tomou.
Recapitulando
- Explore no modo de planejamento e diga explicitamente que não quer alterações.
- O Claude Code busca e lê trechos sob demanda; perguntas amplas enchem a janela de contexto e produzem respostas genéricas.
- Pergunte em camadas, do geral para o específico, deixando cada resposta guiar a próxima.
- Sempre peça arquivo e linha, e verifique por amostragem, especialmente em rastreamentos longos.
- Use diagramas Mermaid limitados a poucos elementos e resumos em Markdown para consolidar o que aprendeu.
- Listas de código morto e de acoplamento são hipóteses a confirmar, não sentenças.
- Em onboarding, a ferramenta acelera o entendimento do código, mas as conversas com o time continuam indispensáveis.
