Pular para o conteudo
Voltar aos artigos
claude-codeplan-modecontext-engineeringplanejamentoboas-praticas

Por que seu Claude Code não entrega (e não é culpa dele): o poder do plan mode

Claude Code está decepcionando você? Antes de trocar de ferramenta, entenda por que o plan mode, o CLAUDE.md e a quebra em microtarefas separam quem trava de quem entrega.

12 min de leitura

Por que seu Claude Code não entrega (e não é culpa dele): o poder do plan mode

Antes de trocar de ferramenta, vale conferir o que a maioria dos usuários pula: o passo de planejar antes de pedir pra codar.

O problema não é o Claude

Tem um padrão claro em fóruns como r/ClaudeAI: alguém diz que Claude Code é ótimo, outra pessoa responde que "o meu não entrega nada parecido". Mesmo modelo, mesma ferramenta, resultados opostos. Por quê?

Na maioria dos casos, não é o Claude. É o pedido.

Quem trava descreve o app inteiro em uma mensagem e espera um resultado pronto. Quem entrega faz algo diferente antes: planeja. Quebra em etapas. Escreve o que quer antes de pedir pra codar.

O padrão recorrente nos fóruns de quem usa a ferramenta a sério é direto: o gargalo não é "saber programar", é saber quebrar o problema em pedaços pequenos o suficiente para o Claude executar cada um com sucesso. Um botão, uma função, uma tela por vez, em vez do app inteiro de uma vez.

Este artigo mostra por que isso acontece, o que é o plan mode do Claude Code, e como um CLAUDE.md bem escrito resolve 80% do problema sem precisar mudar de ferramenta.

O erro mais comum: pedir o app inteiro de uma vez

O instinto natural é tratar a IA como um desenvolvedor contratado. Você manda um briefing grande, volta duas horas depois, vê o resultado.

Não funciona assim. Modelos de linguagem têm uma janela de contexto finita e, segundo a própria Anthropic, "a performance do LLM degrada à medida que o contexto enche". Quando o contexto está cheio, o Claude começa a "esquecer" instruções anteriores e cometer mais erros. Toda janela ocupada com exploração de código, tentativas anteriores e arquivos irrelevantes é janela que falta pra implementar direito.

Pedido gigante gera duas dores ao mesmo tempo: muito código novo de uma vez (difícil de revisar) e um contexto poluído com tudo que precisou ser lido pra chegar lá. Ficou mais fácil arrumar tudo do zero do que corrigir.

O que funciona: separar três fases. Explorar, planejar, implementar. Cada uma com um objetivo específico.

O que é plan mode (e como ele funciona)

Plan mode é um modo de permissão nativo do Claude Code. A descrição oficial:

"Plan Mode instructs Claude to create a plan by analyzing the codebase with read-only operations, perfect for exploring codebases, planning complex changes, or reviewing code safely."

Docs Claude Code, seção "Use Plan Mode for safe code analysis".

Traduzindo o que isso significa na prática:

  • Operações read-only. No plan mode, o Claude não escreve nem executa comandos destrutivos. Ele lê arquivos, analisa, e produz um plano detalhado.
  • Ferramenta de perguntas. Ele usa o AskUserQuestion pra esclarecer requisitos antes de propor o plano. Ou seja: ele interroga você, não o contrário.
  • Plano editável. Quando o plano aparece, Ctrl+G abre ele no seu editor de texto padrão pra você revisar e ajustar antes de aceitar.

Como ativar o plan mode

A documentação oficial descreve três formas:

1. Durante uma sessão ativa. Pressione Shift+Tab pra circular entre os modos de permissão. Em modo normal, Shift+Tab primeiro entra em "Auto-Accept Mode" (indicador ⏵⏵ accept edits on no rodapé). Um segundo Shift+Tab entra no plan mode (indicador ⏸ plan mode on).

2. Iniciando uma nova sessão direto em plan mode. Use a flag --permission-mode plan:

claude --permission-mode plan

3. Em modo headless (queries não-interativas). Combine -p com a mesma flag:

claude --permission-mode plan -p "Analyze the authentication system and suggest improvements"

Configurando como padrão do projeto

Se o seu fluxo envolve quase sempre planejar antes de executar, dá pra fixar isso em .claude/settings.json:

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

A flag --permission-mode sobrescreve o defaultMode do settings quando você precisar.

Por que planejar antes de codar muda tudo

Três razões técnicas, não místicas.

Contexto fica limpo. Na fase de exploração você consome contexto lendo código. Mas o plano final é curto: poucos parágrafos que cabem em pouco espaço. Ao aceitar o plano e sair do plan mode, você entra na implementação com a "resposta" já destilada, sem carregar todo o rascunho de como chegou nela.

