Explore antes de editar

Field Note

Quinta-feira, 16h. Alguém pede ao Claude Code para "adicionar desconto por cupom no checkout". Em dois minutos aparece um campo novo no formulário, uma função de cálculo e um teste passando. Bonito. Só que o projeto já tinha um módulo de promoções, com regra de acúmulo, validade e limite por cliente. O cupom novo ignora tudo isso. Agora existem dois jeitos de dar desconto, e o segundo vai sobreviver mais do que deveria, porque já tem teste e "funciona".

Conceito

Explorar antes de editar é separar duas perguntas que costumam vir grudadas: "como isso funciona hoje?" e "o que eu mudo?". Quando a segunda vem antes da primeira, o agente monta uma hipótese cedo e passa o resto da sessão defendendo essa hipótese. Cada edição puxa a próxima, e desfazer começa a parecer mais caro do que seguir.

A doc oficial recomenda um fluxo em quatro fases: explorar, planejar, implementar, fazer commit. Esta lição é a primeira fase. A próxima é o plano.

Como explorar sem editar. Plan mode é o lugar natural. Nele o Claude lê arquivos, roda comandos de shell para investigar e escreve um plano, mas não edita o seu código. Você entra apertando Shift+Tab até a barra de status mostrar ⏸ plan mode on, ou já abre a sessão assim:

claude --permission-mode plan

O que pedir. A doc de workflows comuns sugere ir do amplo para o específico:

1. Visão geral: "me dê uma visão geral deste código".
2. Localizar: "encontre os arquivos que tratam de autenticação".
3. Relacionar: "como esses arquivos funcionam juntos?".
4. Rastrear: "trace o processo de login do front-end até o banco".

O passo 4 é o que mais rende. Rastrear um fluxo ponta a ponta obriga o agente a seguir chamadas reais, não a supor a arquitetura pelo nome das pastas.

Fato ou inferência. Um mapa de exploração mistura duas coisas: o que ele leu e o que ele deduziu. "A função applyDiscount é chamada em checkout.ts, linha 88" é fato verificável. "Provavelmente o cálculo de frete acontece depois do desconto" é inferência. As duas são úteis, mas só uma pode virar base de decisão sem conferência. Peça explicitamente que ele marque cada afirmação com arquivo e linha, e separe o que confirmou do que supôs.

Subagentes para não lotar o contexto. Explorar lê muito arquivo, e cada arquivo lido ocupa a janela. A doc indica delegar: "use um subagente para investigar como o sistema de autenticação trata o refresh de token". O subagente trabalha numa janela própria e devolve só o resumo. Existe um subagente nativo chamado Explore, descrito como rápido e somente leitura, otimizado para buscar e analisar código. Ao acioná-lo, o Claude escolhe um nível de profundidade: quick, medium ou very thorough. Durante o plan mode, há também um subagente nativo Plan, igualmente somente leitura, usado para juntar contexto antes de apresentar o plano.

Perguntas paralelas. Se no meio da exploração surgir uma dúvida rápida sobre algo que ele já leu, /btw responde sem entrar no histórico da conversa. Detalhe: /btw não usa ferramentas, só responde com o que já está no contexto.

Navegação precisa. Em linguagem tipada, a doc recomenda instalar um plugin de code intelligence. Ele dá ao Claude "ir para definição" e "encontrar referências" de verdade, em vez de busca por texto.

Quando usar

• Código que você não conhece ou não toca há meses.
• Mudança que pode já ter um equivalente no projeto (desconto, autenticação, permissão, notificação).
• Bug cuja causa você não sabe onde está.
• Antes de qualquer mudança que atravessa camadas (front, API, banco).
• Quando outra pessoa vai revisar e precisa entender o raciocínio.

Quando não usar

• Mudança que cabe numa frase e num arquivo: renomear variável, corrigir texto, adicionar log.
• Código que você escreveu ontem e conhece de cor.
• Quando a exploração vira desculpa para não decidir. Mapa bom tem fim.

Faça agora

A prática é produzir um Mapa da área afetada de uma funcionalidade real, sem permitir edição.

1. Escolha uma funcionalidade do seu projeto que você vai precisar mexer em breve, ou uma que você não entende bem.
2. Abra a sessão em plan mode:

cd caminho/do/projeto
claude --permission-mode plan

3. Mande este pedido:

Quero entender a funcionalidade X antes de mudar qualquer coisa. Use um subagente para explorar. Trace o fluxo ponta a ponta, da entrada até onde os dados são gravados. Liste: arquivos envolvidos, funções principais com arquivo e linha, dependências externas, testes que cobrem o fluxo e pontos onde algo parecido já existe no projeto. Separe em duas listas o que você confirmou lendo o código e o que é inferência. Termine com as dúvidas que só uma pessoa do time saberia responder.

4. Escolha três afirmações marcadas como fato e confira você mesmo, abrindo o arquivo na linha citada.
5. Escolha uma inferência e peça que ele confirme ou derrube: "confirme a inferência 2 lendo o código, sem supor".
6. Rode /context e veja quanto a exploração ocupou. Compare com o que teria ocupado sem subagente, se tiver curiosidade de repetir.
7. Salve o mapa. Ele é a entrada da próxima lição.

Armadilhas

• Exploração infinita. A doc chama esse padrão de infinite exploration: pedir para "investigar" sem escopo e ver centenas de arquivos lidos. Delimite a área ou use subagente.
• Aceitar mapa sem linha. Afirmação sem arquivo e linha é opinião. Exija a referência.
• Tratar inferência como fato. "Provavelmente" no mapa vira "com certeza" no plano se ninguém marcar a diferença.
• Sair do plan mode antes da hora. A tentação de "já que ele achou, deixa corrigir" é exatamente o que esta etapa evita.
• Esquecer o que já existe. A pergunta "existe algo parecido no projeto?" evita o cupom paralelo da Field Note.
• Confiar que plan mode é blindado em qualquer configuração. A doc indica que, em sessões de terminal iniciadas com bypass permissions disponível, os bloqueios do plan mode não são aplicados. Se você usa esse modo, saiba disso.

Material para levar

Mapa da área afetada:

Funcionalidade:
Data:
Ponto de entrada:

Fluxo ponta a ponta (passo, arquivo:linha):
1.
2.
3.

Arquivos envolvidos:
Dependências externas (banco, API, fila, serviço):
Testes que cobrem o fluxo:
Algo parecido que já existe no projeto:

Confirmado lendo o código:
- 
Inferência (precisa de conferência):
- 

Dúvidas para o time:
- 

Conferi pessoalmente: 3 fatos (ok / divergiu) e 1 inferência (confirmada / derrubada)

Sequência de perguntas que funciona:

1. Visão geral do código
2. Onde mora a funcionalidade X
3. Como esses arquivos conversam
4. Trace o fluxo do início ao fim
5. O que é fato e o que é suposição
6. O que já existe de parecido