Plan Mode: planejamento antes da execução no Claude Code

O problema mais caro do pair programming com IA

Eu aprendi da pior forma: pedi ao Claude Code para "melhorar a performance da página de busca". Ele leu dois arquivos, tirou suas conclusões, implementou três "otimizações" em lugares diferentes e escreveu testes — tudo em menos de dois minutos. Rodei os testes, passaram. Dei merge. Uma semana depois descobri que ele tinha refatorado a camada errada: o gargalo estava na query do banco, não no JavaScript do cliente.

O erro não foi dele, foi meu. Eu deixei o agente começar a implementar antes de entender. E esse é o problema mais caro do pair programming com IA: a velocidade de execução da máquina esconde a lentidão do entendimento. Você ganha uma hora de digitação e perde um dia depurando o que ela fez.

Plan mode é a resposta oficial do Claude Code para esse problema. É um modo em que o agente não pode editar nada — só lê, pesquisa e escreve um arquivo de plano para você aprovar. Parece trivial, mas muda a dinâmica inteira. Este artigo explica como funciona, quando ligar, quando desligar, e como escrever um plan file que não vira lorota.

Se você ainda não viu os sete pilares do Claude Code, comece pelo guia definitivo antes — plan mode faz muito mais sentido depois de entender o loop agêntico.

O que plan mode faz (e o que não faz)

No plan mode, as ferramentas de escrita são bloqueadas. O Claude pode:

• Ler arquivos (Read, Grep, Glob)
• Rodar comandos somente-leitura (git log, git diff, npm ls)
• Disparar subagents de pesquisa (Explore, general-purpose)
• Editar um único arquivo: o plano, num caminho pré-definido pelo harness

O que não pode:

• Editar qualquer outro arquivo do projeto
• Rodar comandos que modificam estado (git commit, npm install, curl -X POST)
• Criar branches, tags ou subir mudanças remotas

Esse bloqueio é estrutural, não comportamental. Não depende do modelo "lembrar" de não editar — o próprio harness rejeita a chamada. Significa que você pode pedir para o agente pesquisar livremente sem medo de ser surpreendido por uma edição apressada num arquivo de produção.

Como entrar e sair

A forma mais rápida de ligar é pressionar Shift+Tab duas vezes no prompt — o modo alterna e um badge plan mode aparece no status line. Para sair, o próprio agente usa a ferramenta ExitPlanMode, que é chamada quando ele termina o plano e pede sua aprovação explícita.

Você também pode iniciar já em plan mode passando --permission-mode plan no launch do CLI. Útil para rodadas em CI, ou quando você sabe de antemão que a tarefa é grande e quer forçar o fluxo desde o primeiro prompt.

As quatro fases do plan mode bem feito

O harness embute um workflow de quatro fases. Quem ignora e trata plan mode como "chat normal sem editar" desperdiça a feature. Quem segue tira valor real.

Fase 1 — Entendimento. O objetivo é só entender o problema e o código relevante. Aqui você deve usar subagents Explore para pesquisar múltiplas áreas em paralelo. O orquestrador recebe os resumos sem gastar contexto lendo arquivo por arquivo. Se você não conhece bem esse padrão, veja como dispará-los em Subagents no Claude Code: orquestrando tarefas em paralelo.

Fase 2 — Design. Agora o agente deve desenhar a abordagem. Aqui entra o subagent Plan, um arquiteto que recebe o contexto da fase 1 e devolve uma proposta de implementação com trade-offs. Você pode rodar dois ou três Plan em paralelo com perspectivas diferentes (simplicidade vs performance, minimal change vs clean architecture) e escolher.

Fase 3 — Revisão. O agente consolida o que aprendeu, valida contra o pedido original, e usa AskUserQuestion para resolver ambiguidades. É aqui que decisões duvidosas voltam pra você antes de virarem código errado.

Fase 4 — Plano final. O agente escreve o arquivo de plano com as seções essenciais: Context (por que essa mudança), Approach (a abordagem escolhida), Critical files (os arquivos a modificar), Verification (como testar). E só então chama ExitPlanMode para pedir aprovação.

Anatomia de um plan file que não vira lorota

Um bom plan file tem três características. Primeiro, ele explica o porquê antes do como — a seção Context deve deixar claro o problema, não só a solução. Quando você revisitar o plano um mês depois, o porquê é o que te orienta.

Segundo, ele lista arquivos críticos com caminhos exatos e, quando relevante, os números de linha. Plan file vago vira permissão para o agente "achar caminho" na execução. Plan file preciso vira execução previsível.

Terceiro, ele tem uma seção Verification — como testar a mudança end-to-end, quais comandos rodar, qual comportamento esperar. Sem isso, a saída do plan mode é só uma ideia; com ela, é uma tarefa executável.

Evite o erro oposto: planos que viram implementações. Se você escrever 300 linhas de pseudo-código no plan file, não é mais um plano, é código não-testado num arquivo markdown. Plan files devem ser decisões + paths + critérios de sucesso, não implementações disfarçadas.

Quando não ligar

Plan mode não é o modo padrão por um motivo: ele adiciona latência. Para tarefas pequenas, o overhead custa mais do que o benefício. Nos três casos abaixo eu deixo desligado:

• Edição pontual conhecida. "Renomeia essa variável", "acrescenta esse campo no tipo". Você já sabe o que fazer — plan mode só atrasa.
• Iteração rápida numa feature que você já entende. Você e o agente já fizeram 10 micro-ajustes; cada um leva 30 segundos. Ligar plan mode destrói o ritmo.
• Correção seguindo um erro de compilação. O compilador já disse qual é o problema. Planejar um plano para isso é teatro.

Ligue plan mode quando a tarefa tem pelo menos um destes: escopo incerto, múltiplos arquivos, domínios mistos, mudança arquitetural, ou custo alto de rollback. Se você hesita "será que isso vai mexer em mais coisas?", a resposta é plan mode.

Plan mode + memory + slash commands

Plan mode conversa com as outras peças do Claude Code. Plan files podem referenciar decisões guardadas no sistema de memória do Claude Code — se uma regra já foi acordada, o plano não precisa reabri-la. E faz sentido empacotar o ritual "ligar plan mode + pesquisar + escrever plano + chamar review" num slash command do seu time: aprenda a criar o seu em Criando Slash Commands customizados, que é o caminho mais direto para transformar esse workflow em hábito versionado. A disciplina de fundo (padrões, CLAUDE.md, ergonomia) tem que estar em ordem antes — o guia de slash commands e skills cobre o básico.

Próximos passos

Tente isto hoje: pegue uma tarefa que você consideraria "média" e ligue plan mode no primeiro segundo. Observe como o agente pesquisa antes de opinar. Leia o plano com senso crítico, pergunte "o que está faltando?", aprove só quando estiver claro. Na primeira vez vai parecer lento. Na terceira, você não volta mais. Quando quiser dar o próximo passo e orquestrar trabalho em paralelo durante a fase 1, combine plan mode com subagents — é a combinação que mais economiza tempo em tarefas grandes.