Decisões ruins aparecem antes do código ruim. Um plano escrito expõe escolhas: "vou usar OAuth2 com refresh tokens e armazenar no cookie httpOnly". Você vê a decisão antes de virarem 400 linhas de código pra desfazer.

Subtarefas viram unidades de revisão. Com um plano de 6 passos, cada passo tem um "feito" claro. Sem plano, você só sabe se funcionou quando tenta usar.

A própria Anthropic recomenda o fluxo em quatro fases no guia de boas práticas: explorar → planejar → implementar → commitar. Em plan mode você explora e planeja. Em modo normal você implementa e commita.

"Planning is most useful when you're uncertain about the approach, when the change modifies multiple files, or when you're unfamiliar with the code being modified. If you could describe the diff in one sentence, skip the plan."

Anthropic, Best Practices for Claude Code.

Nem tudo precisa de plano. Trocar uma string, arrumar um log, renomear variável: pede direto. Mas pra tudo que envolve mais de um arquivo ou abordagem incerta, planejar custa menos do que refazer.

O PRD como ponto de partida (não como formalidade)

A recomendação mais repetida pelos não-programadores que conseguiram entregar apps reais é contra-intuitiva: antes de pedir código, peça um PRD.

PRD = Product Requirements Document. Um documento curto que responde:

  • O que esse app faz?
  • Quem vai usar?
  • Qual o MVP (funcionalidades mínimas pra valer a pena)?
  • Quais fluxos de usuário existem?
  • Que dados precisam ser armazenados?

O próprio Claude consegue escrever isso pra você. No plan mode, peça algo como: "quero construir X. Me entreviste em detalhes usando o AskUserQuestion. Pergunte sobre implementação técnica, UI/UX, edge cases, tradeoffs. Não faça perguntas óbvias. Quando terminarmos, escreva o spec completo em SPEC.md."

A Anthropic documenta exatamente esse padrão como "Let Claude interview you". A lógica: uma sessão nova, começando com o SPEC.md em mãos, tem contexto limpo focado só na implementação. Você não precisa reexplicar nada.

Isso não é formalidade corporativa. É compressão. Em vez de explicar o app toda vez, você escreveu uma vez e referencia quando precisa.

CLAUDE.md: a memória de longo prazo que o leitor ignora

Se o plan mode resolve "o que fazer agora", o CLAUDE.md resolve "o que o Claude sempre precisa saber sobre este projeto".

Direto da documentação:

"CLAUDE.md is a special file that Claude reads at the start of every conversation. Include Bash commands, code style, and workflow rules. This gives Claude persistent context it can't infer from code alone."

Anthropic, Best Practices for Claude Code.

Na prática:

  • O arquivo fica na raiz do projeto.
  • É lido automaticamente no início de toda sessão.
  • Commitado no git, vira memória compartilhada com o time (ou com você mesmo no futuro).
  • Aceita imports de outros arquivos via @path/to/file quando ficar longo demais.

O que colocar nele:

  • Comandos bash que o Claude não consegue adivinhar (ex: pnpm dev:studio em vez do esperado npm start).
  • Regras de estilo que fogem dos defaults (ex: "nunca use any em TypeScript, use unknown").
  • Convenções de commit e branch do seu time.
  • Env vars obrigatórias e como validar.
  • Gotchas específicos do projeto.

O que não colocar:

  • Qualquer coisa que o Claude já sabe por convenção de linguagem ou framework.
  • Descrição arquivo por arquivo da codebase.
  • Longas explicações ou tutoriais.
  • Conselhos genéricos tipo "escreva código limpo".

A regra de ouro da Anthropic: pra cada linha no CLAUDE.md, pergunte "se eu remover, o Claude erraria?". Se não, corta. Arquivo inchado faz o Claude ignorar as regras importantes porque elas se perdem no ruído.

Microtarefas vs tarefas macro

Voltando ao insight do comentário top do Reddit: "break your project into microscopic pieces". Não é exagero retórico.

O modo antigo: "crie um app de gestão pra minha clínica odontológica com agenda, prontuário, cobrança e integração com WhatsApp".

O modo que funciona: pegue esse plano, quebre em etapas individuais, e peça uma de cada vez.

  • Iteração 1: setup inicial do Next.js e Prisma com modelo Patient.
  • Iteração 2: tela de cadastro de paciente com validação.
  • Iteração 3: listagem paginada de pacientes.
  • Iteração 4: modelo Appointment ligado a Patient.
  • Iteração 5: calendário de agendamento.

Cada iteração cabe numa sessão curta. Cada iteração tem critério claro de pronto. Se der errado, você volta só aquela iteração, não o projeto inteiro.

O plan mode serve exatamente pra sair de "app inteiro" pra essa lista. Você descreve o todo uma vez, o Claude entrevista você, gera o plano, e você usa o plano como sua própria lista de tarefas.

