Como fazer perguntas e dar instruções: Falando ao coração do Claude
📚 Navegação da Série: O artigo anterior 14 Interface e Atalhos ensinou onde colocar os dedos — cursor, Enter, Esc e comandos de barra. Este artigo muda de nível: suas mãos já sabem onde apertar, agora sua boca precisa saber como falar. Para uma mesma necessidade, dependendo de como você fala, o trabalho do Claude será muito diferente.
Para falar uma verdade que muitos não gostam de ouvir: a maioria das pessoas, quando começa a usar o Claude Code, o trata como um mecanismo de busca.
Imagine este cenário: uma função no projeto dá erro, e você joga um "conserta esse bug" para ele, sem dizer qual arquivo ou qual é o erro. Você aperta Enter e fica esperando o show. O resultado é que ele "adivinha" o que acha ser o bug, altera três arquivos, e nenhum deles era onde você realmente queria corrigir. Você olha para uma tela cheia de diffs confuso, pensando: "Essa IA é ruim, hein".
Mas, se você pensar bem, não é a IA que é ruim. O problema não está no Claude, está na frase que foi muito pobre: a quantidade de informação é quase zero, então ele só pode tentar adivinhar. Se ele adivinhar errado, de quem é a culpa?
Deixe-me dizer de outra forma: o limite do Claude Code é, em grande parte, determinado pela forma como você faz os pedidos. Com o mesmo modelo e no mesmo projeto, alguém que sabe fazer pedidos resolve tudo em três frases; quem não sabe, vai e volta cinco vezes e acaba se irritando. Hoje, vou explicar profundamente as regras gerais de "como descrever uma necessidade em uma frase" — não é para te ensinar a memorizar modelos, mas para você entender o que o Claude precisa saber para não se desviar do caminho.
Após ler este artigo, você terá:
- Uma tabela de comparação "Pergunta Ruim vs Boa Pergunta" para usar como guia, diminuindo as idas e vindas
- Quatro princípios rígidos para fazer pedidos: ser específico, dar contexto, fornecer critérios de aceitação e, para tarefas complexas, planejar primeiro
- A forma correta de usar a referência de arquivo
@para delimitar escopos - Um experimento de "uma necessidade, duas formas de falar" que você pode replicar, para ver a diferença com seus próprios olhos
01 Por que uma pergunta ruim é ruim?
Vamos analisar o desastre mencionado acima. A frase "conserta esse bug", do ponto de vista do Claude, carece absurdamente de informações:
- Qual bug? Ele tem que adivinhar de que parte você está falando.
- Qual arquivo? Ele tem que procurar em todo o projeto.
- Qual o comportamento correto esperado? Ele não tem a menor ideia, só pode basear-se no que "geralmente deveria acontecer".
Analogia: Treinar um estagiário novato. Você chega para um estagiário que acabou de ser contratado e diz "arruma aquilo ali"; seria um milagre se ele fizesse certo. Se mudar para "muda a cor do botão de login no canto superior direito da página inicial, do cinza para o azul da marca #1A73E8", ele poderia fazer de olhos fechados. Quanto mais específica for a instrução, menos o estagiário vai errar; quanto mais vaga, mais ele terá que adivinhar, e a chance de errar aumenta. Com o Claude é a mesma coisa.
Dê uma olhada nesta comparação que a documentação oficial enfatiza repetidamente:
| Cenário | ❌ Pergunta Ruim | ✅ Boa Pergunta |
|---|---|---|
| Corrigir bug | "Corrige o erro de login" | "O usuário reporta falha no login após timeout da sessão. Verifique o fluxo de autenticação em src/auth/, focando no refresh de token. Escreva primeiro um teste que falha e reproduza o problema, depois conserte." |
| Escrever teste | "Adiciona um teste pro foo.py" | "Escreva testes para o foo.py, cobrindo casos extremos para usuários deslogados, sem usar mock." |
| Perguntar sobre código | "Por que a API ExecutionFactory é projetada de forma tão horrível?" | "Verifique o histórico do git do ExecutionFactory e resuma como a sua API evoluiu passo a passo até o que é hoje." |
| Adicionar funcionalidade | "Adiciona um componente de calendário" | "Veja como os componentes existentes na homepage são implementados, HotDogWidget.php é um bom exemplo. Siga este padrão para implementar um componente de calendário, permitindo ao usuário selecionar meses e navegar pelos anos. Além das bibliotecas já presentes no repositório, não traga bibliotecas novas." |
Viu qual é o segredo? Uma boa pergunta faz apenas uma coisa: entrega de antemão tudo que o Claude precisaria adivinhar.
💡 Resumo em uma frase: A pergunta ruim é ruim porque "as lacunas de informação são preenchidas pela imaginação do Claude"; a boa pergunta é deixar claro antecipadamente o que ele precisaria adivinhar.
Esta imagem Before/After coloca lado a lado duas formas de perguntar pela mesma necessidade: À esquerda, uma pergunta vaga, onde o Claude só pode adivinhar e fazer uma série de perguntas de volta; à direita, entregando o escopo, o contexto (com @arquivo) e os critérios de aceitação juntos, ele acerta de primeira, passa os testes e pronto. A diferença não está no Claude, está em como você fala.
02 Princípio 1: Específico > Vago
Esta é a regra mais importante de todas as quatro.
Há uma frase na documentação oficial que vale muito a pena lembrar:
Quanto mais precisa for sua instrução, menos correções você precisará.
Traduzindo: falar um pouco mais no início economiza três rodadas de retrabalho no final. Você acha que está "poupando esforço" digitando algumas palavras a menos, mas na verdade, essas palavras a menos acabam virando um custo dobrado de idas e vindas.
Quão específico deve ser? Adicione três dimensões:
Primeiro, delimite o escopo — qual arquivo, qual função, qual cenário. Não deixe que ele procure uma agulha num palheiro em todo o projeto.
Segundo, esclareça as restrições — "Não introduza novas bibliotecas", "Mantenha a retrocompatibilidade", "Não toque nos arquivos de teste". Se você não disser, ele agirá conforme as preferências dele, o que pode não ser o que você quer.
Terceiro, dê uma referência — "Siga o padrão do HotDogWidget.php". Na prática, este é o truque que mais poupa preocupações: em vez de descrever o estilo que você quer, jogue para ele um exemplo pronto que você já aprova, se ele copiar, não vai se afastar muito do ideal.
É preciso esclarecer uma exceção que parece contra-intuitiva: perguntas vagas não são absolutamente erradas. Quando você está na "fase de exploração" e ainda não decidiu a direção, uma pergunta aberta como "o que você acha que pode ser melhorado neste arquivo?" pode extrair insights que você nem imaginava perguntar. Nas palavras oficias, "quando você está explorando e capaz de corrigir a direção, prompts vagos podem ser úteis". A regra é: se quiser resultados defina tudo especificamente, se busca inspiração, deixe espaço aberto propositalmente.
Ao criar pequenas ferramentas, é fácil esbarrar neste limite — no início, queria ver como o Claude entendia o código bagunçado e perguntei de forma vaga; os pontos de melhoria sugeridos foram realmente inspiradores. Mas, uma vez que se tem um objetivo claro, usar perguntas vagas é pura perda de turnos, ele terá que adivinhar tudo de novo.
💡 Resumo em uma frase: Se quer um resultado, seja extremamente específico (escopo + restrições + referência); apenas deixe espaços abertos intencionalmente quando buscar inspiração.
03 Princípio 2: Dê o contexto, não o deixe adivinhar
Além de ser específico, o segundo truque é entregar os "ingredientes" diretamente a ele, em vez de descrever com palavras onde os "ingredientes" estão.
Existem duas ações de alta frequência; dominando-as você terá metade do caminho andado:
Primeiro, use o @ para referenciar arquivos. Digitar @ na caixa de entrada mostrará o autocompletar do caminho do arquivo; ao selecionar, o conteúdo completo do arquivo será injetado diretamente na conversa — o Claude não precisará procurar e ler, economizando passos e evitando que ele pegue o arquivo errado.
Consulte as definições de tipo no @src/types/user.ts para adicionar anotações de tipo ao UserServiceIsto é mil vezes mais seguro do que "há um arquivo de tipo de usuário no projeto, procure lá". A documentação oficial diz explicitamente que a referência @ "lê o conteúdo completo do arquivo antes da resposta".
Analogia: Pendrive. O @ é como plugar um "Pendrive de arquivos" diretamente na mesa de trabalho do Claude — plug and play, a informação chega em um segundo; se você disser "os documentos estão na sala de arquivos do terceiro andar no segundo armário", ele ainda terá que ir lá e, se errar, o trabalho atrasará.
Segundo, cole diretamente blocos de erro. Isso deve se tornar um reflexo muscular — ao se deparar com um traceback, não faça um resumo dizendo "ele deu erro de ponteiro nulo", cole o stack trace completo exatamente como está:
Deu este erro em tempo de execução, me ajude a localizar a causa:
TypeError: Cannot read properties of null (reading 'userId')
at getUserProfile (src/services/user.ts:42:18)
at async ProfileController.getProfile (src/controllers/profile.ts:15:20)Por que colar o trecho inteiro? Porque o stack trace contém nomes de arquivo, números de linha e cadeia de chamadas; seguindo user.ts:42, o Claude pode localizar com precisão. Se você resumir, apagará todas essas coordenadas críticas, forçando-o a adivinhar novamente.
| Informação a passar | ❌ Descrever | ✅ Fornecer diretamente |
|---|---|---|
| O conteúdo de um arquivo | "Há um arquivo que lida com autenticação no projeto" | @src/auth/session.ts |
| Um erro | "Deu um erro undefined" | Colar o traceback completo |
| Um problema de UI | "A posição do botão está errada" | Colar um screenshot direto (O Claude suporta leitura de imagens) |
| Uma especificação de API | "Siga nossa especificação de API" | @docs/api-spec.md |
Em uma frase: Tudo que pode ser "colado", jamais deve ser "dito". O Claude ler o material original será sempre mais preciso do que ler a sua interpretação em segunda mão.
💡 Resumo em uma frase: Use
@para apontar arquivos e cole erros ou capturas de tela diretamente na cara dele; não o faça adivinhar baseado nas suas descrições.
04 Princípio 3: Dê um critério de sucesso "verificável"
Isso é facilmente negligenciado, mas tem um poder enorme: você precisa deixar claro para o Claude "o que conta como concluído com sucesso" e, de preferência, de forma que ele mesmo possa verificar.
Por que isso é crítico? A documentação oficial detalha a lógica de base —
Quando o trabalho parecer concluído, o Claude irá parar. Sem uma verificação que ele possa executar, "parece concluído" é o único sinal disponível e você se torna o loop de validação: cada bug está esperando você notá-lo.
O que isso significa? Se você não der um padrão, o Claude vai parar quando "achar que está bom" e você será quem tem que verificar e garantir tudo, caçando cada falha pessoalmente. Mas, ao fornecer um teste que retorne um "passou / falhou", o ciclo se fecha por si mesmo: Ele termina o trabalho → roda o teste → vê o resultado → se não passar, ele tenta consertar sem que você precise supervisionar.
Veja a diferença:
| Tarefa | ❌ Sem critério de aceitação | ✅ Com critério verificável |
|---|---|---|
| Escrever Função | "Implemente uma função para validar emails" | "Escreva a função validateEmail. Casos de uso de exemplo: user@example.com é verdadeiro, invalid é falso, user@.com é falso. Rode testes após terminar." |
| Ajustar UI | "Deixe esse dashboard mais bonito" | "[Cole o design] Implemente com base nisto, depois tire print do resultado, compare com o original, liste as diferenças e conserte-as." |
| Consertar Build | "O build quebrou" | "O build deu este erro: [Cole o erro]. Conserte e verifique se o build passa. Resolva a causa raiz, não apenas esconda o erro." |
Preste atenção na última frase: "Resolva a causa raiz, não apenas esconda o erro" — isso é algo que aprendi depois de algumas falhas. Sem essa frase, às vezes, por comodidade, ele envolvia o código com um try/except ou adicionava @ts-ignore para apagar as linhas vermelhas. O erro sumia, mas a doença raiz continuava lá.
Uso Avançado: /goal transforma os critérios de aceitação num "só saio quando estiver pronto". (Exige Claude Code v2.1.139 ou superior). Na conversa normal, o critério de aceitação vale para "uma rodada"; com o /goal, ele é fixado como o objetivo de toda a sessão — após cada rodada, um modelo menor (Haiku, por padrão) verificará suas condições novamente. Se não for atingido, ele iniciará outra rodada sozinho, sem devolver o controle para você, até que as condições sejam satisfeitas.
/goal todos os testes em test/auth estão passando, e o passo de lint está limpoHá um detalhe crucial para não se frustrar ao usar /goal: aquele pequeno modelo avaliador apenas analisa o que o Claude "exibe" na conversa; ele não rodará comandos nem lerá arquivos por conta própria. Então, a condição deve ser comprovável pela saída do Claude — "testes de test/auth passaram" funciona porque o Claude realmente roda o teste e o resultado é impresso na conversa para o modelo avaliar. Se você colocar "a qualidade do código é alta", que não pode ser vista em uma saída, ele não terá como julgar.
💡 Resumo em uma frase: Dê a ele uma verificação de passou / falhou (testes, comparação de prints, exit code de builds), o ciclo se fecha sozinho; se quiser que ele "não pare até conseguir", use o
/goal.
05 Princípio 4: Tarefas complexas, peça um plano antes de executar
Por último, a regra para o "trabalho pesado": Para mudanças amplas, em vários arquivos, ou onde nem você tem certeza do caminho, não o deixe codificar cegamente logo de cara — peça-lhe para listar um plano e libere a execução só depois que você dar uma olhada.
Fizemos um prelúdio disso no artigo 06 (Planos e Cobranças), e aqui veremos o porquê. A conclusão da documentação oficial é bem direta:
Fazer o Claude pular direto para a codificação pode produzir código que resolve o problema errado.
Em outras palavras, primeiro explore, depois planeje, e só então codifique — separe o "pensar" do "fazer" para evitar que ele corra a toda velocidade na direção errada; quando você notar, ele já terá mexido em dezenas de coisas.
Analogia: Reformas residenciais. Nenhum operário experiente pega o martelo e quebra uma parede de carga sem dizer uma palavra. Ele antes confirma com você: "quebrar essa parede, passar cabos aqui, mudar o encanamento", e só então ele começa a quebrar, após o seu ok. O plano é aquele desenho técnico que o Claude te entrega antes de começar a martelar — descobrir um erro no desenho custa algumas pinceladas, um custo infinitamente menor que refazer uma parede já demolida.
Como pedir para ele entregar o desenho técnico primeiro? Existem duas maneiras:
Método 1: Apenas diga "Não mude nada ainda". Em uma conversa normal, acrescente esta limitação:
Quero adicionar uma opção de modo escuro na página de configurações. Primeiro me diga quais arquivos você precisa alterar e qual é a ideia da modificação,
não altere nenhum código neste passo.Método 2: Mude para o Plan Mode (Modo de Planejamento). Esta é a "marcha de planejamento somente-leitura" do Claude Code — ele lerá arquivos e propõe soluções, mas não salvará nada até você aprovar. Para entrar, pressione Shift + Tab (uma ou duas vezes) e a interface rodará entre default → acceptEdits → plan. Se você quiser o Plan Mode para apenas uma mensagem, não é necessário trocar a sessão inteira: adicione o prefixo /plan na frente da sua solicitação.
Mas a equipe oficial também dá um lembrete importante, não se empolgue planejando tudo:
Para tarefas pequenas com escopo claro (como arrumar erros de digitação, adicionar logs ou renomear variáveis), peça para o Claude executá-las diretamente. Quando não tiver certeza da abordagem, ou a mudança alterar vários arquivos ou quando não conhecer bem o código, o planejamento é mais útil. Se você consegue descrever o diff em uma frase, pule o plano.
O conselho prático final é a segunda metade: "Eu consigo descrever com uma frase como o código ficará depois disso?" Se sim, vai direto ao ponto; se travar, quer dizer que é complexo o suficiente para precisar de um plano primeiro. Usar Plan Mode para corrigir erro de digitação é puro teatro.
💡 Resumo em uma frase: Incerto / Vários arquivos / Código desconhecido → Peça um plano antes ("não mude ainda" ou
Shift+Tabp/ Plan Mode); Se o diff der pra ser descrito numa frase, vá e faça logo.
06 Prática: A mesma necessidade, em duas formas diferentes
Não adianta só entender a teoria, vamos fazer um pequeno experimento que mostrará a diferença. Prepare um arquivo de brinquedo de 3 linhas; não dependeremos de um projeto real seu.
Passo 1: Crie um arquivo com uma armadilha (Mac / Linux)
mkdir prompt-demo
cd prompt-demo
echo 'def average(nums):
return sum(nums) / len(nums)' > stats.pyUsuários do Windows: digite os mesmos comandos mkdir prompt-demo e cd prompt-demo. Depois, abra o Bloco de Notas para criar o stats.py e cole as duas linhas nele.
A função tem uma falha: Ao passar uma lista vazia [], len(nums) será zero, o que dispara um crash "divisão por zero". Usaremos isso como cobaia.
Passo 2: Rode o Claude no diretório do projeto
claudeResultado Esperado: Surge a tela de boas-vindas com o campo de entrada no final.
Passo 3: Use primeiro uma "pergunta ruim" para ver como ele preenche as lacunas
@stats.py me ajuda a arrumar essa funçãoResultado Esperado: O Claude muito provavelmente vai "adivinhar" o que você quer fazer — talvez adicionar anotações de tipo ou um docstring, mas não vai saber que a sua verdadeira preocupação é o crash com listas vazias. O rumo dependerá apenas da sorte. Esse é o custo de perguntas vagas: Ele toma decisões por você.
Passo 4: Use uma "boa pergunta" — Específico + Contexto + Critérios de Aceitação
A função average em @stats.py tem um bug: ela quebra com divisão por zero quando recebe uma lista vazia.
O comportamento esperado é que listas vazias retornem 0.
Conserte isso e adicione testes: average([]) deve ser 0, average([2, 4]) deve ser 3.
Rode os testes após criar e verifique que passaram.Resultado Esperado: Desta vez, a cadeia de ações do Claude será cristalina — encontra a ramificação da lista vazia → adiciona checagem para retornar 0 → escreve os dois testes que você especificou → roda os testes → mostra para você que passaram. Ele não adivinha o que você quer porque você delimitou tudo: onde alterar, o que virar e como provar sucesso.
Passo 5: Saia e confirme a alteração no arquivo
cat stats.py(Windows PowerShell usa type stats.py)
Resultado Esperado: stats.py terá a verificação de lista vazia (algo como if not nums: return 0). Como isso coincide com seu pedido no passo 4 = Você atingiu o domínio de "falar de forma clara".
Colocando os dois pedidos lado a lado, a diferença é brutal:
| Passo 3 ❌ Pergunta Ruim | Passo 4 ✅ Boa Pergunta | |
|---|---|---|
| Mudar o quê | Não dito, chuta o arquivo inteiro | Apontada função average |
| Para como | Não dito, inventou sozinho | Retornar 0 se lista for vazia, definido |
| Como ser sucesso | Sem métrica, ele decide ao "sentir" que concluiu | Dois testes + Rodar e testar |
| A sua experiência | Olhar para os diffs pensando "não é isso que eu queria" | Sabe a direção desde o começo, resolve de primeira |
💡 Resumo em uma frase: No mesmo arquivo, no mesmo bug, uma pergunta ruim faz o Claude tomar decisões por você, uma boa deixa tudo bem delimitado (onde, o que, verificação) — Teste você mesmo, a diferença é mais intuitiva do que ouvir os princípios mil vezes.
07 Conclusão
Este artigo abordou apenas um aspecto: como tornar um pedido tão preciso a ponto de o Claude pegá-lo facilmente.
São quatro princípios, e se você não conseguir lembrar de todos, lembre-se desta tabela:
| Princípio | Resumo de Uma Frase | Como Aplicar |
|---|---|---|
| Específico > Vago | Escopo, restrições e referência claros | "Mude average, sem biblioteca nova, no estilo xxx" |
| Dar Contexto | Nunca descreva o que puder colar | @arquivo, jogar traceback, prints de erro |
| Critérios Aceitáveis | Permita que ele avalie "se conseguiu ou não" sozinho | Casos de teste, rodar os testes, testar com /goal |
| Plano Antes | Não deixe que a parede seja demolida sem desenho técnico | "Não escreva código ainda", usar Plan Mode |
O que você deve saber agora: Você já é capaz de traduzir a requisição frouxa "me ajuda aí a arrumar isso" em um pedido que o Claude pode atender — definindo escopo, preenchendo contexto, dando um objetivo mensurável, e pedir um plano antecipado para ações mais pesadas. Estes padrões são "a sua energia interior" que embasam toda ação do Claude Code a partir de agora. — Ferramentas mirabolantes não farão milagres com solicitações péssimas.
Um pequeno exercício reverso para reflexão: Dado que "explicar com precisão" é tão importante, há certos padrões ou políticas, (por exemplo, "nunca usar nova biblioteca neste projeto" ou "todos os testes vão no diretório
tests/"), que deverão ser repetidas toda vez? Haveria um modo de fazer o Claude "lembrar" delas, e poupar o esforço de repetí-las constantemente?
No próximo artigo 16 "Fluxos de Trabalho Comuns" — Você acabou de aprender os padrões universais para "explicar os comandos", e é chegada a hora de testá-los em cenários super frequentes: navegar num projeto desconhecido, refatorar código, corrigir bugs, ou implementar testes. Veremos padrões infalíveis que você pode simplesmente usar para suas necessidades diárias. Tem o princípio, hora do treinamento.