Modo de Planejamento no Claude Code para Tarefas Complexas

O Modo de Planejamento é um estado de permissão somente leitura no Claude Code: o Claude pode ler arquivos, pesquisar o código-fonte, executar comandos shell somente leitura, usar busca na web e fazer perguntas de esclarecimento, mas não pode escrever ou editar seu código-fonte nem executar comandos que alterem o estado do sistema até que você aprove o plano proposto.

A maioria dos desenvolvedores descobre esse recurso da forma mais difícil. Você solicita uma alteração, desvia a atenção por um momento e, ao voltar, percebe que o agente silenciosamente reescreveu meia dúzia de arquivos com base em suposições que você nunca teve a chance de questionar. O Modo de Planejamento insere uma pausa entre “aqui está o que eu quero” e a primeira edição que chega ao disco — que costuma ser exatamente o momento em que as coisas saem dos trilhos. Este artigo aborda o que é o Modo de Planejamento, as quatro formas de ativá-lo, o real limite somente leitura (aplicado por instrução de sistema e pelo sistema de permissões, não por um sandbox rígido), um fluxo de trabalho para refatorações em múltiplos arquivos e quando um plano é puro overhead.

O que é o Modo de Planejamento no Claude Code?

O Modo de Planejamento é um dos modos de permissão do Claude Code, situado ao lado de acceptEdits, auto, dontAsk e bypassPermissions, e não uma superfície de produto separada. Dentro dele, o Claude explora o código-fonte e elabora uma proposta, enquanto as edições ao seu código ficam bloqueadas até que você aprove essa proposta. Os comandos shell são tratados em uma trilha separada: quando o modo automático está disponível durante o planejamento, um classificador avalia cada comando em vez de interrompê-lo; caso contrário, qualquer coisa fora do conjunto somente leitura integrado do Claude Code aguarda sua aprovação.

O valor está na revisão antes da execução. A receita do Claude Code para planejar antes de editar é voltada exatamente para esse caso — alterações que você deseja inspecionar antes que qualquer coisa chegue ao disco. Isso bloqueia o problema de erros compostos: em uma alteração com muitos pontos de decisão, cada suposição errada no início corrompe tudo o que vem depois, e um plano permite corrigir essas suposições no papel em vez de em um diff.

Como ativar o Modo de Planejamento?

Há quatro formas de entrar no Modo de Planejamento, e elas diferem em escopo. Escolha a que corresponde ao tempo que você deseja que o modo permaneça ativo.

A documentação oficial confirma a ordem de alternância: Shift+Tab avança default → acceptEdits → plan, portanto dois pressionamentos a partir do modo inicial levam ao Modo de Planejamento, com o modo atual exibido na barra de status. Observe o rótulo: o modo default agora é exibido como Manual na CLI e nas extensões de IDE, embora seu valor de configuração ainda seja default. Para um padrão de projeto, a chave é aninhada. Defina-a em .claude/settings.json sob "permissions": { "defaultMode": "plan" }, não no nível superior.

O que o Modo de Planejamento Pode e Não Pode Fazer

No Modo de Planejamento, o Claude mantém suas ferramentas de leitura e pesquisa (Read, Grep, Glob, Task/subagents, WebSearch e WebFetch), enquanto suas ferramentas Write, Edit e Bash para alterações ficam retidas até que você aprove. As ferramentas MCP que alteram o estado são retidas da mesma forma. O inventário exato de ferramentas é uma propriedade do harness e muda entre versões, portanto trate isso como o conjunto geral, não como um contrato exaustivo.

