Modo de planejamento no Claude Code: quando vale usar e como revisar

Modo de planejamento no Claude Code: quando vale usar e como revisar

O modo de planejamento do Claude Code vale a pena quando a tarefa mexe em vários arquivos, toca uma parte do código que você não domina ou tem mais de um caminho possível. Nele, o agente lê o projeto e propõe um plano sem alterar nada, e só depois de você aprovar é que as edições começam. O ganho vem de descobrir o erro de entendimento no plano, onde corrigir custa uma frase, e não no código já alterado.

Principais pontos

• O modo de planejamento separa duas fases: explorar o código (somente leitura) e editar (só após aprovação do plano).
• Ele compensa em tarefas com impacto em vários arquivos, código desconhecido, migrações e refatorações. Em ajustes pequenos e óbvios, só adiciona uma etapa.
• Um plano bom lista arquivos, ordem das mudanças, riscos, o que fica de fora e como verificar o resultado.
• Revisar o plano é trabalho de quem conhece o negócio, não só de quem conhece a sintaxe. Aprovar sem ler anula o benefício.
• O modo de planejamento reduz o risco de edição precipitada, mas não substitui permissões restritas, revisão do código final e testes.

O que é o modo de planejamento e o que ele muda na prática

O Claude Code trabalha com modos de permissão. No modo padrão, ele pede autorização para ações como editar arquivos ou executar comandos. No modo de planejamento, o agente fica restrito a investigar: lê arquivos, busca trechos, entende a estrutura e conversa com você sobre a abordagem. Ao terminar, apresenta um plano e pede sua decisão: aprovar, ajustar ou continuar planejando.

Segundo a documentação oficial, o modo pode ser alternado durante a sessão pelo atalho Shift+Tab, que percorre os modos de permissão, ou iniciado já em planejamento pela opção de linha de comando para o modo de permissão. Os nomes exatos das opções e o comportamento da tela de aprovação mudam entre versões, então confira a documentação da versão que sua equipe usa antes de padronizar um procedimento interno.

O que muda na prática é a ordem do trabalho. Sem o modo de planejamento, o agente tende a ler um pouco, decidir e já editar. Com ele, a decisão vira um artefato legível, um plano, que você pode corrigir antes que exista qualquer alteração para desfazer.

Por que separar explorar de editar reduz retrabalho

A maior parte do retrabalho em tarefas de código com IA nasce de um entendimento errado do problema, não de erro de digitação. O agente achou que a regra de desconto vivia em um módulo quando vivia em outro. Assumiu que podia mudar um contrato de API sem avisar quem consome. Escolheu uma biblioteca que o projeto evita por motivo histórico.

Quando exploração e edição acontecem juntas, esse erro só aparece no resultado: um conjunto de mudanças espalhadas que você precisa ler, entender e reverter. Quando estão separadas, o erro aparece no plano, em uma linha como alterar a função de cálculo em tal arquivo, e você corrige com uma frase.

Há também um efeito sobre o contexto. A exploração consome espaço da conversa, e o plano funciona como um resumo do que importa. Isso se conecta ao que explicamos em janela de contexto em IA: quanto mais lixo acumulado, pior a qualidade das decisões seguintes. Um plano curto e revisado dá ao agente um ponto de partida limpo para a fase de edição.

Uma ressalva de honestidade: isso é experiência de implementação e raciocínio de processo, não uma garantia documentada. O modo de planejamento não torna o modelo mais inteligente. Ele só cria um ponto de controle antes da mudança.

Em quais tarefas vale usar o modo de planejamento

Um guia de decisão simples, em formato de lista:

• Use quando a mudança afeta vários arquivos ou camadas (interface, regra de negócio, banco de dados).
• Use quando você ou a equipe não conhecem bem a parte do código envolvida.
• Use em migrações, atualizações de dependências e refatorações, em que a ordem dos passos importa.
• Use quando existem pelo menos duas abordagens plausíveis e a escolha tem consequência (por exemplo, mudar um contrato de API ou criar uma tabela nova).
• Use quando o pedido está ambíguo: o agente pode fazer perguntas antes de assumir.
• Use para investigar um problema antes de corrigir, como no fluxo descrito em como debugar código com IA, em que hipóteses vêm antes de qualquer correção.

