Planejamento de Projetos com Claude Code: Plan Mode & ak plan (2026)

Por que planejar antes de deixar o Claude Code escrever código?

O erro mais comum com o Claude Code é digitar um prompt e deixar que ele saia codando na hora. Parece rápido, mas o risco é real: a IA muitas vezes "resolve o problema errado" - ela faz exatamente o que acha que você quer, não o que você de fato precisa. Quando você olha o diff, uma dúzia de arquivos já mudou, e agora você fica preso entre corrigir tudo na mão ou jogar fora e começar de novo.

Planejar primeiro resolve justamente isso. Quando você força o Claude a montar um plano antes de tocar em qualquer código, você consegue prever o escopo da mudança, pegar mal-entendidos enquanto ainda são baratos e manter o trabalho dentro dos limites. De bônus: economiza tokens, porque editar uma linha de um plano é muito mais barato do que deixar a IA escrever a coisa errada e reescrevê-la.

Tem um benefício que quase ninguém menciona: o plano é onde você e a IA concordam sobre a "definição de pronto". Quando o plano diz quais arquivos vão mudar e como verificá-los, você tem uma referência para conferir o diff final - em vez de ler o código e ficar se perguntando "será que fez mesmo o que eu quis?". Em outras palavras, planejar transforma a revisão de adivinhação em comparação com checklist.

Quando você DEVE planejar: a mudança toca em muitos arquivos; você não tem certeza de como abordar; ou você está trabalhando em uma base de código desconhecida cujo fluxo você ainda não domina. Quando pular por velocidade: corrigir um erro de digitação, mudar uma constante, ajustar uma única linha - se você consegue descrever o diff em exatamente uma frase, planejar é só custo extra. Se você é totalmente novo na ferramenta, leia antes o que é o Claude Code e como ele funciona e depois volte para as seções abaixo.

O que é o plan mode no Claude Code & como ativá-lo

O plan mode é um modo de permissão do Claude Code: quando está ligado, o Claude apenas lê arquivos e propõe um plano, sem gravar nenhuma mudança no disco até você aprovar. Pense nele como um freio de segurança que deixa você ver o que a IA pretende fazer antes de permitir.

Há três formas de ativá-lo:

1. Pressione Shift+Tab para alternar entre os modos: default → acceptEdits → plan. Continue pressionando até parar em plan.
2. Inicie direto no plan mode a partir do terminal:

   claude --permission-mode plan

3. Confirme na barra de status - quando o plan mode está ativo, a barra de status mostra ⏸ plan mode on.

Uma dica pouco conhecida: assim que o Claude produzir um plano, pressione Ctrl+G para abrir esse plano em um editor de texto e editá-lo na mão antes de rodar - adicione restrições, remova passos desnecessários ou aponte para arquivos específicos. Editar um plano é sempre mais barato do que editar código que já foi escrito.

O comportamento dos atalhos acima segue a documentação oficial da Anthropic (best practices e common workflows, consultada em 2026-08-09). Como o plan mode evolui rápido, confira novamente os atalhos na versão do Claude Code que você está usando.

O loop de planejamento em 4 passos: Explore → Plan → Implement → Commit

Este é o loop que a Anthropic recomenda, e é o mais fácil de lembrar. Cada passo tem seu próprio objetivo - não os misture.

Explore (no plan mode)

Antes de discutir qualquer solução, deixe o Claude ler e entender o código existente. No plan mode ele só lê, nunca edita, então você pode deixá-lo fuçar à vontade:

Read src/payments/ and src/orders/ to understand how the system handles payments today. No proposals yet - just summarize the flow.

Para projetos grandes, passe a pesquisa para um subagent a fim de manter limpo o contexto da sessão principal - o subagent lê e devolve um resumo, enquanto a sua janela de contexto principal não fica entupida com milhares de linhas. O objetivo deste passo não é a solução; é fazer o Claude descrever, com as próprias palavras, como o sistema funciona hoje. Se o resumo estiver errado, você já sabe na hora que ele não entendeu o problema.

Plan

Quando o Claude entender o código, peça um plano concreto:

I want to add discount codes to orders. Which files need to change? How does the flow work? Write a detailed plan before coding.

