Plan mode, Explore e memória
Objetivos de aprendizagem
- Decidir entre
plan modee execução direta segundo os critérios do exame (task statement 3.4). - Reconhecer os sinais de que uma tarefa exige plan mode: mudanças em larga escala, múltiplas abordagens válidas, decisões arquiteturais, modificações multi-arquivo.
- Usar o subagente
Explorepara isolar descoberta verbosa e preservar o contexto da conversa principal. - Combinar plan mode (investigação/design) com execução direta (implementação) em tarefas multi-fase.
- Relacionar a memória persistente (
CLAUDE.md,/memory) com a redução de re-explicação entre sessões.
O que é o plan mode
No plan mode, o Claude Code opera em caráter somente-leitura: explora o codebase, lê arquivos, entende dependências e produz um plano de implementação — mas não edita nada até o plano ser aprovado. É o mecanismo de "projetar antes de comprometer": permite explorar com segurança e decidir a abordagem antes de tocar o código, prevenindo retrabalho caro. Na interface interativa você alterna o modo de permissão da sessão (por exemplo com Shift+Tab); o modo padrão também é configurável em settings.json (lição 2).
Quando usar cada modo
| Sinal da tarefa | Modo indicado | Exemplo do exam guide |
|---|---|---|
| Mudança em larga escala, dezenas de arquivos | Plan mode | Migração de biblioteca afetando 45+ arquivos |
| Decisão arquitetural, fronteiras de módulos | Plan mode | Reestruturar monólito em microsserviços |
| Múltiplas abordagens válidas com trade-offs | Plan mode | Escolher entre integrações com requisitos de infra diferentes |
| Mudança pequena e bem-escopada | Execução direta | Adicionar uma validação de data em uma função |
| Bug de arquivo único com stack trace claro | Execução direta | Corrigir null pointer apontado pelo stack trace |
flowchart TD
T[Nova tarefa] --> Q1{Escopo claro e pequeno?
1 arquivo, correção óbvia}
Q1 -- Sim --> DE[Execução direta]
Q1 -- Não --> Q2{Múltiplas abordagens válidas,
decisão arquitetural ou
mudança multi-arquivo?}
Q2 -- Sim --> PM[Plan mode:
explorar + desenhar plano]
PM --> AP{Plano aprovado?}
AP -- Sim --> DE2[Execução direta
do plano aprovado]
AP -- Não --> PM
Q2 -- Não --> DE
Pegadinha: "começo executando e mudo para plan mode se a complexidade aparecer" é distrator clássico. Quando a complexidade já está declarada no enunciado (dezenas de arquivos, decisões de arquitetura), esperar ela "emergir" significa descobrir dependências tarde demais — retrabalho que o plan mode existe para evitar. Igualmente errado: usar plan mode para toda vírgula, adicionando latência e cerimônia a mudanças triviais.
O subagente Explore
Fases de descoberta (mapear um codebase desconhecido, localizar todos os usos de uma API, entender um sistema legado) produzem saída volumosa: dezenas de leituras de arquivos e buscas que, na conversa principal, consumiriam o contexto que você vai precisar durante a implementação. O subagente Explore executa essa varredura em contexto isolado e devolve apenas um resumo — as leituras intermediárias morrem com o subagente. Em tarefas multi-fase, isso evita a exaustão da janela de contexto antes de a implementação começar.
- Use Explore quando a pergunta é "onde/como o codebase faz X?" e a resposta útil é a conclusão, não os dumps de arquivos.
- Não use quando você já sabe o arquivo exato — uma leitura direta é mais barata que despachar um subagente.
Combinando os modos em tarefas multi-fase
O padrão recomendado para uma migração de biblioteca, por exemplo:
- Plan mode + Explore: mapear todos os pontos de uso da biblioteca antiga (descoberta isolada), avaliar abordagens e produzir o plano de migração.
- Aprovação humana: revisar fronteiras, ordem de mudanças e riscos.
- Execução direta: implementar o plano aprovado, agora com escopo claro — cada passo virou uma "mudança pequena e bem-escopada".
Ou seja: plan mode e execução direta não competem; investigação em plan mode converte uma tarefa ambígua em uma sequência de tarefas diretas.
Memória persistente entre sessões
Cada sessão do Claude Code começa com contexto vazio, exceto pelo que a memória persistente injeta: os arquivos CLAUDE.md da hierarquia (lição 1) e as regras aplicáveis. Decisões arquiteturais tomadas em uma sessão de plan mode se perdem ao fechar a sessão — a prática recomendada é registrar decisões duráveis no CLAUDE.md (ou num arquivo importado por ele) para que sessões futuras não re-descubram nem contradigam o que já foi decidido. O comando /memory mostra e edita esses arquivos; # no início de uma mensagem oferece atalho para adicionar uma memória rapidamente.
Prática recomendada: ao final de um plano aprovado que estabelece convenções novas ("toda chamada HTTP passa pelo client lib/http.ts"), persista a convenção na memória do projeto. O custo é de poucos tokens; o benefício é consistência em todas as sessões futuras — de todo o time, se estiver no nível de projeto.
Pegadinhas da prova
- Distrator típico: "execução direta com instruções upfront detalhadas" para reestruturação arquitetural — assume que você já conhece a estrutura certa sem explorar o código.
- Distrator típico: "deixe a implementação incremental revelar as fronteiras naturais" — descobre dependências tarde e gera retrabalho; é o oposto de explorar com segurança antes de comprometer.
- Distrator típico: "só mude para plan mode se encontrar complexidade inesperada" — a complexidade já declarada no enunciado não é inesperada.
- Distrator típico: rodar a descoberta verbosa na conversa principal "para o Claude ter todo o contexto" — o excesso de saída intermediária esgota a janela e degrada a implementação; Explore devolve o resumo que interessa.
- Distrator típico: usar plan mode para um bug de uma linha com stack trace claro — cerimônia sem benefício; execução direta resolve.
Resumo em 5 linhas
- Plan mode = exploração somente-leitura + plano aprovável; ideal para mudanças grandes, multi-arquivo, com decisões arquiteturais ou múltiplas abordagens válidas.
- Execução direta = mudanças pequenas e bem-escopadas (bug de um arquivo com stack trace, validação pontual).
- A complexidade declarada no enunciado já justifica plan mode — não espere ela "aparecer" durante a execução.
- Subagente Explore isola descoberta verbosa em contexto próprio e retorna só o resumo, preservando a janela da conversa principal.
- Combine: plan mode para investigar e decidir, execução direta para implementar; persista decisões duráveis no CLAUDE.md (
/memory).
Documentação oficial
Questões de fixação
1. Você precisa migrar o ORM de um serviço, o que afeta cerca de 50 arquivos e admite duas estratégias com trade-offs distintos (adapter incremental vs migração big-bang). Qual abordagem o exame espera?
Gabarito: A. Mudança em larga escala + múltiplas abordagens válidas são exatamente os critérios de plan mode. B descobre dependências tarde demais e gera retrabalho. C pressupõe conhecimento que só a exploração daria. D ignora que a complexidade já está declarada — não é algo que "pode surgir".
2. Um teste falha com stack trace apontando uma comparação de datas errada em uma única função utilitária. Qual é a abordagem adequada?
Gabarito: C. Bug de arquivo único com stack trace claro é o exemplo canônico de execução direta. A adiciona cerimônia sem benefício. B usa descoberta pesada para um problema já localizado. D confunde o modo headless de CI com o fluxo interativo de correção — resolve outro problema.
3. Durante uma tarefa multi-fase, a fase de descoberta (entender um subsistema legado) gera dezenas de leituras de arquivos e a janela de contexto se esgota antes da implementação. Como reestruturar?
Gabarito: B. É o caso de uso definidor do Explore: a saída verbosa fica no contexto do subagente e só a conclusão volta. A não muda a ordem de grandeza do problema — as leituras de arquivos continuam no contexto. C é uma mudança organizacional drástica para um problema de gerenciamento de contexto. D incharia a memória sempre-carregada de todas as sessões futuras, piorando o consumo de tokens.
4. Após uma sessão de plan mode que definiu "todo acesso a banco passa pelo repositório db/repo.ts", as sessões da semana seguinte voltam a criar queries diretas. Qual é a correção estrutural?
Gabarito: D. Sessões novas começam sem o contexto das anteriores; decisões duráveis pertencem à memória persistente, carregada automaticamente para todo o time. A e B pagam custo recorrente (tempo/tokens) por algo que a memória resolve uma vez. C injeta histórico volumoso e não versionado — frágil e caro em tokens.