Modo plano no Claude Code: quando vale segurar o agente antes de ele editar arquivos

O agente já editou dez arquivos antes de você entender o que ele entendeu

Fala aí, beleza? Esse é o momento clássico do vibe coding dando errado: não é que a IA seja burra, é que ela partiu pro código antes de você conferir se ela entendeu o problema certo

O modo plano é exatamente o freio entre essas duas coisas: pesquisar e executar

Ele é um dos modos de permissão do Claude Code, e a proposta dele é simples: o Claude lê arquivos, roda comandos de shell pra explorar e escreve um plano, mas NÃO edita o código-fonte

Aqui eu vou te dar o critério: como ligar, como sair, em que tipo de tarefa isso economiza retrabalho de verdade e em que tipo isso só te faz esperar à toa 🙂

O que você precisa antes de usar o modo plano

Nada de setup mirabolante, só três coisas na cabeça antes de apertar qualquer tecla:

• Claude Code instalado e rodando numa sessão: pode ser no terminal, no VS Code ou num IDE JetBrains
• Saber a ordem do ciclo de modos: ao pressionar Shift+Tab a sessão cicla default → acceptEdits → plan
• Reconhecer os rótulos da interface: o nome bonitinho que aparece na tela não é o mesmo nome técnico do modo

E esses rótulos confundem muita gente, então se liga na tradução:

Formação Recomendada

Formação Claude Code

Domine Claude Code do absoluto zero até o avançado

• 114 aulas
• 4 projetos
• 9h 18min

Conhecer formação

Um aviso importante antes que você se confunda mais pra frente: essa tabela é a dos rótulos exibidos na interface, e ela NÃO é a mesma lista da configuração de modo padrão nas settings

Lá os valores válidos são default, acceptEdits, plan, dontAsk e bypassPermissions: repara que o auto aparece como rótulo aqui na tabela e não entra naquela lista, e o dontAsk faz o caminho contrário

São dois conjuntos diferentes mesmo, não é erro de digitação nem contradição

Uma garantia importante do modo plano: edições de arquivo nunca são aprovadas automaticamente ali dentro, mesmo que exista uma regra de allow que combine

Ferramentas de leitura rodam como no modo default, e a edição fica barrada

E os comandos de shell durante o planejamento? Com a configuração useAutoModeDuringPlan ligada (que é o padrão), o classificador revisa os comandos durante o planejamento em vez de te perguntar: os aprovados rodam, os rejeitados são bloqueados

Sem isso, comando que está fora do conjunto read-only embutido volta a pedir aprovação

Como ativar e sair do modo plano no Claude Code:

Passo a passo, só com o que dá pra conferir na documentação

1. Entre no modo plano no meio da sessão

Pressione Shift+Tab pra ciclar entre os modos, ou prefixe um único prompt com /plan quando você quer só aquela rodada planejada

O erro comum deste passo: sair apertando Shift+Tab no automático e não olhar o rótulo que ficou na tela, aí você acha que está em Plan mode e está em Edit automatically

2. Comece a sessão já em modo plano pela linha de comando

claude --permission-mode plan

O erro comum deste passo: combinar essa flag com outras flags de permissão e esperar que ela ganhe (volto nisso mais pra frente, tem relato justamente sobre isso)

3. Use a mesma flag em execução não interativa

A --permission-mode funciona junto do -p, então dá pra manter o comportamento em script

claude -p "analise o modulo de cobranca e proponha um plano" --permission-mode plan

O erro comum deste passo: assumir que -p sozinho já é seguro, sem dizer em qual modo aquilo roda

4. Deixe como padrão nas settings

Existe uma configuração de modo padrão: permissions.defaultMode

{
  "permissions": {
    "defaultMode": "plan"
  }
}

Os valores válidos são default, acceptEdits, plan, dontAsk e bypassPermissions

Como eu falei lá em cima, essa lista é a das settings, não a dos rótulos da interface: o auto da tabela não entra aqui, e o dontAsk só aparece aqui

O erro comum deste passo: inventar valor (tipo escrever o rótulo da interface, "Plan mode", em vez do valor plan)

5. No VS Code, troque pelo seletor

Na aba Code você usa o seletor de modo ao lado do botão de enviar, não o Shift+Tab

O erro comum deste passo: ficar martelando o atalho dentro da aba e achar que o recurso sumiu

6. No plugin dos IDEs JetBrains, é igual à CLI

