Plan Mode — pensar antes de mexer

Aperta Shift+Tab no Claude Code e você entra em Plan Mode. O modelo explora o código, entende o que você quer, e te entrega um plano escrito — sem editar nada. Você aprova, edita ou descarta.

Por que vale

Sem plan, o Claude já começa editando com base na primeira interpretação do teu prompt. Se ele entendeu 80%, você ganha 80% do que queria e tem que corrigir os 20%. Em tarefa grande, esse 20% custa caro.

Com plan, você vê a interpretação antes de qualquer mudança. Erro de leitura? Corrige em 2 linhas. Arquitetura ruim? Ajusta. Falta considerar um edge case? Adiciona.

Explore → Plan → Implement → Verify

O fluxo que funciona:

1. Explore: em Plan Mode, o Claude lê os arquivos relevantes. Você pode pedir “olha também o módulo X”.
2. Plan: ele escreve passos concretos. Você lê como se fosse um PR description.
3. Implement: sai do Plan Mode, ele executa. Já sabe o que fazer, erra menos.
4. Verify: testa, lê o diff, roda o lint. Plan bom = verify rápido.

Quando vale o plan

• Toca 3+ arquivos ou módulos diferentes
• Envolve decisão de arquitetura (onde colocar, como nomear, qual abstração)
• Refactor não-trivial
• Feature nova que precisa encaixar no que existe
• Debug onde você não sabe nem por onde começar

Quando pular o plan

• Fix de 1 linha que você já sabe o que é
• “Renomeia essa variável”, “adiciona esse log”
• Tarefa exploratória de pesquisa (usa subagent, não plan)
• Protótipo descartável — plano é overhead aqui

Regra: se o plano vai ser maior que a implementação, pula o plan.

Exemplo prático

Prompt: “adiciona rate limit no endpoint de login”

Sem plan, o Claude pode:

• Adicionar um middleware custom
• Instalar express-rate-limit
• Editar só o handler do login
• Colocar a config hardcoded ou num env

Quatro caminhos, todos defensáveis, provavelmente não é o que o teu projeto já usa.

Com plan, ele explora, acha que o projeto já tem @upstash/ratelimit configurado em src/lib/rate-limit.ts, e propõe:

1. Importar `loginLimiter` de src/lib/rate-limit.ts
2. Adicionar no handler src/routes/auth/login.ts antes do parse do body
3. Retornar 429 com mesma estrutura de erro que os outros limites
4. Adicionar teste em login.test.ts cobrindo o 429

Você lê, aprova, ele executa. Sem retrabalho.

Gotcha

Plan Mode pode te dar um plano bonitinho mas errado se você der pouco contexto. Antes de apertar Shift+Tab, dá um prompt decente: o que você quer, onde, restrições. Plano nasce do prompt — entrada ruim, plano ruim.

Dica prática

Se o plano vier com “opção A ou opção B, qual você prefere?”, ótimo. Significa que ele identificou a ambiguidade antes de codar. Escolhe e segue. Sem plan, essa pergunta viraria código errado.