O Claude Code tem um comportamento que parece ótimo até não ser: ele age rápido demais.

Você digita "refatora o controller de pedidos pra usar o padrão Repository" e, antes de você terminar de ler o que ele vai fazer, ele já editou seis arquivos, criou dois novos e deletou um. O resultado pode estar certo. Mas você não sabe, porque não viu o plano antes. E se estiver errado, você passa os próximos dez minutos revertendo no git enquanto tenta entender o que mudou.

O modo Plan existe pra resolver exatamente isso.

O que é o modo Plan do Claude Code

O modo Plan muda o comportamento do agente de "age e me mostra o resultado" para "me mostra o plano e age só quando eu aprovar".

Na prática: você faz um pedido, o Claude lê os arquivos relevantes, monta uma lista ordenada de passos com o que vai fazer em cada um e aguarda. Você lê, aprova, ajusta ou cancela. Só depois ele começa a editar.

Isso não é um modo de emergência pra quem tem medo de IA. É um modo de trabalho diferente, mais adequado pra situações onde o escopo é amplo ou o impacto é alto. A documentação oficial do Claude Code chama isso de separar a fase de "entendimento e planejamento" da fase de "execução".

Como ativar

Tem dois caminhos:

Shift+Tab no prompt. Pressionar Shift+Tab alterna entre três modos: Auto (padrão), Plan e sem agente. O indicador aparece no canto do terminal. É fácil esquecer que mudou, então preste atenção nele.

Digitando /plan no prompt. Funciona como comando direto. Útil quando você tá no meio de uma conversa e quer mudar o comportamento só pra aquele pedido específico.

Nos dois casos, o Claude confirma o modo ativo antes de agir.

Como funciona na prática

Vou usar um exemplo concreto: refatorar um controller de ASP.NET Core pra extrair a lógica de negócio em um serviço separado.

Sem modo Plan:

Você digita o pedido, o Claude começa imediatamente. Ele cria PedidoService.cs, modifica PedidoController.cs, atualiza o Program.cs pra registrar o serviço no container de DI. Pode estar tudo certo. Mas talvez ele tenha renomeado um método que outras partes do sistema chamam, ou adicionado uma dependência que você queria evitar por uma razão arquitetural que ele não conhecia.

Com modo Plan:

Você digita o mesmo pedido. O Claude lê PedidoController.cs, Program.cs e qualquer arquivo que referencia o controller. Então apresenta algo assim:

Plano de refatoração:

1. Criar IPedidoService.cs em Interfaces/ com os métodos:
   - CriarPedido(PedidoDto dto): Task<Pedido>
   - BuscarPorId(int id): Task<Pedido?>
   - ListarPorCliente(int clienteId): Task<List<Pedido>>

2. Criar PedidoService.cs em Services/ implementando a interface

3. Mover a lógica de negócio de PedidoController.cs para PedidoService

4. Injetar IPedidoService no controller via construtor

5. Registrar PedidoService como scoped em Program.cs

6. Manter os endpoints com as mesmas assinaturas HTTP (sem breaking changes)

Prosseguir?

Antes de aprovar, você viu o escopo inteiro. Dá pra pedir ajuste: "troca o passo 1, quero a interface dentro de Domain/Contracts/, não em Interfaces/" — e só depois liberar a execução.

Aí você chega no final com um resultado que você acompanhou do início.

Quando usar Plan vs Auto

A resposta curta: Plan pra quando o impacto é alto ou o escopo é incerto; Auto pra quando o pedido é simples e o resultado é previsível.

Use Plan quando:

• A mudança envolve mais de três arquivos
• Você tá mexendo em código crítico: controllers de pagamento, autenticação, jobs agendados
• É uma refatoração estrutural: mudança de padrão, reorganização de namespace, extração de serviço
• Você não tem certeza de quais arquivos o Claude vai tocar

Deixa no Auto quando:

• Você pediu um método simples ou uma classe nova isolada
• É geração de boilerplate: DTOs, migrations, testes unitários de um método
• O escopo é claro e limitado a um arquivo

Com o tempo você desenvolve o senso de quando cada modo serve. Na maioria dos dias você trabalha no Auto e ativa o Plan nos momentos certos.

Combinando Plan mode com CLAUDE.md e hooks

O modo Plan fica mais útil quando combinado com as outras ferramentas de contexto do Claude Code.

Se você já tem um CLAUDE.md com as convenções do seu projeto .NET (estrutura de pastas, padrões de nomenclatura, restrições de arquitetura), o plano que o Claude apresenta vai estar alinhado com essas convenções desde o início. Em vez de aprovar e corrigir depois, você aprova com confiança porque o contexto já estava lá.

Combinado com hooks configurados no projeto, como um hook que roda dotnet format e dotnet build depois de cada conjunto de edições, você tem um ciclo completo: plano aprovado, edição executada, formatação aplicada, build validado automaticamente.

Esses três recursos juntos formam um workflow que escala bem em projetos .NET reais: o CLAUDE.md define as regras, o Plan mode garante que você aprova antes de executar, e os hooks automatizam a verificação depois.

O que o modo Plan não resolve

Dois erros comuns de expectativa:

Ele não prevê comportamento em runtime. O Claude vai propor um plano baseado no que lê estaticamente. Se o plano criar um bug em runtime (uma race condition, um problema de configuração no DI container), isso não vai aparecer no plano. Testes continuam sendo necessários.

Ele não substitui revisão de código. O plano é uma proposta de estrutura. Depois de executado, ainda vale fazer git diff e ler o que mudou antes de commitar. O Plan mode reduz surpresas, não as elimina.

Mas dentro do que ele promete: mostrar o que vai fazer antes de fazer. Funciona de forma consistente.

Por que isso importa pra quem tá aprendendo a usar IA no código

Se você tá começando a integrar Claude Code no dia a dia, o modo Plan tem um benefício que vai além de evitar erros: ele te mantém no controle do que está sendo produzido.

É fácil cair no padrão de aceitar o resultado sem entender o que mudou. Com o modo Plan no caminho, você lê cada etapa antes de executar. Com o tempo, você desenvolve um senso de como o Claude raciocina em refatoração, quais decisões ele toma por padrão, onde as convenções do seu projeto estão sendo respeitadas ou não.

Isso é o que separa quem usa IA como ferramenta de quem deixa a ferramenta mandar no código.

Mas se você ainda tá no começo e quer entender como o Claude Code funciona antes de configurar modos e hooks, o guia completo de Claude Code é o lugar certo pra começar.

Perguntas frequentes sobre o modo Plan

Como ativar o modo Plan no Claude Code?

Pressione Shift+Tab no prompt para alternar entre Auto, Plan e sem agente. Ou digite /plan diretamente no prompt. O modo ativo aparece indicado no terminal.

O plano apresentado é editável antes de executar?

Sim. Depois que o Claude apresenta o plano, você pode responder com ajustes: mudar estrutura de pastas, remover etapas, pedir uma abordagem diferente. Só depois de aprovado ele começa a editar os arquivos.

O modo Plan consome mais tokens?

Um pouco mais. O Claude precisa ler os arquivos e escrever o plano antes de agir. Mas você evita o custo de reverter mudanças grandes no git, o que compensa na maioria dos cenários.

Dá pra usar Plan mode pra qualquer pedido?

Dá, mas não faz sentido em pedidos simples. Pra gerar um DTO ou adicionar um campo numa migration, o Auto resolve mais rápido. O Plan mode brilha quando o escopo não é óbvio de cara.

Quanto tempo leva pra o Claude montar o plano?

Depende do tamanho do codebase e de quantos arquivos ele precisa ler. Em projetos .NET médios, entre 15 e 40 segundos. É o tempo de leitura mais raciocínio antes de agir, e não dá pra cortar isso sem perder qualidade no plano.