Lá o Claude Code roda no terminal do IDE, então vale Shift+Tab pra ciclar ou passar --permission-mode ao iniciar

O erro comum deste passo: procurar um botão de modo na interface do plugin, quando a troca é a mesma do terminal

7. Saia do modo plano sem aprovar o plano

Pressione Shift+Tab de novo

O erro comum deste passo: confundir sair do modo com aprovar o plano: são coisas diferentes, a aprovação é explícita

8. Volte a planejar depois de um plano aprovado

Cicle de volta com Shift+Tab, ou prefixe o próximo prompt com /plan

O erro comum deste passo: pedir "planeje com cuidado antes de implementar" dentro do texto e confiar que isso reativa o modo, em vez de acionar o modo você mesmo

Quando o modo plano economiza retrabalho e quando ele só atrasa:

Essa é a parte que ninguém te fala, beleza? Modo plano não é virtude moral, é ferramenta

A documentação oficial de boas práticas é bem direta sobre o porquê: deixar o Claude ir direto ao código pode produzir solução para o problema errado, e a recomendação é usar o modo plano justamente pra separar exploração de execução

Traduzindo: o plano não te protege de código ruim, ele te protege de código certo pro problema errado

Onde ele se paga:

• Refatoração que atravessa vários arquivos: o custo de descobrir tarde que ele mexeu no arquivo errado é altíssimo
• Bug cuja causa ainda não está localizada: aqui o valor está na pesquisa, não na edição
• Base de código grande e desconhecida: você não tem mapa, ele precisa ler antes de escrever
• Tarefa em que resolver o problema errado custa caro: migração, mudança de contrato, coisa que espalha
• Sessão longa: quanto mais tempo rodando, mais caro é o desvio de rota

Aliás, pra sessão longa em base grande a recomendação oficial vai um passo além: peça ao Claude que escreva o plano num arquivo markdown no repositório

O motivo é bem prático: uma sessão longa compacta o contexto ao longo do caminho, e o plano salvo sobrevive onde o histórico da conversa pode não sobreviver

Onde ele só atrasa:

• Ajuste de uma linha
• Correção de texto, label, copy
• Mudança que você já sabe descrever com precisão: se você consegue ditar o diff, planejar é cerimônia
• Loop de tentativa e erro rápido: aquele vai e volta curto onde a resposta aparece rodando, não pensando

A régua que eu uso é essa: se eu não consigo dizer QUAIS arquivos deveriam mudar, o modo plano vale

Se eu consigo, ele só me faz esperar

Vale a mesma lógica quando você já organiza o trabalho com subagentes rodando em paralelo: quanto mais o trabalho se espalha, mais caro fica descobrir tarde que o entendimento inicial estava torto

Como ler o plano e apontar o que está errado antes de aprovar:

Aqui está o pulo do gato, porque aprovar plano no piloto automático é a mesma coisa que não ter modo plano 😛

Antes de dizer sim, passa o olho nessas quatro perguntas:

1. Quais arquivos o plano promete tocar?

Se aparece arquivo que você não esperava, isso é sinal de que ele entendeu outro escopo

2. Ele resolve o SEU problema ou um vizinho?

É o erro mais silencioso: o plano é bom, coerente, bem escrito, e resolve outra coisa

3. O que ele está assumindo sem ter lido?

Procure afirmação sobre como o código funciona hoje que não veio de leitura, veio de palpite

4. O que ficou de fora?

Teste, migração, o outro lugar onde aquele mesmo padrão aparece, o caso de erro

Como intervir sem jogar o plano fora:

Duas saídas verificadas:

• Continuar planejando: escolha "No, keep planning" e diga o que está errado, em vez de aprovar torto e corrigir depois
• Editar o plano você mesmo: dá pra abrir o plano proposto no seu editor de texto padrão com Ctrl+G e editá-lo antes do Claude prosseguir

Esse Ctrl+G é subestimado demais: às vezes é mais rápido apagar duas linhas do plano do que explicar em prosa por que aquelas duas linhas estão erradas

A hora do sim:

Quando o Claude propõe sair do modo plano, aparecem as opções "Yes, and use auto mode" (ou "Yes, auto-accept edits", quando o auto mode não está disponível), "Yes, manually approve edits" e "No, keep planning"

Repara no detalhe: a aprovação é explícita E define em qual modo o Claude passa a editar

Ou seja, você não está só dizendo "pode ir", você está escolhendo o quanto de rédea larga o agente ganha logo em seguida