Leia o plano com atenção. Se algo estiver errado, pressione Ctrl+G para editá-lo na mão, ou responda para que o Claude o revise. Não se apresse em aprovar.

Implement

Aprove o plano (ou pressione Shift+Tab para sair do plan mode) para que o Claude comece a codar. O ponto-chave: ancore o plano com critérios de verificação - diga exatamente o que a IA precisa fazer para provar que terminou:

Execute the plan. When finished, run npm test and make sure every test passes. If any test fails, fix it until it is green.

Commit

Por fim, feche tudo em um commit limpo e abra um PR:

Commit the changes with a clear descriptive message, then open a pull request with a summary of what changed.

Veja também o nosso fluxo de trabalho com Git & criação de PRs com o Claude Code para padronizar este passo.

Divida um projeto grande em fases & um roadmap

O loop de 4 passos acima funciona bem para uma funcionalidade autocontida. Mas um projeto que roda por dias ou semanas quebra um plano plano: o contexto se dilui, o Claude esquece decisões anteriores e você perde o controle.

A abordagem mais duradoura: peça ao Claude para montar um roadmap de várias fases, em que cada fase deixe claro seu objetivo, os arquivos que vai tocar e seus critérios de "pronto". Salve o roadmap em um arquivo (por exemplo PLAN.md ou uma pasta plans/) para que ele não suma quando você rodar /clear. Depois execute cada fase em sua própria sessão, com um contexto limpo - rode /clear entre as fases para que cada uma comece enxuta, carregando só a fatia do roadmap de que precisa.

O princípio para dividir as fases: cada fase deve se sustentar sozinha e terminar em um estado verde (testes passam, app roda), para que você possa parar em qualquer ponto sem deixar código pela metade. A ordem das fases deve ir da fundação para fora - construa primeiro o backend/lógica, a interface depois - para que toda fase seguinte tenha chão firme sobre o qual construir.

Exemplo de roadmap para uma funcionalidade de "Entrar com o Google (OAuth)":

Para funcionalidades complexas, use o padrão interview → SPEC.md → nova sessão: diga ao Claude para "me entrevistar uma pergunta de cada vez sobre os requisitos e depois escrever tudo em SPEC.md", e então abra uma sessão nova que lê o SPEC e executa com um contexto limpo. Essa é a essência do desenvolvimento orientado a especificação (escreva o SPEC.md primeiro), e se alinha com o fluxo brainstorm → plan → cook → ship que muitos devs na ativa já usam.

Dicas para planos de mais qualidade

• Ancore com critérios de verificação. Um bom plano sempre inclui como conferi-lo: quais testes precisam passar, o build precisa rodar, o screenshot precisa bater. Você também pode definir uma condição com /goal para que a IA se avalie após cada passo em vez de declarar "pronto" quando não está. Em outras palavras, critérios de aceite claros tornam o /goal seguro de rodar.
• Escreva um CLAUDE.md. Registre as convenções do seu projeto (estrutura de pastas, regras de nomenclatura, comandos de teste) em um arquivo CLAUDE.md, para que todo plano permaneça no contexto certo sem você repetir isso toda vez.
• Seja específico nos prompts. Aponte os arquivos exatos, cite um padrão de exemplo a seguir e diga o que está fora do escopo. Quanto mais específico você for, mais perto o plano chega.
• Use um subagent para revisar o plano. Peça a um subagent com contexto novo para dar uma olhada no plano ou no diff - uma perspectiva "limpa" costuma pegar falhas para as quais a sessão principal já ficou cega.
• Use /rewind. Se uma direção de planejamento não está funcionando, rebobine e tente outra abordagem em vez de ficar remendando por cima.

Uma comparação rápida lado a lado para ver a diferença:

Prompt fraco: "Adicione login com Google ao app."

Prompt forte: "Leia src/auth/ e src/routes/. Quero adicionar login com Google (OAuth) seguindo exatamente o padrão de sessão que já existe em src/auth/session.ts. Fora do escopo: sem refresh token por enquanto. Escreva um plano: quais arquivos mudam, como funciona o fluxo de callback e os critérios de verificação (auth.spec.ts passa)."

