A documentação oficial abre esse assunto com uma frase direta:
Deixar o Claude ir direto para o código pode produzir código que resolve o problema errado.
Sem erro nenhum no caminho. É por isso que dói: não há o que consertar, há o que refazer.
As quatro fases
1. Explorar
Entre no modo de plano: aperte Shift+Tab até a barra de status mostrar
⏸ plan mode on, ou abra a sessão já assim:
claude --permission-mode plan
Nesse modo ele lê arquivos e responde perguntas sem alterar nada.
Exemplo de pedido:
leia /src/auth e entenda como tratamos sessão e login.
veja também como as variáveis de ambiente guardam os segredos.
2. Planejar
Peça o plano detalhado antes de qualquer edição:
quero adicionar login com Google. que arquivos mudam?
como fica o fluxo de sessão? faça um plano.
Ctrl+G abre o plano no seu editor de texto para você corrigir antes de ele seguir.
Esse é o momento barato de discordar.
3. Implementar
Saia do modo de plano aprovando o plano ou apertando Shift+Tab de novo. Aí sim:
implemente o fluxo de OAuth do seu plano. escreva testes para o
callback, rode a suíte e corrija o que falhar.
4. Commitar
faça o commit com uma mensagem descritiva e abra um PR
O passo que quase ninguém conta: quando pular o plano
A mesma página é explícita — planejar tem custo, e nem toda mudança compensa:
| Pule o plano | Planeje |
|---|---|
| Corrigir erro de digitação | A mudança mexe em vários arquivos |
| Acrescentar uma linha de log | Você não conhece o código que vai mudar |
| Renomear uma variável | Você está incerto sobre a abordagem |
E a régua cabe numa frase:
Se você consegue descrever o diff em uma frase, pule o plano.
Os erros que a doc lista, com o conserto
A sessão pia de cozinha. Você começa com uma tarefa, pergunta outra coisa sem
relação, volta para a primeira. O contexto fica cheio de informação irrelevante.
→ Conserto: /clear entre tarefas sem relação.
Corrigir sem parar. Ele erra, você corrige, ainda erra, você corrige de novo.
O contexto fica poluído de tentativas que falharam.
→ Conserto: depois de duas correções falhas, /clear e escreva um pedido
melhor incorporando o que você aprendeu. Uma sessão limpa com pedido bom quase
sempre ganha de uma sessão longa com correção acumulada.
O CLAUDE.md inchado. Se ele está longo demais, metade é ignorada porque a
regra importante se perde no meio do resto.
→ Conserto: para cada linha, pergunte "tirar isso faria ele errar?". Se não, corte.
O motivo por trás de tudo
Está escrito lá, na linha do /clear:
Sessões longas com contexto irrelevante podem reduzir o desempenho.
Quase toda boa prática dessa página desce daí.
Comandos que valem decorar
| Comando | Para quê |
|---|---|
Shift+Tab | Alterna o modo de plano |
Ctrl+G | Abre o plano no seu editor |
/clear | Zera o contexto entre tarefas |
/compact <instrução> | Resume mantendo o que você mandar manter |
Esc | Interrompe no meio, preservando o contexto |
Esc Esc ou /rewind | Volta a conversa e o código a um ponto anterior |
/btw | Pergunta cuja resposta não entra no histórico |
Documentação oficial: https://code.claude.com/docs/en/best-practices