Planeje antes de executar

Field Note

Segunda-feira, 9h30. Uma pessoa pede ao Claude Code para trocar o provedor de envio de e-mail. O plano chega rápido e parece completo: doze arquivos, uma camada nova de abstração, migração dos templates, testes. Ela aprova sem ler direito, porque o plano "parecia profissional". Duas horas depois, metade dos templates está no formato novo, a outra metade quebrada, e a camada de abstração atende a três provedores que ninguém pretende usar. O plano estava lá. Ninguém discutiu com ele.

Conceito

Planejar é transformar o mapa da lição anterior numa sequência de mudanças que você aprova antes de qualquer arquivo ser tocado. O valor não está no documento. Está na conversa sobre o documento: as escolhas que você recusa, a ordem que você muda, o risco que você enxerga e ele não.

Plan mode, na prática. Conferido na doc oficial em outubro de 2026:

• Entrar: Shift+Tab até a barra de status mostrar ⏸ plan mode on. Ou /plan no começo de um prompt, com descrição opcional (/plan corrigir o bug de autenticação). Ou abrir já no modo com claude --permission-mode plan.
• O que ele faz: lê arquivos, roda comandos de shell para investigar e escreve um plano, sem editar o seu código. Se o auto mode estiver disponível para você, um classificador revisa os comandos de shell durante o planejamento em vez de te perguntar.
• Editar o plano: Ctrl+G abre o plano proposto no seu editor de texto para você mexer direto antes de ele seguir.
• Sair sem aprovar: Shift+Tab de novo.

Aprovação. Quando o plano fica pronto, ele pergunta como seguir. As opções que a doc lista:

1. Yes, and use auto mode: aprova e passa a executar em auto mode. Se o auto mode não estiver disponível, a opção aparece como Yes, auto-accept edits.
2. Yes, manually approve edits: aprova e você revisa cada edição.
3. No, keep planning: continua em plan mode e você diz o que mudar.

Aprovar tira a sessão do plan mode e ela começa a editar. Para planejar de novo, volte com Shift+Tab ou use /plan no próximo prompt.

O que um plano bom tem. Não é tamanho. É poder ser conferido:

• Arquivos que vão mudar, e por quê cada um.
• Ordem de execução, com o motivo da ordem.
• Riscos e o que pode quebrar fora da área.
• Como cada etapa vai ser verificada (qual teste, qual comando).
• Pontos de parada: onde você quer olhar antes de seguir.
• O que fica de fora.

Peça alternativas. Um plano só é uma resposta. Dois planos são uma decisão. Peça duas abordagens com trade-offs antes de escolher. Isso expõe as suposições que um plano único esconde.

Quando pular. A doc é clara: plan mode tem custo. Para mudança pequena e de escopo claro, peça direto. A regra é a mesma que vimos no Território 1: se você consegue descrever o diff em uma frase, pule o plano.

Para mudanças grandes, a doc sugere uma variação: deixar o Claude te entrevistar e escrever um SPEC.md, depois abrir uma sessão nova para executar. A sessão nova começa com o contexto limpo, focado na implementação, e o spec fica escrito para consulta.

Plan mode como padrão. Se o seu projeto pede isso sempre, dá para configurar defaultMode como plan no .claude/settings.json. Na extensão do VS Code, a configuração é outra (claudeCode.initialPermissionMode).

Quando usar

• Mudança em vários arquivos.
• Você está incerto sobre a abordagem.
• Código que você não conhece bem.
• Decisão de arquitetura ou de dependência.
• Qualquer coisa difícil de reverter: migração de dados, troca de provedor, mudança de contrato de API.

Quando não usar

• Diff que cabe numa frase.
• Tarefa exploratória em que você quer ver o que ele faz antes de decidir.
• Quando o plano vira fim em si. Plano de quarenta passos para uma mudança de três arquivos só antecipa a burocracia.

Faça agora

A prática é sair com um Plano aprovado, depois de rejeitar pelo menos uma escolha.

1. Use o mapa da lição anterior, ou escolha uma mudança que envolva dois ou mais arquivos. Trabalhe numa branch separada.
2. Entre em plan mode e peça:

/plan Com base no mapa abaixo, proponha duas abordagens para implementar X, com trade-offs de cada uma. Depois recomende uma. Para a recomendada, liste: arquivos que mudam e por quê, ordem de execução, riscos, como cada etapa será verificada e o que fica fora do escopo. Defina pontos de parada onde eu reviso antes de continuar.

[cole aqui o resumo do seu mapa]

3. Leia o plano inteiro. Ache pelo menos uma escolha para recusar: uma abstração que não precisa existir, uma ordem que deixa o sistema quebrado no meio, um arquivo que não deveria mudar, um teste que não prova nada.
4. Escolha No, keep planning e explique o que mudar. Exemplo: "remova a camada de abstração genérica, só vamos ter um provedor".
5. Repita até o plano ficar do tamanho do problema. Se quiser ajustar texto direto, use Ctrl+G.
6. Antes de aprovar, confira com o checklist abaixo.
7. Aprove com Yes, manually approve edits desta vez. Na próxima lição você vai executar em passos pequenos.
8. Salve o plano final e a lista do que você recusou.

Armadilhas

• Aprovar porque parece profissional. Formatação bonita não é revisão. Leia cada arquivo da lista.
• Plano sem verificação. Se nenhuma etapa diz como vai ser conferida, o plano termina em "parece pronto".
• Ordem que quebra no meio. Mudar o consumidor antes do produtor deixa o sistema inválido entre etapas. Peça uma ordem em que cada etapa termine funcionando.
• Abstração para o futuro. "Suporte a vários provedores" quando só existe um. Recuse.
• Esquecer que aprovar muda o modo. Depois de aprovar, a sessão sai do plan mode. Se escolheu auto mode, ele segue editando sem perguntar.
• Planejar na mesma sessão gigante. Se a exploração lotou o contexto, considere salvar o plano num arquivo e executar numa sessão nova.

Material para levar

Checklist de plano aprovável:

[ ] Duas abordagens comparadas, com trade-offs
[ ] Cada arquivo listado tem um motivo
[ ] Ordem em que cada etapa termina com o sistema funcionando
[ ] Riscos fora da área afetada
[ ] Verificação definida para cada etapa (teste, comando, saída)
[ ] Pontos de parada para minha revisão
[ ] Fora do escopo escrito
[ ] Pelo menos uma escolha recusada e o motivo registrado
[ ] Tamanho do plano proporcional ao problema

Atalhos do plan mode:

Shift+Tab              entra e sai do plan mode (ciclo de modos)
/plan descrição        entra em plan mode já com a tarefa
claude --permission-mode plan   abre a sessão no modo
Ctrl+G                 abre o plano no seu editor
No, keep planning      continua planejando com o seu ajuste