Se o plano toca em coisa sensível, "Yes, manually approve edits" existe justamente pra isso

O que muda na prática quando você segura o agente

No vídeo abaixo eu mostro o Claude Code do zero, e tem um pedaço que casa direto com esse assunto

Quando eu criei o primeiro projeto ali (uma calculadora de IMC em HTML, CSS e JavaScript), o Claude começou num modo em que ele pede permissão antes de agir: cada arquivo que ele queria editar virava uma pergunta na tela

Tive que aprovar manualmente a edição de arquivo e, na sequência, outras permissões, uma a uma

E eu comento no vídeo: esse fluxo de perguntar tudo deixa o desenvolvimento bem pausado

Mas repara na diferença, que é o ponto desta seção: aprovar edição um por um é interrupção SEM contexto, você diz sim a um pedaço de cada vez sem ver o todo

O modo plano é o contrário: uma interrupção só, com o desenho inteiro na sua frente

É por isso que ele se paga em tarefa média pra cima, e vira burocracia em tarefa pequena: numa calculadora de IMC eu já sei o que precisa acontecer, o plano não me diz nada que eu não saiba

Outra coisa que eu mostro no vídeo e que ajuda muito antes de aprovar qualquer coisa: dá pra abrir o raciocínio do agente (o thinking) e ver como ele planejou cada funcionalidade antes de executar

Quando você lê o raciocínio junto com o plano, fica bem mais fácil apontar onde ele assumiu algo errado

No fim eu rodei o projeto no navegador com Live Server e a calculadora funcionava, então não é que o modo de perguntar tudo não entregue: ele entrega, só cobra a sua atenção o tempo todo

E se você está montando um fluxo mais sério dentro do Claude Code, essa decisão de modo conversa direto com a diferença entre skills e comandos: é tudo a mesma pergunta, quanto de estrutura você coloca antes de soltar o agente

Modo plano não ativa ou não volta: problemas conhecidos

Tem três relatos no repositório oficial que explicam a maioria dos "aqui não funciona"

Importante: são issues reportadas, eu não tenho confirmação do status atual de cada uma, então trate como relato e não como diagnóstico fechado

Sintoma: a sessão não inicia em modo plano

Causa reportada: a issue #19429 descreve --dangerously-skip-permissions sobrepondo --permission-mode plan, impedindo o início no modo plano

O que fazer: não misturar as duas flags no mesmo comando, e conferir o rótulo do modo na tela antes de mandar a tarefa

Sintoma: ele não volta a planejar nas rodadas seguintes

Causa reportada: a issue #53276 descreve que, depois de um ExitPlanMode aprovado, pedidos explícitos de "planeje com cuidado antes de implementar" nas rodadas seguintes não fazem o Claude reentrar no modo plano

O que fazer: acionar o modo na mão, ciclando com Shift+Tab ou prefixando o próximo prompt com /plan, em vez de pedir por texto

Sintoma: o ciclo do Shift+Tab pula o modo plano no Windows

Causa reportada: a issue #17344 tem justamente esse título, "Plan mode missing from mode cycle on Windows, Shift+Tab only toggles to auto-accept"

O que fazer: entrar pelo caminho que não depende do ciclo, ou seja, /plan no prompt, claude --permission-mode plan ao iniciar, ou permissions.defaultMode nas settings

Tome cuidado com uma coisa: circula por aí um atalho alternativo pra Windows que eu NÃO encontrei confirmado na documentação oficial, então não vou te ensinar tecla que eu não consigo checar

A prevenção geral é chata e funciona: não misturar flags de permissão, e olhar o rótulo do modo na interface antes de soltar a tarefa

Conclusão

O critério cabe numa frase: se você não consegue listar quais arquivos deveriam mudar, use o modo plano; se você consegue, ele só te atrasa

O resto é mecânica: Shift+Tab ou /plan pra entrar, claude --permission-mode plan pra já começar assim, permissions.defaultMode pra fixar, Ctrl+G pra editar o plano e aprovação explícita escolhendo em qual modo ele passa a editar

Próximo passo prático, bem simples: pega a sua próxima tarefa média, roda em modo plano, pede pro Claude salvar o plano num arquivo markdown no repositório e compara o retrabalho com a rodada anterior

Se a comparação te decepcionar, ótimo, é sinal de que aquela tarefa era das pequenas e você acabou de calibrar a régua 😀

até o próximo post!