Claude Code Plan Mode: ciclos de refatoração com revisão de design primeiro

Muitos desenvolvedores começam a usar o Claude Code do mesmo jeito: colam uma tarefa, deixam rodar e revisam o diff. Funciona para mudanças pequenas, mas qualquer coisa que mexe em vários arquivos começa a desandar. 

Cada decisão sem orientação que o Claude toma pode estar certa na maioria das vezes — o que parece ok até você compor os erros: por exemplo, se você assume 80% de acerto por decisão, em um recurso com 20 pontos de decisão, 0.8^20 derruba suas chances para cerca de 1%.

O Plan Mode muda essa conta ao adicionar uma fase somente leitura. Você obriga o Claude a ler o codebase, levantar perguntas e produzir um plano que você revisa antes de tocar em qualquer arquivo. 

Este tutorial percorre esse fluxo usando uma API de blog em FastAPI bagunçada como exemplo, cobrindo o loop Explorar-Planejar-Executar, edição do plano com Ctrl+G e como escalar para refatorações maiores com Agent Teams. 

Nosso tutorial de boas práticas do Claude Code aprofunda o problema de erros compostos, e o guia do Claude Code 2.1 explica a instalação e os recursos caso você precise de ajuda com o setup.

Para saber mais sobre os modelos por trás do Claude Code, confira nossos guias do Claude Sonnet 4.6 e do Opus 4.6, ou faça o curso Introduction to Claude Models.

O que é o Plan Mode do Claude Code?

O Plan Mode coloca o Claude em operações somente leitura. Ele pode ler arquivos, buscar no codebase e fazer perguntas, mas qualquer tentativa de escrever arquivos, editar código ou rodar comandos no shell é recusada. Tente pedir para "só fazer um ajuste rápido" no Plan Mode e ele não vai ceder.

Você pode ativá-lo de quatro formas:

• Shift+Tab duas vezes no campo de entrada alterna entre Normal, Auto-Accept e Plan Mode

• O comando /plan entra no Plan Mode até você trocar de modo novamente

• A flag de CLI --permission-mode plan inicia uma nova sessão no Plan Mode

• Uma entrada em settings.json sob permissions.defaultMode define o Plan Mode como padrão permanente

Quando o Claude termina de gerar um plano, ele salva o resultado como um arquivo markdown em ~/.claude/plans/ com um nome aleatório (como dreamy-orbiting-quokka.md). 

Esse arquivo é um contrato revisável: persiste entre sessões, sobrevive tanto a /clear quanto à compactação de contexto, e nada é implementado até você aprovar. Observe que, embora o arquivo do plano persista, o Claude às vezes pode perdê-lo de vista após a compactação de contexto, a menos que você peça para reler o plano.

Se quiser armazenar os planos dentro do seu projeto para controle de versão, defina plansDirectory em settings.json para um caminho relativo ao projeto, como ./plans.

Planos relativos ao projeto abrem fluxos de trabalho que ~/.claude/plans/ não suportam:

• Revisar diffs do plano em pull requests antes de alguém começar a codar
• Levar anotações adiante entre sessões sem depender da compactação de contexto
• Tratar o arquivo markdown como uma especificação viva que vários membros do time editam diretamente

Para refatorações longas ou trabalho em várias sessões, um arquivo de plano versionado dá mais controle do que só Ctrl+G.

Implementando um fluxo Explorar-Planejar-Executar no Claude Code

Para ver como as três fases funcionam juntas, vamos refatorar um repositório fastapi-blog-api. Ele não tem testes e traz três arquivos que fazem coisa demais: 

• main.py: todas as rotas, checagens de auth inline, config hardcoded, envio de e-mail

• models.py: modelos ORM, schemas Pydantic, funções de consulta, seed data

• utils.py: hash de senhas, tokens JWT, uploads S3, renderização de markdown, cache, rate limiting, exportação CSV

Fase 1: reúna contexto antes de qualquer coisa

Comece a tarefa no Plan Mode (clone o repositório no GitHub localmente primeiro). O prompt inicial deve dizer ao Claude o que você quer e direcioná-lo a ler os arquivos relevantes:

I want to refactor this FastAPI blog API into a clean module structure with proper separation of concerns and full test coverage. Read through main.py, models.py, and utils.py first. Map out which functions belong together, flag any shared state or circular dependency risks, and identify what needs testing most.Tecnologia

O Claude delega a pesquisa do codebase a um subagente interno restrito a ferramentas de leitura. Ele leu os três arquivos, rastreou os imports entre eles e usou AskUserQuestion para expor ambiguidades. 

As perguntas cobriram algumas decisões de alto nível:

• Profundidade arquitetural (routers planos vs. camadas de serviço completas)
• Como lidar com config hardcoded
• Se funções utilitárias mortas devem ser removidas ou mantidas
• Qual framework de testes usar