Exemplo didático: prompt ruim vs prompt bom

Os dois exemplos abaixo tratam o mesmo objetivo. Um costuma travar. O outro costuma entregar. Copie o padrão, não os detalhes.

Prompt ruim (one-shot, descrição vaga):

Cria um sistema de gestão de agenda pra consultório com cadastro de paciente,
agendamento, lembretes por WhatsApp, relatório mensal e login. Usa Next.js,
Prisma e PostgreSQL. Estiliza bonito.

O que acontece: o Claude tenta tudo de uma vez, o contexto enche com decisões parciais, a autenticação fica meio feita, o banco não tem migrations organizadas, o front está sem validação. No final, tem código demais pra revisar e pouca coisa realmente pronta.

Prompt bom (plan mode + microtarefa):

claude --permission-mode plan

Quero construir um sistema de gestão de consultório (Next.js + Prisma +
PostgreSQL). Me entreviste com o AskUserQuestion pra gerar um SPEC.md com:
modelos de dados, fluxos de usuário, MVP, stack exata, requisitos de auth.
Não implemente nada. Só planeje.

Depois, em sessão nova (modo normal):

Use o SPEC.md deste projeto. Implemente apenas a Iteração 1: setup do
Next.js 16 com App Router, Prisma configurado com PostgreSQL local, modelo
Patient com campos nome, cpf, telefone, data_nascimento. Adicione migration
inicial e uma página /patients/new com formulário que cria paciente.
Valide com Zod. Rode os checks ao final (tsc --noEmit, eslint).

Repare: o segundo prompt tem escopo fechado, critérios de verificação (checks no final) e referência a um contexto externo (SPEC.md). É muito código também, mas é muito código que faz uma coisa e pode ser revisado em poucos minutos.

Na Prática

Passo a passo para entrar em plan mode hoje:

1. Abra o Claude Code na raiz do seu projeto

cd /caminho/do/projeto
claude

2. Entre em plan mode

Pressione Shift+Tab duas vezes até aparecer ⏸ plan mode on no rodapé do terminal. (Se quiser começar já no modo, saia e rode claude --permission-mode plan.)

3. Peça um plano, não uma implementação

Exemplo de prompt inicial:

Estou planejando [descrição curta da feature]. Me entreviste usando
AskUserQuestion sobre implementação, edge cases e tradeoffs. Não implemente
nada. Quando terminar, escreva o plano em PLAN.md.

4. Revise o plano com Ctrl+G

Quando o plano aparecer, Ctrl+G abre no seu editor de texto. Edite livremente. O plano é seu documento, não do Claude.

5. Saia do plan mode e implemente uma etapa por vez

Saia do plan mode (Shift+Tab até voltar a "default mode" ou a "accept edits on") e peça uma iteração por vez, referenciando o plano salvo:

Implemente a Iteração 1 de @PLAN.md. Rode os checks do projeto ao final.

Dica: se você se pega corrigindo o Claude mais de duas vezes na mesma coisa, rode /clear pra resetar o contexto. Sessão nova com prompt melhor quase sempre ganha de sessão longa com correções acumuladas.

Conclusão: a diferença entre quem trava e quem entrega

Voltando à pergunta inicial: por que duas pessoas com a mesma ferramenta têm resultados tão diferentes?

Quem trava:

  • Descreve o app inteiro de uma vez.
  • Pede código direto, sem plano.
  • Não mantém um CLAUDE.md.
  • Corrige sintoma em vez de causa.
  • Deixa o contexto encher de tentativas frustradas.

Quem entrega:

  • Explora, planeja, implementa em fases separadas.
  • Usa plan mode pra interrogar o próprio projeto.
  • Tem um CLAUDE.md curto e afiado.
  • Quebra o projeto em microtarefas.
  • Roda /clear entre assuntos diferentes.

A ferramenta é a mesma. O método é o diferencial. E o método não está escondido: está nos docs oficiais, nos comentários dos usuários mais experientes, e agora neste artigo.

Troque a ordem das operações antes de trocar de ferramenta.

Referências

Por onde continuar

Plan mode, CLAUDE.md e engenharia de contexto são três dos 13 pilares cobertos no Curso Claude Code: Criador de Apps. O curso leva você do setup completo ao app publicado, com módulos dedicados a Como o Claude Code Pensa, Engenharia de Prompts, Contexto e o CLAUDE.md Perfeito, Turbine Seu Claude Code (plugins, commands, skills, MCP, hooks, subagents) e Workflow Profissional. Acesso vitalício a partir de 12× R$39 (R$468 à vista), inclui o Claude Code Guide de bônus e tem garantia incondicional de 7 dias.