ak plan - uma skill de planejamento pronta (AgentKit)

Um aviso rápido para evitar confusão: o AgentKit aqui é um kit para o Claude Code (agentkit.best, usando a CLI ak), que é completamente diferente do "OpenAI AgentKit".

Se você se pega "pedindo um plano por prompt" toda vez que começa uma funcionalidade, existe uma skill que empacota esse processo para você: a ak-plan. Em vez de escrever o prompt você mesma, você chama a skill e ela gera um plano de várias fases com um roadmap em um framework consistente, com suporte a --html (um artifact autocontido que você pode ver/compartilhar) e --wiki (publicar no AgentWiki). Essa skill fica no Engineer Kit - um pacote de $99 (o site não lista mensalidade) com mais de 60 skills e mais de 30 workflows. Se você quiser experimentar agora mesmo, pode ativar a CLI ak (20% de desconto pelo link) e instalar o kit por lá.

Sendo sincera: para a maior parte do trabalho, o plan mode nativo já basta, e é grátis - você não precisa de um kit para planejar bem. O ak plan vale a pena quando você precisa de planos padronizados, repetíveis e documentados (artifact/wiki) para um time inteiro, e não como pré-requisito para começar.

Erros comuns ao planejar com IA

• Planejar algo pequeno demais. Ligar o plan mode para mudar uma linha só perde tempo. Se você consegue descrever o diff em uma frase, deixe rodar.
• Um plano longo sem âncora de verificação. Um plano de uma dúzia de passos soa impressionante, mas sem critérios de checagem a IA facilmente "parece pronta" enquanto nada de fato roda. Anexe sempre condições de teste/build/claras.
• Empilhar muitas tarefas em uma sessão. Fazer três funcionalidades sem relação na mesma janela de contexto confunde a IA. Rode /clear entre as tarefas para manter o contexto enxuto.
• Confiar no plano e pular o diff. Um plano correto não garante código correto. Você ainda tem que ler o diff de verdade antes de commitar.

Perguntas frequentes (FAQ)

O plan mode custa a mais?

Não. O plan mode é um modo embutido no Claude Code, não um add-on pago. Você o usa dentro do seu plano atual (por exemplo, Pro a $20/mês ou Max 5x a $100/mês).

Qual tecla ativa o plan mode?

Pressione Shift+Tab para alternar default → acceptEdits → plan e pare em plan. Ou inicie com claude --permission-mode plan. A barra de status vai mostrar ⏸ plan mode on.

O plan mode edita arquivos sozinho?

Não. No plan mode, o Claude apenas lê arquivos e propõe um plano; ele não grava mudanças no disco até você aprovar. Esse é o recurso de segurança central do modo.

Como o plan mode se diferencia do extended thinking (think/ultrathink)?

São coisas diferentes. O plan mode é um modo de permissão - ele controla se a IA pode editar arquivos. O extended thinking (think/ultrathink) aumenta a profundidade de raciocínio do modelo. Você pode usar os dois juntos: ligue o plan mode por segurança e peça um raciocínio mais profundo quando o problema for complexo.

O ak plan é obrigatório, e como ele difere do plan mode nativo?

Não é obrigatório. O plan mode nativo basta na maioria dos casos e é grátis. O ak plan é uma skill pronta (no Engineer Kit do AgentKit) que gera planos padronizados de várias fases com artifacts --html/--wiki - útil quando você precisa repetir o processo e ter documentação para um time.

Como devo dividir um projeto grande?

Peça ao Claude para montar um roadmap de várias fases (cada fase com objetivo, arquivos tocados e critérios de pronto), salve em PLAN.md, depois execute cada fase em sua própria sessão e rode /clear entre as fases para manter o contexto limpo.

Conclusão + próximos passos

Resumo: não deixe o Claude Code codar de cara - vá de Explore → Plan → Implement → Commit, ligue o plan mode com Shift+Tab para pré-visualizar antes de aprovar e divida projetos grandes em fases com um contexto limpo. Em seguida, leia o fluxo brainstorm → plan → cook → ship para um framework de trabalho completo, e o desenvolvimento orientado a especificação quando você precisar de um plano rigoroso para uma funcionalidade grande.