Essas perguntas importam. Só a questão da arquitetura teria sido uma moeda no ar sem input humano. O Claude tende ao padrão que mais viu nos dados de treino e, no caso do FastAPI, geralmente é uma estrutura com routers planos. Responder "use uma service layer" aqui economizou uma rodada inteira de re-refatoração depois.

Se você tiver um projeto de referência que casa com a arquitetura alvo, inclua o link no seu prompt. O Claude produz planos melhores quando tem um exemplo funcional de onde se basear, em vez de descrições abstratas.

Uma coisa para verificar antes de aceitar qualquer plano: as perguntas do Claude citam funções específicas e detalhes de linha, ou só nomes de arquivos? Se ele pergunta sobre "o sistema de auth" mas nunca menciona verify_jwt_token ou a cadeia de middleware em main.py, ele passou os olhos em vez de ler. Force uma leitura mais cuidadosa antes de ir para a Fase 2.

Fase 2: gere e edite o plano

Depois que você responde às perguntas do Claude, ele gera um plano automaticamente. Não precisa de prompt separado. O plano é salvo em ~/.claude/plans/ e inclui: 

• Resumo do contexto
• Estrutura de diretórios alvo
• Ordem de implementação passo a passo
• Seção de verificação com comandos para confirmar que a refatoração funcionou

Antes de decidir como prosseguir, pressione Ctrl+G para abrir o plano no seu editor de texto padrão (definido por $EDITOR). Em alternativa, use /plan open para abrir diretamente o arquivo do plano ativo.

É aqui que o Plan Mode se paga. Você pode anotar passos com comentários inline, excluir etapas com as quais não concorda, reordenar operações e salvar. O Claude capta todas as edições quando você volta ao terminal.

Para o plano da API de blog, as anotações podem ser assim:

## Step 3: Extract auth module
Move JWT validation and password hashing to auth/
> NOTE: extract auth middleware BEFORE splitting routes,
> otherwise the route files will import from utils.py
> and we'll have to update imports twice
 
## Step 5: Database layer
Create a repository pattern for database operations
> NOTE: keep the SQLAlchemy session factory in a shared
> db.py, don't put it in models.pyTecnologia

Para planos complexos, uma passada com Ctrl+G pode não ser suficiente. Anote, volte, diga ao Claude "enderece todas as anotações no plano, não implemente ainda", revise a versão ajustada e use Ctrl+G novamente. Cada rodada de anotações remove ambiguidades que virariam decisões de implementação erradas.

Quando o contrato estiver do seu jeito, o Claude oferece algumas opções: 

1. Trabalhar no plano e limpar o contexto (bom quando a sessão está ficando estagnada), 
2. Trabalhar sem limpar (para manter o histórico da conversa), ou 
3. Continuar conversando sobre o plano. 

Escolha com base no quanto de contexto você já construiu. Se você está em uma sessão longa, limpar dá ao Claude uma janela fresca para executar.

Fase 3: execute o plano aprovado

Escolha uma opção de trabalho e o Claude começa a implementar passo a passo. Ele percorre cada etapa e para quando precisa de intervenção manual (como autenticação interativa no terminal) ou quando conclui o plano inteiro.

Fique de olho no desvio. O plano dizia para extrair auth em seu próprio módulo primeiro, mas o Claude pode começar a puxar rotas e lógica de auth ao mesmo tempo porque viu um atalho. Esse tipo de movimento é como você acaba com um codebase meio migrado, em que alguns imports apontam para o local antigo e outros para o novo. 

Outros sinais de desvio: 

• Editar um arquivo não mencionado na etapa atual
• Tomar silenciosamente uma decisão de arquitetura que o plano deixou em aberto
• Juntar duas etapas que o plano manteve separadas

Quando houver desvio, use Shift+Tab para voltar ao Plan Mode. O Claude lê o estado atual dos arquivos, produz um plano revisado para as etapas restantes e você o revisa antes de continuar. Isso não é medida emergencial. A maioria das refatorações multi-arquivo passa por 2–3 revisões de plano até concluir.

Para refatorações que não cabem em uma única sessão, quebre o trabalho em planos sequenciais em vez de um plano enorme. Conclua a extração de auth em seu próprio plano, depois inicie uma sessão nova e um plano para dividir as rotas. 

Use /rename para nomear cada sessão (por exemplo, "blog-api-auth-extraction") e poder retomar de onde parou com /resume. Planos menores mantêm a janela de contexto focada e dão um checkpoint natural entre fases.

Estratégias práticas para o Plan Mode do Claude Code

Agora que percorremos todo o processo uma vez, veja algumas boas práticas para tirar o máximo do Plan Mode.

Quando usar o Plan Mode (e quando pular)

Nem toda tarefa precisa de plano. Ajustes de uma linha, correções de typo e atualizações isoladas de função são mais rápidas sem a sobrecarga de planejamento. O mesmo vale para mudanças mecânicas, como renomear uma variável no arquivo todo.

