# Plan Mode no Claude Code: guia passo a passo e 4 fases em 2026 > Plan Mode no Claude Code: o que é, como ativá-lo com Shift+Tab, as 4 fases da Anthropic, modelos de prompts prontos a usar e o comando /goal para tarefas autónomas durante a noite. Source: https://ailoot.ai/blog/pt-pt/claude-code-plan-mode/ Canonical: https://ailoot.ai/blog/pt-pt/claude-code-plan-mode/ Language: pt-PT Publisher: Ailoot (https://ailoot.ai/) Translation: guide-197 Revision: sha256-91e00efd1eb20c56ceddf8d884866790410a26c4dc1c6655ed03bbfd09097087 As instruções adicionais estão na [documentação da Ailoot](https://ailoot.ai/docs/). ## O que é o Plan Mode e porque não é suficiente por si só?
Pontos-chave O Plan Mode no Claude Code é um modo em que a IA lê ficheiros, analisa código e propõe um plano de alterações, mas não escreve nada até o aprovar. É ativado ao premir Shift+Tab duas vezes ou através da opção `--permission-mode plan`. É útil quando a abordagem é incerta, o código é desconhecido ou a alteração tem risco significativo entre ficheiros ou na operação. Uma correção clara e de baixo risco de um erro de escrita costuma dispensar planeamento separado.
No modo normal, o Claude Code escreve código imediatamente e, se não estiver atento, pode obter um diff em muitos ficheiros sem perceber de onde veio. O Plan Mode inverte a sequência: primeiro pesquisa e planeamento, depois aprovação e, por fim, alterações. A Anthropic descreve o Plan Mode na documentação oficial da seguinte forma:

O modo plan diz a Claude para pesquisar e propor alterações sem as fazer. Claude lê ficheiros, executa comandos shell para explorar e escreve um plano, mas não edita o seu código.