O limite é aplicado por uma instrução de sistema injetada mais o sistema de permissões do Claude Code, e não por um sandbox rígido — é por isso que o próprio plano é gravado em um arquivo markdown editável, em vez de ser bloqueado como uma “escrita”. A análise da implementação do modo de planejamento feita por Armin Ronacher descobriu que as ferramentas de escrita ainda estão presentes e que entrar no modo de planejamento injeta um prompt informando ao modelo que ele está em modo somente leitura; a ferramenta de edição é o que o Claude usa para criar seu próprio arquivo de plano. A documentação corrobora que isso é uma camada de permissão, não remoção de ferramentas: em uma sessão padrão, as escritas em caminhos protegidos ainda passam pelo sistema de prompt em vez de serem descartadas silenciosamente. Na prática, isso significa que o plano é um contrato em texto simples que você pode editar. Pressione Ctrl+G para abrir o plano proposto no seu editor de texto, anote ou exclua etapas, e o Claude incorporará suas alterações antes de escrever qualquer código.

Um Fluxo de Trabalho do Modo de Planejamento para Tarefas Complexas

Para uma alteração em múltiplos arquivos, o ciclo é: descrever → esclarecer → planejar → editar → executar:

1. Descreva a tarefa no Modo de Planejamento e aponte o Claude para os arquivos relevantes. Declare o objetivo e as restrições no primeiro prompt.
2. Deixe o Claude ler e perguntar. Ele rastreia as importações e então apresenta as decisões genuinamente ambíguas (profundidade da arquitetura, o que fazer com código morto, qual framework de testes) antes de se comprometer com uma abordagem. Um sinal fraco é um plano que nomeia apenas arquivos, nunca funções específicas.
3. Revise o plano numerado. Verifique se as etapas estão ordenadas por dependência e se os testes estão intercalados com a implementação, e não adicionados apenas no final.
4. Edite e aprove. Use Ctrl+G para anotar ou reordenar, depois aprove quando o contrato estiver correto.
5. Execute e observe desvios. O Claude trabalha passo a passo seguindo o plano aprovado.

Aprovar um plano encerra o Modo de Planejamento; portanto, se a execução se desviar (o Claude edita um arquivo que a etapa atual não mencionava, ou silenciosamente toma uma decisão que o plano deixou em aberto), pressione Shift+Tab para reentrar no Modo de Planejamento e peça ao Claude que replaneje o trabalho restante com base no estado atual dos arquivos. Replanejar no meio de uma tarefa é normal em refatorações reais, não uma falha. Para trabalhos grandes demais para uma única sessão, divida-os em planos sequenciais em vez de um único documento extenso.

Separando Planejamento e Execução entre Modelos

Para trabalhos complexos, use o modelo de raciocínio mais poderoso para elaborar o plano e um modelo mais rápido e econômico para executá-lo: a qualidade do planejamento domina os resultados, enquanto a execução é amplamente mecânica quando o plano está correto. O Claude Code implementa isso como um alias de modelo em vez de uma alternância. Selecionar opusplan executa o modelo opus enquanto você está no modo de planejamento e muda para sonnet no momento em que a execução começa.

Na API da Anthropic, opus resolve para o Claude Opus 5 e sonnet resolve para o Claude Sonnet 5, portanto opusplan oferece o Opus 5 para planejamento e o Sonnet 5 para execução. O Opus 5 requer o Claude Code v2.1.219 ou posterior; em versões anteriores, o alias opus ainda aponta para o Opus 4.8. Os aliases acompanham a versão recomendada para o seu provedor e são atualizados conforme novos modelos são lançados, portanto fixe um nome de modelo completo como claude-opus-5 quando precisar de uma versão específica. O Opus também não é o topo da hierarquia: a visão geral dos modelos posiciona o Claude Fable 5 acima do nível Opus como o modelo mais capaz da Anthropic amplamente disponível, e o Claude Code o expõe por meio do alias fable para trabalhos maiores do que uma única sessão.

Quando Usar o Modo de Planejamento e Quando Ignorá-lo

Use o Modo de Planejamento quando uma alteração envolver aproximadamente três ou mais arquivos, incluir uma refatoração, migração de esquema ou trabalho sensível à segurança, ou não puder ser descrita em uma única frase; ignore-o para correções de uma linha e edições mecânicas onde um plano é puro overhead. Três arquivos é aproximadamente o ponto em que as decisões compostas começam a ser problemáticas. Correções de digitação, ajustes isolados em funções e renomeações em um único arquivo são mais rápidos sem o ciclo de planejamento. Qualquer situação em que você não tem certeza de como o código-fonte lida com um caso específico, ou onde uma edição prematura seria cara de desfazer, vale a pena planejar primeiro.

