Como fazer o Claude Code perguntar antes de começar a codar

Código que roda perfeito e resolve o problema errado é o desperdício mais caro do vibe coding

Você pediu uma coisa, o Claude Code entendeu outra, e as duas versões parecem certas até alguém abrir o PR e perguntar "por que ele fez assim?"

O ponto de virada é bem simples: em vez de aceitar a primeira interpretação dele, você segura a edição e pede que ele levante dúvidas e confirme as premissas ANTES da primeira linha de código

E isso se monta em três camadas, do mais rápido ao mais permanente: o modo de planejamento, que tira dele o poder de editar enquanto ele pesquisa e propõe, o pedido explícito de entrevista pela ferramenta AskUserQuestion, que é o que realmente arranca as perguntas, e uma instrução fixa no CLAUDE.md pra valer em toda sessão

Bora ver na prática? 🙂

Formação Recomendada

Formação Claude Code

Domine Claude Code do absoluto zero até o avançado

• 110 aulas
• 4 projetos
• 9h 2min

Conhecer formação

O que você precisa antes de começar

Nada de PC da Nasa aqui, o setup é o básico mesmo:

• Claude Code instalado e uma sessão aberta no diretório do projeto
• Noção dos modos de permissão, que são default, acceptEdits, plan, auto, dontAsk e bypassPermissions
• Um ./CLAUDE.md (ou ./.claude/CLAUDE.md) se você quiser tornar o comportamento permanente, e não só do humor daquela conversa

Duas pegadinhas de nome que confundem muita gente, então se liga

O modo que revisa cada ação aparece como Manual na CLI, no claude --help, nas extensões de VS Code e JetBrains e no app desktop, mas o valor dele na configuração é default

E nos planos Pro, Max e Team o modo inicial em sessões interativas de terminal e VS Code é o auto, ou seja, se você não fizer nada, a sessão já nasce com ele autorizado a tocar o barco

A referência completa disso tudo está na documentação de modos de permissão

Passo a passo para o Claude Code perguntar antes de escrever código

A lógica geral: primeiro você tira dele o poder de editar, depois você dá pouca informação de propósito, e só então pede as perguntas

Parece contraintuitivo dar POUCA informação, né? É intencional, já explico

1. Entre no modo de planejamento antes de qualquer coisa. Shift+Tab cicla os modos de permissão, ou você prefixa um único prompt com /plan. No plan mode ele lê arquivos, roda comandos de exploração e escreve um plano, mas não edita o código-fonte do projeto. O erro comum deste passo é começar em auto e só perceber que estava fora do plan mode quando ele já editou meio repositório

/plan quero adicionar login por magic link no app

2. Dê uma descrição mínima da funcionalidade, não o briefing completo. As boas práticas oficiais mandam começar com uma descrição mínima justamente pra sobrar espaço pras perguntas. O erro comum aqui é despejar uma spec de quarenta linhas no primeiro prompt: aí não sobra dúvida nenhuma pra ele levantar, e você só recebeu de volta a sua própria interpretação

3. Peça a entrevista, explicitamente. Não adianta um "me faça perguntas" solto, isso rende três perguntas óbvias e olhe lá. O prompt sugerido nas boas práticas nomeia os eixos e proíbe o óbvio

Antes de propor qualquer implementação, me entreviste usando a ferramenta AskUserQuestion.
Cubra implementação técnica, UI/UX, casos de borda, preocupações e trade-offs.
Não faça perguntas óbvias, insista nas partes difíceis e continue até cobrir tudo.

4. Responda as perguntas de múltipla escolha com calma. Os diálogos do AskUserQuestion deixaram de continuar sozinhos por padrão, então ele te espera. Se você PREFERE um tempo limite de inatividade, a configuração askUserQuestionTimeout aceita 60s, 5m, 10m ou never, e aparece no /config como "Question auto-continue timeout". Se alguma opção vier com jargão que você não domina, vale saber o que perguntar antes de aceitar em vez de escolher no chute

5. Feche com a spec autocontida. A spec mais útil, segundo a documentação, nomeia os arquivos e interfaces envolvidos, declara o que está fora de escopo e termina com um passo de verificação ponta a ponta

Agora escreva a spec completa em SPEC.md: arquivos e interfaces envolvidos,
o que está fora de escopo e um passo de verificação ponta a ponta.