E quando não usar:

• Ajustes pequenos e óbvios, como corrigir um texto, renomear uma variável local ou mudar uma cor.
• Tarefas que você já descreveu com precisão, apontando arquivo e mudança esperada.
• Experimentos descartáveis em um ramo isolado, em que reverter é trivial.

A regra prática: quanto mais caro for desfazer, mais o plano compensa. Para uma empresa que mantém sistemas ligados a atendimento, cobrança ou dados de clientes, quase toda mudança fora do trivial cai na primeira lista.

Como conduzir uma sessão de planejamento, passo a passo

Um roteiro que funciona para a maioria das tarefas:

• Passo 1: entre no modo de planejamento antes de pedir a tarefa. Confirme na interface que o modo está ativo.
• Passo 2: descreva o objetivo de negócio, não só a mudança técnica. Diga quem usa essa função, o que não pode quebrar e o que está fora do escopo.
• Passo 3: aponte onde olhar, como arquivos, pastas ou documentos de decisão. Se o projeto tem convenções, peça que o agente as leia primeiro.
• Passo 4: peça perguntas antes do plano. Se o agente não perguntar nada em uma tarefa ambígua, desconfie.
• Passo 5: peça o plano em formato revisável: arquivos afetados, ordem, riscos, o que não será alterado e como verificar.
• Passo 6: revise, questione e peça ajustes sem sair do modo de planejamento. Repita até o plano estar claro.
• Passo 7: só então libere a execução. Decida se as edições serão aprovadas uma a uma ou em bloco, conforme o risco da tarefa.

Se a equipe repete esse roteiro com frequência, vale transformá-lo em instrução permanente. Isso é exatamente o tipo de procedimento que cabe em skills no Claude Code, para que todos peçam planos no mesmo formato.

Como revisar o plano antes de liberar mudanças

Aprovar um plano sem ler é só uma forma mais lenta de editar às cegas. A revisão não precisa ser longa, mas precisa ser feita por alguém que entenda o que o sistema faz para o negócio. Um checklist de revisão:

• Escopo: o plano resolve o problema pedido e só ele? Há mudanças extras que ninguém pediu?
• Arquivos: os arquivos listados fazem sentido? Falta algum que você sabe que será afetado, como testes, documentação ou configuração?
• Ordem: a sequência permite parar no meio sem deixar o sistema quebrado?
• Dados: alguma etapa lê, grava ou apaga dados de clientes? Se sim, está claro quais e por quê? Em projetos que lidam com dados pessoais, essa pergunta se liga às obrigações da LGPD e à política interna da empresa.
• Dependências e acessos: o plano pede instalar pacotes novos, chamar serviços externos ou usar credenciais? Cada item precisa de justificativa. Quando há integrações por MCP no Claude Code, confira em qual escopo estão configuradas e o que cada ferramenta pode fazer.
• Riscos declarados: o plano admite incertezas? Um plano sem nenhum risco listado costuma ser raso.
• Verificação: há um modo concreto de saber se funcionou, como testes a rodar ou um comportamento a conferir manualmente? Sobre confiar nos testes que a própria IA escreve, vale ler testes automatizados gerados por IA.
• Reversão: se der errado, como voltar? Trabalhar em um ramo separado do controle de versão costuma resolver.

Se qualquer item estiver fraco, não aprove: peça a correção ao agente, ainda dentro do modo de planejamento. Frases úteis são mostre onde você viu isso no código, qual é a alternativa que você descartou e por quê, e o que acontece com o que já existe se esse passo falhar.

Cenário ilustrativo: mudar a regra de arredondamento de um orçamento

Imagine uma empresa pequena que mantém um sistema interno de orçamentos. Alguém pede: arredondar o valor total para cima em múltiplos fixos. Parece uma linha de código.