— Anthropic Docs, https://code.claude.com/docs/en/permission-modes
Parece simples, mas esconde a principal mudança. O Plan Mode altera o ritmo do trabalho: primeiro acordar, depois agir. É uma mudança de modo, não um ajuste cosmético. O problema para quem pratica vibe coding é que os agentes de IA tendem a precipitar-se. Se pedir «Adiciona autenticação Google», no modo normal o Claude escreverá o código num minuto, mas metade dos ficheiros estará errada. No Plan Mode, o mesmo pedido transforma-se num plano em texto que pode ler em dois minutos e corrigir antes de se tocar em qualquer código. Eis uma armadilha de que ninguém fala nos guias internacionais. Por si só, o Plan Mode é uma ferramenta fraca: o plano só existe na conversa atual. Feche a janela e o plano perde-se. Não pode passá-lo a outro agente. Não há versões nem histórico. Se a tarefa for grande (refatorizar um módulo com 30 ficheiros, migrar para uma nova base de dados), o plano depressa atingirá o limite da janela de contexto e começará a degradar-se. É por isso que o Plan Mode funciona bem em conjunto com uma pasta `plans/` no repositório. O plano é guardado como `plans/2026-05-21-google-oauth.md`, dividido em fases com caixas de verificação, e qualquer agente seguinte pode retomá-lo. É assim que funciona a [context engineering](https://ailoot.ai/blog/pt-pt/context-engineering/) — gerir o contexto antes do prompt, não durante. ## Como ativar o Plan Mode no Claude Code?
Pontos-chave Há quatro formas oficiais de ativar o Plan Mode. Durante uma sessão, prima Shift+Tab duas vezes ou coloque o prefixo `/plan` antes de um prompt. Ao iniciar, use a opção `claude --permission-mode plan`. Globalmente, defina o campo `defaultMode` em `.claude/settings.json`. O indicador de modo ativo é `⏸ plan mode on` na parte inferior do terminal.
A forma mais rápida durante uma sessão é através do teclado: ``` Shift+Tab # alterna entre modos: predefinido → acceptEdits → plan ``` Depois de premir duas vezes, o indicador `⏸ plan mode on` aparece na parte inferior do terminal. Uma terceira pressão regressa ao modo normal. É o método mais prático: muda de modo em qualquer altura quando percebe que a tarefa está a crescer. O segundo método é adicionar um prefixo antes de um único prompt: ``` /plan escreve um plano para migrar a base de dados de MySQL para Postgres ``` Esta opção é útil quando está no modo de aceitação automática e não quer alterá-lo durante toda a sessão. Um pedido em Plan Mode e, depois, o trabalho continua como antes. O terceiro método é ao iniciar a sessão: ```bash claude --permission-mode plan ``` Use-o quando souber antecipadamente que uma tarefa exige planeamento. Por exemplo, antes de uma grande refatoração ou migração. O quarto método consiste em definir o modo predefinido em `.claude/settings.json` no projeto: ```json { "permissions": { "defaultMode": "plan" } } ``` Quando é útil? Quando uma equipa trabalha num sistema complexo em que qualquer alteração pode afetar módulos adjacentes. Nesse caso, o Plan Mode predefinido protege todos contra alterações acidentais. Há ainda um quinto truque que muitas vezes passa despercebido: `Ctrl+G` abre o plano num editor de texto. Use-o quando o plano estiver quase certo, mas precisar de reformular 2-3 pontos ou acrescentar uma restrição. Edite-o manualmente, guarde e Claude continuará com a sua versão. ## Quais são as 4 fases canónicas do Plan Mode da Anthropic: Explore, Plan, Implement, Commit?
Pontos-chave Nas suas boas práticas, a Anthropic apresenta um fluxo de trabalho canónico com quatro fases: Explore (ler ficheiros e explorar o contexto), Plan (criar um plano de alterações sem editar), Implement (mudar para o modo normal e implementar de acordo com o plano) e Commit (criar um commit com uma mensagem descritiva e um PR). Cada fase tem as suas próprias restrições de ferramentas.
Muitos guias descrevem 3 fases (Explore-Plan-Execute) ou apenas 2 (Plan-Implement). São simplificações. No seu [guia oficial de boas práticas](https://www.anthropic.com/engineering/claude-code-best-practices), a Anthropic descreve exatamente 4 fases. A diferença é importante: separar Commit como uma fase leva-o a registar o resultado, em vez de ficar por «fiz mais alguns ajustes, faço commit mais tarde» — a causa mais comum de trabalho perdido. Quanto mais preciso for o plano, menos iterações serão necessárias para a implementação. Se passar 10 minutos no plano, a implementação demora um prompt. Se esboçar o plano num minuto, a implementação vai demorar uma hora de correções. Eis o aspeto das 4 fases ao adicionar Google OAuth (um exemplo da documentação da Anthropic): | Fase | O que Claude faz | O que faz | Modo | |----|----|----|----| | **Explore** | Lê `/src/auth` e procura perceber como são tratadas as sessões e as variáveis de ambiente | Define o âmbito da exploração | Plan Mode | | **Plan** | Cria um plano: que ficheiros alterar, quais criar e que riscos existem | Lê o plano, edita-o com Ctrl+G e aprova-o | Plan Mode | | **Implement** | Implementa de acordo com o plano e escreve o código do fluxo OAuth, os testes e o callback | Acompanha cada alteração à medida que é aplicada | Default ou acceptEdits | | **Commit** | Cria um commit com uma descrição e abre um Pull Request | Verifica a mensagem e revê o PR | Default | Os prompts também são diferentes em cada fase. Em Explore: «lê /src/auth e percebe como tratamos as sessões e o início de sessão». Em Plan: «Quero adicionar Google OAuth. Que ficheiros têm de mudar? Cria um plano». Em Implement: «implementa o fluxo OAuth do teu plano, escreve testes, executa a suite e corrige as falhas». Em Commit: «faz commit com uma mensagem descritiva e abre um PR». Uma nuance importante: o Plan Mode não impede Claude de executar comandos para pesquisa. Read, LS, Glob, Grep, web fetch e comandos shell de exploração são permitidos. Apenas Edit, Write e quaisquer operações de alteração do sistema de ficheiros são proibidos. Isto significa que Claude pode ler a estrutura do projeto, executar `git log` e consultar testes, mas não poderá alterar nada acidentalmente. ## Como ler o plano de Claude e decidir se o deve aprovar?
Pontos-chave Um bom plano de Claude contém uma lista de ficheiros específicos e das alterações a fazer, uma sequência ordenada de passos, riscos explícitos e critérios de sucesso. Um mau plano usa frases genéricas como «vou atualizar o módulo auth», sem especificar detalhes. Use os 7 sinais abaixo para decidir se o aprova. Aperfeiçoe-o com feedback ou edite-o diretamente com Ctrl+G.
Quando Claude termina de criar um plano, apresenta opções para o passo seguinte: - Aprovar e iniciar em modo automático - Aprovar e aceitar as edições - Aprovar e rever manualmente cada edição - Continuar o planeamento com feedback - Aperfeiçoar com Ultraplan (revisão no browser) Saber se deve aprovar um plano é a competência essencial no Plan Mode. É fácil carregar em «Aprovar» automaticamente e depois ter de reverter commits. A IA bajuladora quer dar uma resposta rápida, e você quer chegar ao código mais depressa. Ambos estão errados. Um bom plano cumpre 7 critérios: 1. **Nomes de ficheiros específicos.** Não «vou atualizar auth», mas «vou alterar `src/auth/login.ts:42-58`, criar `src/auth/oauth-callback.ts` e atualizar `src/auth/session.ts:103`». 2. **A sequência está especificada.** O plano está dividido em fases ou passos, em vez de «vou fazer isto tudo de alguma maneira». 3. **As dependências externas estão identificadas.** Se a tarefa exigir uma nova biblioteca, ela é indicada. O mesmo se aplica às variáveis de ambiente necessárias. 4. **Os riscos estão enumerados.** Um bom plano diz «a migração pode quebrar as sessões existentes; é preciso verificar X». Um mau plano não menciona efeitos secundários. 5. **Há critérios de sucesso.** «Os testes `test/auth` passam, o linter não apresenta problemas e o servidor de desenvolvimento arranca sem erros.» 6. **Não há pressupostos «tirados do ar».** Se Claude disser «vou usar a biblioteca Z», confirme: chegou sequer a instalá-la no projeto? Se a IA a inventou, verá que não consta de `package.json`. 7. **O plano cabe no ecrã.** Se o plano para uma funcionalidade simples tiver 200 linhas, provavelmente a tarefa é demasiado grande para um único plano. Divida-a em partes. Se o plano não passar na verificação, há três opções: - **Continuar o planeamento com feedback** — dê a Claude um comentário específico sobre aquilo de que não gosta e ele reescreverá o plano. - **Ctrl+G** — abra o plano num editor, edite-o manualmente e guarde. Claude continuará com a sua versão. - **Aperfeiçoar com Ultraplan** — o plano passa para o modo de browser do Claude Code na Web, onde pode rever secções e comentar; depois, executá-lo localmente ou na cloud. Se algo correr mal a meio da implementação, não force. Regresse ao Plan Mode e reescreva o plano. Isso é 10 vezes mais barato do que reverter 40 commits mais tarde. ## Plan Mode + uma pasta `plans/`: uma combinação para contextos longos
Pontos-chave Por si só, o Plan Mode só funciona na conversa atual. Feche a janela e o plano desaparece. Uma pasta `plans/YYYY-MM-DD-feature.md` no repositório transforma o plano num artefacto duradouro: um ficheiro com fases, caixas de verificação e estados que qualquer agente seguinte pode retomar. É a passagem de «plano na memória» para «plano no código».
O Plan Mode é um modo do Claude Code. A pasta `plans/` é uma metodologia construída sobre ele. Se usar o Plan Mode sem uma pasta, atingirá o limite após uma hora de trabalho. Eis a lógica. A janela de contexto de Claude é a memória da sessão. No Opus 4.7, pode conter 1 milhão de tokens, mas esse é o volume de toda a conversa. Se planear uma tarefa complexa numa conversa, depois pedir a implementação, discutir um erro e tratar de outra coisa, a janela fica «inchada». Claude começa a esquecer decisões anteriores, a confundir contextos e a repetir perguntas. A solução é a regra de ouro: **uma tarefa — uma conversa**. Eis como fazê-lo: 1. **Conversa 1 — formular o plano.** Ative o Plan Mode, descreva a tarefa e Claude cria um plano. Guarde-o em `plans/2026-05-21-feature-name.md`. Feche a janela. 2. **Conversa 2 — dividir em fases.** Abra um novo chat. Peça: «pega em `plans/2026-05-21-feature-name.md` e divide-o em fases». Guarde o ficheiro atualizado. 3. **Conversa 3 — implementar a fase 1.** Abra um novo chat. Peça: «implementa a Fase 1 de `plans/2026-05-21-feature-name.md` e assinala as tarefas à medida que as concluis». Feche a janela. 4. **Conversa 4 — implementar a fase 2.** Faça o mesmo. O que ganha com isto? A janela de contexto de cada conversa mantém-se fresca. Claude na fase 3 não conhece os detalhes da fase 1, mas conhece o plano porque o ficheiro `plans/` está no repositório. Qualquer agente seguinte (seja um subagente, uma nova sessão ou uma execução através de `/goal`) pode retomar o plano e continuar. Comparação entre abordagens: | Funcionalidade | Apenas Plan Mode | Plan Mode + pasta `plans/` | |----|----|----| | Durabilidade | Apenas no chat atual | Para sempre no repositório | | Passagem a outro agente | Impossível | `cat plans/file.md` | | Versões e histórico | Nenhum | Através de git diff | | Suporte de subagentes | Apenas na sessão atual | Cada fase → o seu próprio subagente | | Caixas de verificação e estados | Apenas texto | Caixas de verificação Markdown `[ ]` / `[x]` | | Tamanho do plano | Limitado pela janela | Qualquer tamanho | Cada funcionalidade tem o seu próprio ficheiro de plano. Quando, três meses depois, precisar de se lembrar de porque escolheu um fornecedor de pagamentos em vez de outro, pode abrir o plano relevante e consultar o histórico da decisão: o que foi discutido, que opções foram consideradas e porque foi escolhido aquele caminho. São planos de trabalho vivos; a documentação estática fica desatualizada em poucos meses. ## Como pôr Claude a trabalhar enquanto dorme com o Plan Mode e /goal?
Pontos-chave O `/goal` é o ciclo autónomo de que a Anthropic fala há um ano. O comando `/goal` surgiu no Claude Code v2.1.139 (11 de maio de 2026). Define uma condição de conclusão e Claude trabalha nela sem intervenção humana até a satisfazer. Um pequeno modelo avaliador verifica, após cada turno, se a condição foi satisfeita.
A principal limitação das longas sessões com IA não é o modelo em si, mas a pessoa que carrega em Enter. Sempre que Claude chega ao fim de um turno, espera pela sua resposta. O `/goal` elimina essa espera. A sintaxe é simples: ```bash /goal all tests in test/auth pass and lint is clean, or stop after 20 turns ``` A condição pode ter até 4000 caracteres. É possível definir um objetivo por sessão. Após cada turno, o modelo Haiku mini analisa a transcrição e decide: «condição cumprida — terminar» ou «não cumprida — próximo turno». O avaliador não chama ferramentas; apenas lê. Aliases para o limpar: `/goal stop`, `/goal off`, `/goal reset`, `/goal none`, `/goal cancel`. A combinação com o Plan Mode é assim: 1. Ative o Plan Mode (prima `Shift+Tab` duas vezes). 2. Peça: «cria um plano para migrar a base de dados de MySQL para Postgres e guarda-o em `plans/2026-05-21-postgres-migration.md`, com fases e critérios». 3. Reveja o plano, edite-o e aprove-o. 4. Saia do Plan Mode (prima `Shift+Tab` mais uma vez). 5. Defina um objetivo: «conclui todas as fases em `plans/2026-05-21-postgres-migration.md`, assinala as caixas, todos os testes passam ou para após 50 turnos». 6. Feche o portátil e vá dormir. De manhã, verifique o resultado: «✓ objetivo concluído» ou «◎ parado após 50 turnos», com um histórico do que foi feito. Há três regras essenciais para o `/goal`, caso contrário desperdiçará tokens: **Regra 1: Um estado final mensurável.** «Faz com que pareça bonito» é mau. «`npm test` devolve 0, `npm run lint` devolve 0 e foi adicionada uma entrada a `CHANGELOG.md`» é bom. **Regra 2: Verificação explícita.** A condição deve referir algo verificável: um comando, ficheiro ou endpoint. Não «tudo funciona», mas «curl localhost:3000/api/users devolve 200». **Regra 3: Limite o número de turnos.** Acrescente sempre «or stop after N turns». A Anthropic recomenda-o explicitamente na documentação:

Para limitar a duração de execução de um objetivo, acrescente à condição uma cláusula de turnos ou de tempo, por exemplo, «ou parar após 20 turnos».

— Anthropic Docs, https://code.claude.com/docs/en/goal
Se ativar o `/goal` sem «or stop after», o seu orçamento pode desaparecer durante a noite. ## Que ciclo de 4 passos transforma o Plan Mode num processo de engenharia?
Pontos-chave O Plan Mode simples, sem estrutura, produz resultados medianos. Um fluxo de trabalho sólido segue 4 passos numa única janela: estabelecer os factos sem propor uma solução, desenvolver opções com exemplos da Internet, criar um plano detalhado com riscos previstos 2-3 passos à frente e exigir uma autoverificação do plano para identificar pressupostos «tirados do ar». Esta sequência impede a IA bajuladora.
Um erro comum é perguntar «como é que corrijo isto?»: Claude propõe uma solução, aplica-a, mas nada funciona ou a situação piora. É a «IA bajuladora»: foi treinada para responder rapidamente e você quer chegar ao código mais depressa. Um ciclo de 4 passos resolve este problema. O ciclo de 4 passos impede este comportamento. É utilizado sequencialmente numa sessão do Plan Mode: **Passo 1. Estabelecer os factos sem propor uma solução.** Prompt: «Estou a observar o seguinte: \[descrição do sintoma\]. A tua tarefa agora é estabelecer os factos. São proibidas quaisquer soluções, ideias e recomendações. Apenas: o que observo, que passos são reproduzíveis, que dados estão disponíveis e que dados faltam. Condição de paragem absoluta: NÃO proponhas soluções; regista apenas o diagnóstico.» Isto bloqueia o primeiro impulso da IA: «eis a solução». Claude tem de parar em «o que se sabe e o que não se sabe». **Passo 2. Desenvolver opções com exemplos.** Prompt: «Agora que o diagnóstico está estabelecido, encontra online exemplos de resolução de problemas semelhantes. Pelo menos 3 abordagens diferentes. Para cada uma: uma ligação à fonte primária, uma descrição breve e as vantagens e desvantagens para a nossa situação.» Isto bloqueia o segundo impulso da IA: «inventar uma solução de cabeça». Fazemo-la sair para o mundo e trazer abordagens que possam ser verificadas. **Passo 3. Plano detalhado com riscos.** Prompt: «Escolhe a melhor opção do Passo 2 e apresenta um plano detalhado: que ficheiros específicos alterar, o que adicionar, o que remover, que testes escrever, o que pode falhar e que riscos existem 2-3 passos à frente.» É a conhecida fase Plan, com uma diferença: baseia-se nas opções verificadas no Passo 2, e não nas suposições de Claude. **Passo 4. Autoverificação do plano.** Prompt: «Agora faz uma autoverificação obrigatória. Reavalia honestamente o teu plano: há pontos que tiraste do ar e não verificaste no código, na documentação ou num exemplo do Passo 2? Se houver, assinala-os e revê o plano.» Este é o filtro final. Claude tem de verificar o próprio raciocínio e admitir onde alucinou. Nesta fase, são normalmente revistos pelo menos 2 itens do plano. Depois dos 4 passos, o plano está pronto para aprovação. Pode passar à implementação com confiança de que a tarefa foi compreendida, as opções foram ponderadas e os riscos considerados. Esta metodologia destina-se a diagnosticar erros difíceis e a tomar decisões arquiteturais — situações em que o custo de um erro é elevado. Aplicada ao Plan Mode, elimina o principal problema de quem pratica vibe coding: «a IA deu-me uma solução, apliquei-a e tudo se partiu». ## Quais são os 5 prompts prontos a usar que funcionam no Plan Mode para tarefas comuns?
Pontos-chave Os prompts prontos a usar poupam 10-15 minutos por tarefa e melhoram a qualidade dos planos. Há cinco modelos universais para refatorar um módulo, migrar uma base de dados, adicionar uma funcionalidade, escrever testes e depurar um erro complexo. Cada um integra o ciclo de 4 passos e está associado à pasta `plans/`.
**Modelo 1. Refatorar um módulo.** ``` Estou a ativar o Plan Mode. Tarefa: refatorar o módulo {module-name}. Passo 1: Estuda a estrutura atual do módulo {module-path}. Descreve: - que ficheiros fazem parte do módulo - que dependências externas tem - que partes estão duplicadas - que funções são demasiado complexas Passo 2: Encontra online 2-3 exemplos de refatoração de módulos semelhantes. Pelo menos 1 fonte tem de ser documentação oficial da Anthropic ou da framework relacionada. Passo 3: Cria um plano de refatoração em plans/YYYY-MM-DD-refactor-{module}.md: - que ficheiros renomear - que funções extrair para módulos separados - que testes manter e quais reescrever - riscos: o que pode correr mal para os utilizadores Passo 4: Autoverificação. Há pressupostos no plano que foram «tirados do ar»? Reescreve-os ou remove-os. ``` **Modelo 2. Migração da base de dados.** ``` Estou a ativar o Plan Mode. Tarefa: migrar a base de dados de {old} para {new}. Passo 1: Estuda o esquema atual da base de dados usando {schema-reading-command}. Descreve: - que tabelas existem e qual é o seu tamanho - que relações, índices e restrições existem - onde estão guardadas as migrações - que dados são críticos Passo 2: Encontra exemplos de migrações {old → new} em projetos de produção. Pelo menos 3 abordagens diferentes: pg_dump, dual-write, blue-green. Para cada uma, indica as vantagens e os riscos para o nosso volume de dados. Passo 3: Cria um plano de migração em plans/YYYY-MM-DD-db-migration.md: - fases (cópia de segurança, migração, verificação, mudança) - critérios de sucesso para cada fase - plano de reversão caso algo corra mal - com ou sem indisponibilidade Passo 4: Autoverificação. Todos os valores estão apoiados em documentação? Todos os passos foram verificados mentalmente face ao ambiente de desenvolvimento? ``` **Modelo 3. Adicionar uma nova funcionalidade.** ``` Estou a ativar o Plan Mode. Tarefa: adicionar a funcionalidade {description} ao projeto. Passo 1: Estuda como funcionam atualmente funcionalidades semelhantes no projeto. Analisa especificamente: - {file-1} - {file-2} - que padrões arquiteturais são utilizados - que testes são escritos para funcionalidades semelhantes Passo 2: Descobre como esta funcionalidade é implementada em projetos open-source com uma arquitetura semelhante. Pelo menos 2 abordagens diferentes. Passo 3: Cria um plano em plans/YYYY-MM-DD-feature-{name}.md: - lista de ficheiros novos - lista de ficheiros alterados com linhas específicas - sequência de implementação - que testes adicionar - que regra adicionar a CLAUDE.md para sessões futuras Passo 4: Autoverificação. O plano segue a arquitetura do projeto? Pressupõe bibliotecas que ainda não foram instaladas? ``` **Modelo 4. Escrever testes.** ``` Estou a ativar o Plan Mode. Tarefa: cobrir o módulo {name} com testes. Passo 1: Estuda o módulo {path}. Identifica: - funções públicas e as respetivas assinaturas - funções internas que NÃO vamos testar (detalhes de implementação) - casos-limite: entrada vazia, erros, acesso concorrente Passo 2: Encontra exemplos de testes para uma classe de tarefas semelhante em projetos open-source populares que usem a mesma framework. Passo 3: Cria um plano de testes em plans/YYYY-MM-DD-tests-{module}.md: - para cada função pública, uma lista de testes - que mocks são necessários - que fixtures são necessárias - que abordagem de verificação usar (estilo das assertions) Passo 4: Autoverificação. Todos os testes verificam o comportamento, em vez da implementação? A cobertura inclui casos-limite? ``` **Modelo 5. Depurar um erro complexo.** ``` Estou a ativar o Plan Mode. Tarefa: perceber a causa do erro {symptom-description}. Passo 1: ESTABELECE OS FACTOS. Soluções e ideias são proibidas. Apenas: - o que observo (texto exato do erro) - passos reproduzíveis - dados disponíveis (registos, traces, versões das bibliotecas) - dados em falta (o que é necessário recolher adicionalmente) Passo 2: Encontra exemplos deste erro. Pelo menos 3 fontes: GitHub issues, documentação técnica e documentação. Para cada uma, fornece uma ligação e um breve resumo da solução. Passo 3: Cria um plano de diagnóstico em plans/YYYY-MM-DD-bug-{name}.md: - que hipóteses verificar (ordenadas por probabilidade) - que comandos/scripts executar para verificar cada uma - resultado esperado de cada verificação Passo 4: Autoverificação. Há hipóteses no plano «tiradas do ar»? Todas as hipóteses estão ligadas aos factos do Passo 1? ``` Copie cada modelo, substitua `{parameters}` pelos seus próprios valores e cole-o no Claude Code em Plan Mode. O resultado será um plano de trabalho em `plans/`, que poderá aprovar e usar na implementação. ## Plan Mode ou modo normal: qual deve escolher?
Pontos-chave Use Plan Mode para abordagens incertas, código desconhecido, decisões arquiteturais, migrações ou alterações com efeitos secundários significativos. O número de ficheiros é um sinal para considerar dependências, não uma regra rígida. Um diff pequeno, compreendido e de baixo risco pode ser tratado diretamente; descrever autenticação ou migração numa frase não as torna seguras.
A Anthropic diz isto diretamente na documentação:

O modo plan é útil, mas acrescenta trabalho. Para tarefas com um âmbito claro e uma alteração pequena (um erro tipográfico, uma linha de registo, renomear uma variável), peça a Claude que o faça imediatamente. O planeamento é mais útil quando não tem a certeza da abordagem, quando uma alteração afeta vários ficheiros ou quando não conhece bem o código. Se conseguir descrever o diff numa frase, ignore o plano.

— Anthropic Docs, https://www.anthropic.com/engineering/claude-code-best-practices
Dispense um plano separado só quando o diff real for pequeno, compreendido e de baixo risco. Planeie quando precisar de descobrir a abordagem ou coordenar alterações arriscadas entre componentes. Conhecer os nomes dos ficheiros ou resumir o objetivo numa frase não elimina riscos de migração, autenticação ou integridade dos dados. Tabela de decisão: | Tarefa | Modo | Porquê | |----|----|----| | Erro tipográfico no README | Default | Um ficheiro, uma alteração, diff óbvio | | Renomear uma variável num ficheiro | Default | Âmbito claro e referências verificáveis; avaliar efeitos secundários | | Adicionar uma linha de registo | Default | Alteração de uma linha que não afeta a lógica | | Adicionar um botão novo a uma página | Default | Se for um botão e souber onde o colocar, não precisa de plano | | Refatorar um módulo | Plan Mode | 5+ ficheiros, riscos de efeitos secundários | | Migração da base de dados | Plan Mode + `/goal` | Processo com várias fases; é necessário um plano de reversão | | Adicionar autenticação | Plan Mode | Afeta 10+ ficheiros; a segurança é fundamental | | Escrever testes para um módulo | Plan Mode | É necessário determinar o que testar | | Depurar um erro pouco claro | Plan Mode + ciclo de 4 passos | Sem diagnóstico, as soluções falharão o alvo | | Migração de uma framework completa | Plan Mode + `plans/` + `/goal` durante a noite | Tarefa longa que precisa de fases e de um ciclo autónomo | Antes de escolher o modo, verifique se compreende a abordagem, os efeitos secundários e a validação. Trabalhe diretamente numa alteração pequena, localizada e de baixo risco com verificação óbvia. Planeie primeiro perante incerteza, código desconhecido, migração, autenticação ou coordenação entre componentes, mesmo que já consiga identificar os 3-5 ficheiros afetados. ## Como combinar Plan Mode + CLAUDE.md + subagentes para um trabalho fiável?
Pontos-chave O Plan Mode torna-se 10 vezes mais poderoso quando combinado com um [CLAUDE.md](https://ailoot.ai/blog/pt-pt/claude-md-template/) bem configurado e com [subagentes](https://ailoot.ai/blog/pt-pt/claude-code-subagents/). O CLAUDE.md define as regras que Claude usa para criar um plano. Os subagentes permitem distribuir as fases do plano por agentes em paralelo. Sem esta combinação, o Plan Mode continua a ser uma ferramenta pontual.
O CLAUDE.md é um ficheiro que Claude lê no início de cada sessão, incluindo no Plan Mode. Se o CLAUDE.md disser «nunca codifiques datas diretamente; obtém-nas sempre da base de dados», o plano nunca sugerirá datas codificadas diretamente. Se essa regra não existir, o plano pode sugerir qualquer coisa. A combinação funciona assim: **Camada 1. O CLAUDE.md define as regras.** O ficheiro especifica a stack do projeto, os princípios arquiteturais, as proibições («não uses APIs obsoletas») e os requisitos («todos os e-mails usam um layout partilhado»). Guia detalhado: [Como configurar o CLAUDE.md](https://ailoot.ai/blog/pt-pt/claude-md-template/). **Camada 2. O Plan Mode aplica as regras à tarefa.** Quando ativa o Plan Mode e pede «adiciona OAuth», Claude lê o CLAUDE.md, vê as regras («guarda os tokens no Redis, não na base de dados») e tem-nas imediatamente em conta no plano. O plano respeita a arquitetura do projeto. **Camada 3. Os subagentes dividem o trabalho.** Se o plano estiver dividido em fases, cada fase pode ser atribuída a um [subagente](https://ailoot.ai/blog/pt-pt/claude-code-subagents/) separado. Cada subagente trabalha na sua própria janela de contexto sem sobrecarregar a principal. O plano em `plans/` continua a ser a fonte central de verdade: os subagentes leem-no, executam a sua fase e atualizam as caixas de verificação. ## Que 7 erros prejudicam o Plan Mode?
Pontos-chave O Plan Mode falha muitas vezes devido a erros comuns de utilização, não por a ferramenta ser fraca. Os sete erros principais são: manter o plano na memória em vez de o guardar num ficheiro, juntar todas as tarefas num chat, criar um plano sem fases, ignorar a pesquisa aprofundada, deixar a IA bajuladora propor uma solução sem diagnóstico, ignorar a autoverificação e usar condições vagas no `/goal`.
**Erro 1. O plano só existe no chat.** Sintoma: escreveu um plano, fechou a janela e precisa de voltar a ele no dia seguinte — mas já não está lá; o contexto desapareceu. Solução: guarde sempre o plano em `plans/YYYY-MM-DD-feature-name.md` no repositório. O chat é a secretária; o ficheiro é o arquivo. **Erro 2. Todas as tarefas estão num único chat.** Sintoma: numa sessão, fala de auth, depois de uma migração, do design da interface e, por fim, de um erro. A janela de contexto fica «inchada» e Claude esquece-se de coisas anteriores. Solução: uma tarefa — uma conversa. Terminou o plano? Feche a janela. Vai começar a implementação? Abra uma nova. **Erro 3. Um plano de 3000 linhas sem fases.** Sintoma: há um plano, mas não tem caixas de verificação nem divisões. É impossível perceber o que está concluído e o que falta. Não é possível delegar. Solução: divida cada plano em 3-7 fases. Cada fase é uma lista de caixas de verificação com ações específicas. **Erro 4. Não há pesquisa aprofundada antes do plano.** Sintoma: Claude propõe uma solução de cabeça porque não lhe pediu para procurar exemplos. Uma semana depois, descobre que o open source oferece há muito tempo uma abordagem melhor. Solução: passo 2 do ciclo de 4 passos — peça a Claude que encontre 2-3 exemplos online antes de criar um plano. **Erro 5. A IA bajuladora dá uma solução sem diagnóstico.** Sintoma: pergunta «como corrijo o erro X?», Claude propõe uma solução, aplica-a e nada funciona ou as coisas pioram. Solução: comece sempre por «estabelece os factos; as soluções são proibidas». Só passe às opções depois do diagnóstico. **Erro 6. Ignorar a autoverificação.** Sintoma: o plano parece plausível, mas contém 2-3 pressupostos «tirados do ar» (uma biblioteca inventada, uma API inexistente ou uma versão errada). A implementação falha nesses pontos. Solução: passo 4 do ciclo de 4 passos — peça a Claude que volte a verificar honestamente o plano e assinale os pressupostos. **Erro 7. Condições vagas no `/goal`.** Sintoma: define `/goal faz com que pareça bonito`, deixa-o a funcionar durante a noite e acorda com $200 de quota consumida. Solução: use apenas condições mensuráveis, com um comando de verificação e um limite obrigatório «or stop after N turns». Nada de «faz com que fique bom» ou «melhora-o». O oitavo erro, que quem pratica vibe coding comete com maior frequência, é ignorar a própria ideia de uma pasta `plans/`. O Plan Mode sem uma pasta `plans/` não é uma metodologia; é um brinquedo. Se usar o Plan Mode sem criar ficheiros, obtém 10% das suas capacidades. ## O que fazer a seguir à primeira experiência com o Plan Mode?
Pontos-chave A primeira experiência com o Plan Mode é um ponto de partida. Próximos passos: configure o [CLAUDE.md](https://ailoot.ai/blog/pt-pt/claude-md-template/), se ainda não o tiver (sem ele, o plano fica suspenso no vazio), crie uma pasta `plans/` no repositório como metodologia de trabalho e experimente o `/goal` numa tarefa autónoma antes de se deitar. A combinação dos três — Plan Mode, CLAUDE.md e `plans/` — é um sistema funcional.
Três passos concretos, por ordem crescente de dificuldade: **Passo 1. Configure o CLAUDE.md, se ainda não tiver um.** Sem CLAUDE.md, o Plan Mode funciona «no vazio»: Claude não conhece as regras do projeto e propõe planos que quebram a arquitetura. Guia completo: [Como configurar o CLAUDE.md](https://ailoot.ai/blog/pt-pt/claude-md-template/). Um CLAUDE.md mínimo tem 50-80 linhas a descrever a stack, as regras e as proibições. O comprimento é secundário. O que importa é a especificidade. **Passo 2. Crie uma pasta `plans/` no repositório.** Adicione uma pasta `plans/` à raiz do projeto. Defina um formato de nomenclatura: `YYYY-MM-DD-feature-name.md`. Cada plano recebe o seu próprio ficheiro. Ao fim de um mês, terá 20-30 ficheiros; ao fim de seis meses, 100+. É um histórico vivo das decisões do projeto. **Passo 3. Experimente o `/goal` numa tarefa.** Escolha uma tarefa que costuma executar manualmente durante 30-40 minutos. Ative o Plan Mode, crie um plano e guarde-o em `plans/`. Saia do Plan Mode. Defina `/goal conclui todas as fases em plans/file.md, todos os testes passam ou para após 30 turnos`. Feche o portátil durante uma hora e vá fazer outra coisa. Volte e verifique o resultado. Estes três passos são o mínimo. Isto desenvolve-se gradualmente; não tente montar tudo numa só noite. Comece com o CLAUDE.md, acrescente `plans/` após uma semana e experimente o `/goal` durante a noite ao fim de um mês.
### Fontes - [Anthropic Docs - Permission Modes](https://code.claude.com/docs/en/permission-modes) - [Anthropic Docs - Common Workflows](https://code.claude.com/docs/en/common-workflows) - [Anthropic Engineering - Claude Code Best Practices](https://www.anthropic.com/engineering/claude-code-best-practices) - [Anthropic Docs - /goal command](https://code.claude.com/docs/en/goal) - [Anthropic Docs - Changelog](https://github.com/anthropics/claude-code/blob/main/CHANGELOG.md)
Quando estiver pronto, conheça a [Ailoot](https://ailoot.ai/). ## Perguntas frequentes ### Posso dispensar planeamento só porque sei que ficheiros vão mudar? Não. Conhecer os nomes não elimina a incerteza sobre efeitos secundários ou verificação. Planeie migrações, alterações de autenticação e mudanças coordenadas entre componentes, mesmo com a lista de ficheiros definida. ### Quando é desnecessária uma fase separada de Plan Mode? Numa alteração pequena, compreendida e de baixo risco com verificação óbvia, como um erro de escrita localizado, é razoável trabalhar diretamente. Planeie quando a abordagem for incerta, o código desconhecido ou houver riscos operacionais e entre ficheiros a resolver. ## Ailoot · A empresa e a sua carteira de projetos A Ailoot assenta numa experiência operacional consolidada, numa ampla base de clientes, num serviço estável e no acompanhamento contínuo dos KPI. A empresa e a sua carteira de projetos: milhões de clientes; vendas mensais na ordem dos milhares de milhões. A Ailoot aplica essa experiência operacional ao acesso por API a funcionalidades de IA nos produtos dos clientes, agentes, aplicações e automatizações.