A regra da frase única é o filtro mais rápido: se você consegue descrever toda a alteração em uma única frase, simplesmente faça-a; caso contrário, planeje-a. Escale além disso apenas quando um plano genuinamente supera um único contexto de execução — nesse ponto, o recurso experimental Agent Teams do Claude Code distribui o trabalho entre instâncias, com o agente líder revisando e aprovando o plano de cada membro da equipe antes que ele comece a escrever.

Utilize o Modo de Planejamento na sua próxima alteração em múltiplos arquivos, edite o plano com Ctrl+G antes de conceder acesso de escrita e retorne com Shift+Tab no momento em que a execução se desviar. A mecânica muda com frequência, portanto confirme quaisquer especificidades vinculadas a versões na documentação oficial do Claude Code antes de depender delas.

Perguntas Frequentes

O Modo de Planejamento realmente impede o Claude de editar arquivos, ou ele ainda pode escrever?

O Modo de Planejamento bloqueia edições ao seu código-fonte, mas não é um sandbox rígido. O limite somente leitura é aplicado por uma instrução de sistema injetada mais o sistema de permissões do Claude Code, e não pela remoção das ferramentas de escrita. A ferramenta de edição ainda está presente — é assim que o Claude cria seu próprio arquivo de plano — e qualquer tentativa de escrita no seu código ainda passa pelo prompt de permissão, em vez de ser silenciosamente permitida.

Qual é a diferença entre usar Shift+Tab, o prefixo /plan e a flag --permission-mode plan?

Eles diferem em escopo. Pressionar Shift+Tab alterna o modo para a sessão atual e persiste até que você alterne novamente. O prefixo /plan se aplica apenas ao próximo prompt, deixando seu modo inalterado. Iniciar com claude --permission-mode plan coloca toda a sessão no modo de planejamento desde o início. Para um padrão permanente, defina permissions.defaultMode como plan no settings.json para que se aplique a todas as sessões no escopo do projeto ou do usuário.

Como tornar o Modo de Planejamento o padrão para um projeto?

Defina defaultMode como plan dentro do objeto permissions em .claude/settings.json, escrito como permissions contendo defaultMode definido como plan. A chave é aninhada sob permissions, não colocada no nível superior do arquivo. Uma vez definida, toda sessão iniciada nesse projeto começa automaticamente no Modo de Planejamento. Use um arquivo de configurações no nível do usuário se quiser o comportamento de planejamento prévio em todos os seus projetos, e não apenas em um repositório.

O que acontece depois que aprovo um plano e como faço o Claude replanejar no meio de uma tarefa?

Aprovar um plano encerra a fase de planejamento e move a sessão para o modo de permissão descrito pela opção de aprovação que você escolheu, portanto o Claude começa a trabalhar imediatamente. Se a execução se desviar das etapas acordadas, pressione Shift+Tab para reentrar no Modo de Planejamento, ou prefixe seu próximo prompt com /plan, e peça ao Claude que replaneje o trabalho restante com base no estado atual dos arquivos. Replanejar no meio de uma tarefa é esperado em refatorações reais, não uma falha.

Qual modelo deve elaborar o plano versus executá-lo?

Use o modelo de raciocínio estável mais poderoso para elaborar o plano e um modelo mais rápido e econômico para executá-lo, já que a qualidade do planejamento domina os resultados enquanto a execução é amplamente mecânica. O Claude Code automatiza a transição por meio do alias de modelo opusplan, que executa o Opus durante o modo de planejamento e muda para o Sonnet na execução. Na API da Anthropic, esses aliases resolvem para Claude Opus 5 e Claude Sonnet 5, respectivamente. Os aliases são atualizados conforme novos modelos são lançados, portanto fixe um nome de modelo completo quando precisar de uma versão específica.