No modo de planejamento, o agente lê o projeto e devolve um plano. Ele identifica que o cálculo do total aparece em dois lugares: na tela de orçamento e na geração do PDF enviado ao cliente. Aponta também que um relatório mensal soma os totais salvos e que a mudança alteraria comparações com meses anteriores. E pergunta se o arredondamento vale só para orçamentos novos ou também para os já emitidos.

Sem o plano, a edição provavelmente mudaria apenas a tela, deixando o PDF com um valor diferente do que o vendedor viu. Com o plano, a equipe decide que só orçamentos novos são afetados, inclui o PDF no escopo e pede um teste que compare tela e documento. A diferença não é o agente ter acertado de primeira, mas o desencontro ter aparecido antes de existir código.

Este é um cenário ilustrativo, construído para mostrar o raciocínio. Não descreve nenhum projeto real nem resultado medido.

Limites do modo de planejamento

Três limites que vale deixar claros para a equipe:

• Um plano convincente pode estar errado. O texto é fluente mesmo quando a premissa é falsa, então verifique as afirmações sobre o código antes de aprovar.
• O modo de planejamento é um controle de processo, não uma fronteira de segurança completa. Permissões, ambientes isolados e acesso mínimo a credenciais continuam necessários. Se o agente lê arquivos com conteúdo de terceiros, o risco de prompt injection também continua existindo.
• O plano não substitui a revisão do resultado. Depois da execução, leia as mudanças e rode os testes como faria com o trabalho de qualquer pessoa.

Há ainda o custo de tempo. Planejar tudo, inclusive o trivial, cria fricção, e a equipe acaba aprovando por reflexo. Reserve o modo para onde ele muda a decisão.

Como isso se encaixa no método de trabalho

O modo de planejamento é uma aplicação pequena das mesmas etapas que usamos ao implantar IA em processos: mapear, limitar, pilotar e transferir. Mapear é a fase de exploração, em que o agente entende o código e você confere esse entendimento. Limitar é o plano aprovado: escopo, arquivos, acessos e o que fica de fora. Pilotar é executar uma tarefa real, com registro do que foi pedido, planejado e entregue, e um critério de sucesso combinado antes. Transferir é deixar o procedimento documentado para que a equipe repita sem depender de quem o criou, e então decidir se expande, ajusta ou para.

Para orientar a prática, os materiais da Anthropic sobre construção de agentes e sobre engenharia de contexto, listados nas fontes, tratam de ideias próximas: dividir o trabalho em etapas verificáveis e manter no contexto apenas o que ajuda a decidir.

Perguntas frequentes

O modo de planejamento do Claude Code impede qualquer alteração? Na fase de planejamento, o agente fica restrito a investigar e propor, sem editar arquivos. Mesmo assim, não trate isso como substituto de permissões bem configuradas e de um ramo separado para o trabalho. O comportamento exato pode variar entre versões, então confirme na documentação.

Preciso usar o modo de planejamento em toda tarefa? Não. Para ajustes pequenos e bem descritos, ele só acrescenta uma etapa. Use quando a mudança atravessa vários arquivos, envolve código pouco conhecido ou tem mais de um caminho possível.

Quem deve revisar o plano? Quem entende o impacto da mudança no negócio e no sistema, e não necessariamente quem pediu a tarefa. Em mudanças que envolvem dados de clientes, vale incluir também quem responde pela proteção de dados na empresa. O ponto é que a aprovação seja uma decisão consciente, não um clique.

O que fazer se o plano vier vago ou com premissas erradas? Não aprove. Continue no modo de planejamento e peça ao agente que mostre onde viu cada informação no código, liste alternativas descartadas e declare os riscos. Se o plano continuar fraco, reduza o escopo da tarefa e comece por uma parte menor.

Fontes

• Anthropic: Claude Code, best practices for agentic coding
• Anthropic: Building effective agents
• Anthropic: Effective context engineering for AI agents