6. Escolha como prosseguir quando o plano aparecer. Ele apresenta o plano e pergunta: aprovar e iniciar em modo auto, aprovar e revisar cada edição manualmente, ou continuar planejando. Tome cuidado com a pressa aqui, porque a aprovação de plano nunca se resolve sozinha por inatividade, aquele tempo limite vale só pras perguntas de múltipla escolha. Se quiser sair sem aprovar, Shift+Tab de novo, e pra voltar a planejar depois é ciclar outra vez ou usar /plan no próximo prompt

7. Rode a spec em sessão nova. As boas práticas recomendam iniciar uma sessão limpa pra executar, com o contexto focado só na implementação. É a diferença entre um contexto cheio de "e se" descartado e um contexto que só sabe o que ficou decidido

Quando a rodada extra de perguntas compensa (e quando não)

Entrevista em tudo é receita pra você odiar o processo na terceira tarefa

O gatilho oficial da AskUserQuestion já entrega o critério: ela é chamada quando a tarefa tem mais de uma abordagem válida

O critério prático que eu usaria: se você consegue descrever a solução inteira em uma frase e só existe um jeito sensato de fazer, manda ver direto

Se você precisa de um "depende" pra explicar a tarefa pra um colega, esse "depende" é exatamente o que ele vai chutar sozinho

Ele continua codando sem perguntar: o que verificar

Antes de culpar o modelo, olhe o ambiente primeiro e o prompt depois, é a mesma ordem de investigação de quando o Claude Code não reconhece uma ferramenta instalada

Sintoma: ele começa a editar direto

Causa provável: a sessão não está no modo de planejamento. Nos planos Pro, Max e Team o modo inicial em terminal interativo e VS Code é o auto, então o padrão joga contra você

Solução: Shift+Tab até cair no plan mode, ou prefixo /plan no prompt

Como prevenir: confira o modo ANTES de escrever o pedido, não depois

Sintoma: a instrução de perguntar vale só naquela conversa

Causa: o pedido foi feito no prompt, e prompt morre com a sessão

Solução: registre a regra no ./CLAUDE.md ou no ./.claude/CLAUDE.md, que são lidos no início de cada sessão. Se o arquivo ainda não existe, /init gera um inicial, e quando já existe ele sugere melhorias em vez de sobrescrever

## Fluxo de trabalho

Em funcionalidades novas, me entreviste com AskUserQuestion antes de implementar:
implementação técnica, UI/UX, casos de borda, preocupações e trade-offs.

Como prevenir: rode /context na sessão e confira a lista em "Memory files". Se o arquivo não aparece lá, ele não foi carregado, e nenhuma regra de dentro dele está valendo

Sintoma: quero uma checagem toda vez que ele sai do modo de planejamento

Solução: ExitPlanMode pode ser usado como matcher em hooks PreToolUse. Quando o hook aprova, o Claude Code sai do modo de planejamento e restaura o modo de permissão que estava ativo antes

Como prevenir: pense nisso como o portão da saída, e não como substituto do plano bem feito

Sintoma: no Agent SDK ele nunca pergunta

Causa: o AskUserQuestion está disponível por padrão, MAS se você especificou um array tools restringindo as capacidades do Claude, ela precisa estar incluída nesse array

Solução: inclua o AskUserQuestion na lista

Como prevenir: toda vez que apertar as ferramentas do agente, confira se alguma capacidade de conversa foi junto no pacote

Conclusão

São três camadas, e elas se empilham bem

O modo de planejamento resolve o agora: Shift+Tab ou /plan, e ele pesquisa e propõe sem editar

A entrevista via AskUserQuestion, pedida no prompt, resolve a tarefa grande, cobrindo implementação técnica, UI/UX, casos de borda, preocupações e trade-offs até acabar a dúvida

E o CLAUDE.md resolve o amanhã, pra você não repetir o mesmo pedido toda santa sessão

O próximo passo concreto é escolher UMA tarefa de porte médio que está na fila, abrir ela em plan mode, pedir a entrevista, guardar a spec autocontida em SPEC.md e executar numa sessão nova

Depois compare com o que você teria recebido no chute da primeira interpretação, a diferença costuma aparecer logo no primeiro caso de borda 😀

até o próximo post!