Uma boa heurística: se a mudança toca três ou mais arquivos, ou se você não consegue descrever a mudança completa em uma única frase, planeje primeiro. Três arquivos é mais ou menos onde os erros compostos começam a morder, porque cada arquivo adiciona seu próprio conjunto de decisões que o Claude precisa acertar.

Tarefas que sempre se beneficiam do Plan Mode:

• Refatorações que movem código entre arquivos ou renomeiam interfaces compartilhadas
• Novos recursos que tocam módulos existentes
• Upgrades de dependências com mudanças quebrando APIs
• Qualquer tarefa em que você não tem certeza de como o codebase trata um caso específico
• Sessões de brainstorming em que você quer iterar na abordagem com o Claude sem risco de edições prematuras

Como detectar planos fracos antes que saiam caro

Um plano com cara de estruturado nem sempre é bom. Com as versões atuais do Claude Code, referências de arquivos alucinadas e passos vagos do tipo "atualize conforme necessário" são raros. O problema mais provável é um plano que coloca todas as etapas de implementação primeiro e deixa "adicionar testes" para o fim.

Planos estruturados assim geram resultados piores do que você espera. Sem testes durante a implementação, o Claude não tem como verificar o próprio trabalho no meio da sessão. Na refatoração da API de blog, um plano que diz "Passos 1–6: extrair todos os módulos, Passo 7: escrever testes" significa seis passos de código sem loop de feedback. 

Um plano mais forte usa TDD (test-driven development) e intercala testes com implementação: escreva testes para auth/ antes de extrair as funções de auth, confirme que passam, depois escreva testes para posts/ antes de puxar as rotas. Cada teste que passa dá ao Claude um sinal claro de que a refatoração está no trilho. 

Adicionar convenções de TDD ao seu CLAUDE.md faz o Claude incluir passos de teste por padrão. Os Claude Code Hooks podem automatizar esse tipo de enforcement rodando scripts de validação que checam a qualidade do plano antes de aprovar a execução.

Escalando grandes refatorações com Agent Teams

Planos que tocam sete ou mais arquivos começam a perder qualidade porque a janela de contexto enche durante a execução. A refatoração da API de blog bate nesse limite quando você conta rotas, modelos, serviços, config, testes e uma nova estrutura de diretórios.

Agent Teams é um recurso experimental que distribui esse tipo de trabalho entre várias instâncias do Claude Code. Uma sessão atua como líder do time enquanto colegas têm suas próprias janelas de contexto independentes. 

Para a API de blog, você pode dividir em três colegas: um cuidando da extração de rotas, um da camada de banco/modelos e um responsável pela cobertura de testes. O líder atribui tarefas, os colegas assumem e concluem, e tarefas bloqueadas (como "atualizar imports" dependendo de "extrair módulos") são desbloqueadas automaticamente quando as dependências terminam. 

A mesma divisão funciona entre repositórios: se sua API depende de uma biblioteca compartilhada, um colega pode refatorar a biblioteca enquanto outro atualiza o consumo na API.

A melhor configuração para o Plan Mode é exigir aprovação de plano para os colegas. Diga ao líder: "Crie três colegas para a refatoração da API de blog. Exija aprovação de plano antes de qualquer mudança." 

1. Cada colega planeja em modo somente leitura
2. O líder revisa e aprova ou rejeita com feedback
3. Somente planos aprovados são executados

Você pode orientar o julgamento do líder dando critérios: "aprove apenas planos que incluam cobertura de testes" ou "rejeite planos que modifiquem o schema do banco diretamente". Ative o Agent Teams adicionando "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1" ao bloco env do seu settings.json.

Para paralelização mais simples sem a flag experimental, git worktrees permitem rodar sessões separadas do Plan Mode em branches diferentes, cada uma trabalhando em seu próprio plano de forma independente.

Se uma sessão longa passar por compactação de contexto, peça explicitamente que os colegas reabram e releiam seus arquivos de plano para evitar desvio.

O tutorial de plugins do Claude Code cobre padrões adicionais para gerenciar trabalhos em múltiplas fases.

Conclusão

O valor do Plan Mode se resume a uma coisa: revisar antes de executar. Cada rodada de anotações que você adiciona, cada pergunta que o Claude faz em vez de chutar, remove uma decisão que provavelmente sairia errada. 

Comece na sua próxima mudança multi-arquivo: obrigue o Claude a planejar primeiro e edite esse plano com Ctrl+G antes de conceder acesso de escrita. Para configuração do CLAUDE.md, gestão de contexto e guardrails baseados em hooks, o tutorial de boas práticas dá sequência a este conteúdo. 

Para uma visão mais ampla de código assistido por IA, recomendo conhecer nossa trilha de habilidades AI for Software Engineering, que ensina os conceitos fundamentais e dá prática com ferramentas similares como GitHub Copilot, Windsurf e Replit.