# Porque é que o Claude faz a coisa errada: 3 instruções
> O Claude escreve a coisa errada porque se lança a escrever código sem compreender o que pretende. Explico porquê e dou-lhe 3 instruções prontas a usar para o fazer começar por perguntar.
Source: https://ailoot.ai/blog/pt-pt/why-claude-does-the-wrong-thing/
Canonical: https://ailoot.ai/blog/pt-pt/why-claude-does-the-wrong-thing/
Language: pt-PT
Publisher: Ailoot (https://ailoot.ai/)
Translation: guide-201
Revision: sha256-c6f53076b0806362c95e626f973c9c120b0dce621df04b8bc54fd555466bef53
Conclusão principal
O Claude escreve a coisa errada porque se lança a escrever código e preenche as lacunas com aquilo que pensa que queria. Muitas vezes, engana-se. O problema quase nunca está no modelo — até o mais poderoso falha o alvo quando a tarefa é vaga. Resolvo isto com um único passo: primeiro, faço com que o Claude me entreviste, descubra o que pretendo e só depois escreva. Abaixo, encontrará três instruções prontas a usar, que pode copiar e colar.
Para saber mais sobre como utilizar o serviço, consulte a [documentação da Ailoot](https://ailoot.ai/docs/).
## Porque é que o Claude faz a coisa errada?
Conclusão principal
O Claude recebe um pedido curto, preenche de imediato as peças em falta e começa a escrever código com base na sua própria interpretação da tarefa. A interpretação dele é diferente da sua. É assim que acaba com um diff que altera 14 ficheiros quando esperava uma mudança de uma linha. A causa é a diferença entre o que disse e o que tinha em mente. O modelo quase nada tem que ver com isso.
Escreve: «Adiciona filtros à página de produtos.» Na sua cabeça, isso significa algumas caixas de seleção e uma lista atualizada. O Claude ouve o mesmo e decide criar um motor de filtragem completo: o seu próprio armazenamento de estado, lógica separada para atrasar a entrada, sincronização com o URL e uma dúzia de funções auxiliares. Centenas de linhas, quando bastariam alguns parâmetros de URL.
Num caso como este, a conclusão é clara: o agente não cometeu um erro; simplesmente resolveu um problema muito maior do que era necessário. A falha esteve em não descrever o resultado pretendido de forma suficientemente breve e precisa.
A palavra-chave é «intenção». Tem-na na cabeça; o Claude não. Ele vê o texto do seu pedido e tudo o que está no contexto até esse pedido. Depois, preenche as lacunas com suposições. Quanto mais curto for o pedido, mais suposições faz — e mais o resultado se afasta daquilo que queria.
A Anthropic diz isto claramente na documentação do Claude Code:
Se deixar o Claude passar diretamente ao código, poderá resolver o problema errado.
— Claude Code Docs, https://code.claude.com/docs/en/best-practices
Deparei-me com isto no meu próprio projeto. Pedi uma correção para um ecrã de autorização e recebi um diff que afetava metade de um módulo adjacente. A culpa não foi do Claude: dei-lhe uma linha, e ele preencheu o resto por conta própria. Desde então, começo qualquer tarefa maior do que corrigir um erro tipográfico com perguntas — as perguntas que o Claude me faz.
## A culpa é mesmo do modelo — e porque falham até os mais poderosos?
Conclusão principal
O modelo importa menos do que as pessoas tendem a pensar. Perante uma tarefa vaga, até o mais poderoso falha o alvo: recebe as mesmas instruções incompletas e preenche as lacunas com as suas próprias suposições. Os programadores que mantêm o agente sob controlo obtêm os mesmos resultados, quer usem um modelo de topo ou um modelo intermédio. Tudo depende da clareza com que descreve o que pretende. Aqui, a potência do modelo é secundária.
Todas as semanas surge um modelo «mais inteligente» do que o anterior e, de cada vez, parece que é desta que a IA finalmente nos vai compreender com poucas palavras. Não vai. Um modelo mais poderoso escreve código mais depressa e lida melhor com lógica complexa, mas continua sem conseguir ler-lhe os pensamentos. Se a tarefa estiver mal definida, obterá algo muito bem escrito que continua errado.
A conclusão para si é simples. Perseguir o modelo mais recente para que adivinhe melhor é um beco sem saída. É mais barato e fiável aprender a atribuir-lhe tarefas de modo a que não tenha de adivinhar. É disso que trata a próxima secção.
## O que é grilling e como resolve o desalinhamento com a IA?
Conclusão principal
Grilling é quando faz com que a IA o entreviste antes de começar a trabalhar: ela faz perguntas detalhadas sobre a tarefa até chegarem a um entendimento comum. O objetivo é eliminar a falha de comunicação antes da primeira linha de código.
Parece contraintuitivo. Recorremos à IA para fazer as coisas mais depressa e agora dizem-nos para a abrandar e fazê-la começar por perguntar. Mas cinco minutos de perguntas antes de programar podem poupar uma hora de correções depois.
O problema não é apenas ter explicado mal as coisas ao Claude. Muitas vezes, também não pensou bem na tarefa — nos casos a considerar, nos limites e no que é mais importante. O grilling ajuda-o a esclarecer isso através de perguntas. No fim da conversa, tem não só uma tarefa que a IA compreende, mas também a sua própria tarefa finalmente descrita em pormenor.
É assim que funciona a engenharia de contexto: o trabalho principal acontece antes da instrução, não durante. Não está à procura de uma formulação mágica para a instrução; está a explicar antecipadamente ao Claude aquilo de que precisa, até ele compreender sem explicações adicionais.
## Como fazer com que o Claude lhe faça perguntas primeiro?
Conclusão principal
Dê ao Claude uma breve descrição da tarefa e peça-lhe explicitamente que o entreviste antes de começar a trabalhar: peça-lhe que pergunte sobre detalhes, casos extremos e restrições, e que depois reúna tudo num ficheiro de especificação. Esta é a recomendação oficial da Anthropic — a documentação do Claude Code inclui um modelo de instrução pronto a usar. Copie-o, altere a descrição e cole-o no início de uma sessão.
A Anthropic não se limita a permitir esta abordagem; recomenda-a. A documentação tem uma secção chamada «Let Claude interview you», com uma instrução pronta a usar. Eis uma versão prática:
Instrução
Instrução de grilling — faça com que o Claude o entreviste
```
Quero criar [breve descrição da tarefa].
Entreviste-me em pormenor antes de escrever qualquer código. Faça perguntas sobre a implementação, a interface, os casos extremos, os riscos e as compensações. Não faça perguntas óbvias — explore os aspetos complicados em que talvez ainda não tenha pensado.
Faça uma pergunta de cada vez e aguarde pela minha resposta. Para cada pergunta, sugira de imediato a resposta que recomenda.
Continue até termos abordado tudo. Depois, compile uma especificação completa num ficheiro chamado SPEC.md.
```
Três pormenores tornam esta instrução útil em vez de decorativa. Primeiro, «uma pergunta de cada vez». Se a IA lhe despejar dez perguntas de uma só vez, ficará sobrecarregado e responderá superficialmente. Segundo, «sugira a resposta»: não tem de inventar tudo de raiz; pode concordar ou corrigir. Terceiro, «compile uma especificação num ficheiro»: a intenção que a IA extraiu de si transforma-se num documento que não se perde.
A Anthropic descreve os benefícios em termos de esforço:
O tempo dedicado a acertar na especificação é mais valioso do que o tempo passado a observar a implementação.
— Documentação do Claude Code, https://code.claude.com/docs/en/best-practices
Depois da entrevista, abra uma sessão nova e entregue-lhe a especificação concluída. Contexto limpo e intenção claramente expressa — e o Claude acerta à primeira.
## A técnica «prova-me que este é o melhor plano»
Conclusão principal
Não se limite a fazer com que a IA faça perguntas — peça-lhe também que defenda a sua decisão. Acrescento à tarefa um requisito: provar que o plano proposto é o melhor, e não apenas o primeiro que lhe ocorre, e que foi pensado com vários passos de antecedência. Isto tira o Claude do modo «vou fazer algo parecido» e põe-no em modo crítico, a verificar o próprio trabalho antes de investir tempo na implementação.
O grilling revela a sua intenção. Mas a IA tem outro hábito: agarrar-se à primeira solução que parece plausível. A Anthropic chama-lhe a falha de «confiar, mas verificar»: o Claude produz uma implementação plausível que não resiste aos casos extremos. A solução é pedir provas antes do código.
Se não consegue verificar o resultado, não o submeta.
— Anthropic, Claude Code Docs, https://code.claude.com/docs/en/best-practices
Quase sempre acrescento à minha instrução uma secção «prova-o». Eis a formulação exata:
Instrução
Instrução — faça com que a IA defenda o plano
```
Antes de escrever código, analise a tarefa como um crítico.
Encontre 2-3 formas de a resolver. Para cada uma, prove que resolve realmente a minha tarefa, em vez de acrescentar complexidade sem necessidade. Não escreva código só por escrever código.
Depois, escolha uma e prove que é a melhor solução, ponderada com vários passos de antecedência. O que poderá correr mal à medida que o projeto crescer? O que nos está a escapar neste momento?
Só então proponha uma implementação.
```
Sem esta secção, o Claude dá-lhe a primeira opção viável. Com ela, o Claude elimina por si próprio os becos sem saída, explica a sua escolha e permite-lhe ver o seu raciocínio antes de tocar num único ficheiro. Lê um texto curto, que demora dois minutos, em vez de passar uma hora a perceber porque é que o código concluído não funciona como esperado.
## Pré-mortem: peça à IA para encontrar 10 razões para o fracasso antes de começar
Conclusão principal
Um pré-mortem é uma técnica em que pede à IA que imagine que o projeto já falhou e que identifique as razões. O Claude deixa o modo otimista «vou tratar disto» e passa a procurar fragilidades que, de outro modo, só apareceriam depois de uma semana de trabalho. Obtém uma lista de riscos antes de investir tempo no projeto e pode resolvê-los antecipadamente.
Esta é a minha técnica preferida, e é psicológica. Quando pede à IA para «fazer um bom trabalho», ela fica orientada para o sucesso e ignora os problemas. Peça-lhe que imagine o fracasso e ela começa a ver aquilo que antes ignorava. A instrução é curta:
Instrução de pré-mortem — encontre as lacunas antes de começar
```
Imagine que estamos daqui a um ano. O projeto que estamos a planear falhou.
Escreva 10 razões pelas quais isso aconteceu. O que não tivemos em conta no início, o que subestimámos, onde cortámos caminho e que pressupostos se revelaram falsos?
Depois, diga-me o que podemos corrigir agora para lidar com cada razão.
```
Uso esta instrução antes de aprovar o plano. Metade das razões acaba por ser absurda, mas a outra metade corresponde a obstáculos reais que teria encontrado uma semana mais tarde. Resolvê-los na fase de planeamento demora dez minutos. Encontrá-los num projeto concluído custa vários dias de investigação.
A combinação é simples: o grilling revela a intenção, «prova-o» defende a decisão e o pré-mortem encontra as lacunas. Três textos curtos que cola antes de escrever código. Transformam o Claude de um executor apressado num colaborador que pensa primeiro.
## Porque é que um contexto sobrecarregado faz o Claude parecer estúpido?
Conclusão principal
O Claude tem uma janela de contexto limitada — a quantidade de informação que consegue manter em mente ao mesmo tempo. Quando a janela está mais de metade cheia, começa a perder pormenores importantes, a confundir acordos anteriores e a preencher lacunas em vez de se lembrar. Uma sessão longa sobre tudo e mais alguma coisa é uma razão comum para a IA fazer, ao fim do dia, algo completamente diferente do que combinaram de manhã.
Até uma tarefa perfeitamente formulada se desmorona se trabalhar nela num contexto desorganizado. Funciona assim: cada novo pedido que faz leva todo o histórico da conversa para o contexto de trabalho do Claude. Quanto mais longa a sessão, mais depressa a janela se enche. Mantenha-a, no máximo, meio cheia; a partir daí, a IA começa a comportar-se de forma estúpida e a perder coisas importantes que discutiram no início.
Eis a regra que mais me poupa frustração: uma tarefa, uma conversa. Concluiu uma função? Feche a conversa e abra uma nova para a tarefa seguinte. Sim, por vezes é mais conveniente fazer tudo numa só janela, mas pagará por isso com perda de contexto e respostas fora do assunto.
A Anthropic chama a este modo de falha uma «sessão de gaveta da tralha». A solução é simples: use `/clear` entre tarefas sem relação para limpar a janela e evitar levar a confusão da tarefa anterior para a nova.
Se faz sessões longas e não percebe para onde vão o dinheiro e a atenção da IA, explico isso separadamente no guia sobre [para onde vão os tokens do Claude Code](https://ailoot.ai/blog/pt-pt/where-claude-code-tokens-go/). E reuni os fundamentos do contexto persistente, que o Claude lê em cada arranque, no guia sobre [como configurar o CLAUDE.md](https://ailoot.ai/blog/pt-pt/claude-md-template/).
## Grilling ou Plan Mode — qual é a diferença e como se complementam?
Conclusão principal
O grilling e o Plan Mode resolvem metades diferentes do mesmo problema. O grilling revela a sua intenção através de perguntas, antes de existir um plano. O Plan Mode pega numa tarefa que já foi compreendida e mostra-lhe um plano de alterações, sem tocar em nada até o aprovar. Funcionam melhor em conjunto: primeiro, o grilling clarifica o que vamos construir; depois, o Plan Mode mostra exatamente como.
As pessoas confundem muitas vezes estas duas técnicas ou presumem que só precisam de uma. Na prática, pertencem a momentos diferentes do processo.
| Funcionalidade | Grilling | Plan Mode |
|----|----|----|
| Quando acontece | Antes do plano — clarifica a intenção | Depois — cria um plano de alterações |
| Quem pergunta a quem | A IA entrevista-o | Lê e aprova o plano |
| O que obtém | Uma especificação da tarefa | Um plano de alterações ficheiro a ficheiro |
| Principal benefício | Evita «não era isto que eu queria» | Evita «não mexas em mais nada» |
A Anthropic descreve um fluxo de trabalho canónico de quatro fases: primeiro Explore (o Claude analisa e faz perguntas), depois Plan (cria um plano sem fazer alterações), a seguir Implement (escreve código de acordo com o plano) e, por fim, Commit (regista o resultado). O grilling acontece na primeira fase; o Plan Mode, na segunda. Para uma análise completa da segunda fase, consulte o guia sobre [Plan Mode no Claude Code](https://ailoot.ai/blog/pt-pt/claude-code-plan-mode/).
Uma ressalva importante da própria Anthropic: não sobrecarregue tarefas pequenas com este processo.
Se consegue descrever uma alteração numa frase, salte o plano.
— Documentação oficial do Claude Code, https://code.claude.com/docs/en/best-practices
Para corrigir um erro tipográfico, mudar um nome ou fazer uma alteração de uma linha, descreva-a diretamente, sem entrevistas nem planos. O grilling compensa em tarefas ambíguas em que o erro tem custos. Nas tarefas triviais, só o atrasa.
## 5 erros na formulação de tarefas que levam a IA a fazer a coisa errada
Conclusão principal
Quase todos os erros da IA se resumem a cinco falhas na formulação da tarefa: uma frase vaga, ausência de restrições, «escreve código» sem uma fase de «compreende primeiro», ausência de uma definição de «concluído» e uma sessão interminável para tudo. Cada uma leva o Claude a preencher a tarefa com suposições. Abaixo, verá como se manifesta cada erro e como o substituir.
Resumi numa tabela as armadilhas mais comuns. À esquerda está aquilo que as pessoas costumam fazer e que corre mal; à direita, o que devem fazer em vez disso.
| Erro | Como soa | O que fazer em vez disso |
|----|----|----|
| Frase vaga | «Melhora o dashboard» | Descreva a tarefa e comece uma sessão de grilling — deixe a IA esclarecer os detalhes com perguntas |
| Sem restrições | «Adiciona autorização» | Diga o que não pode deixar de funcionar, que bibliotecas não deve adicionar e o que está fora do âmbito |
| «Escreve código» logo de início | Instrução — e começa a programar | Primeiro «compreende e pergunta», depois escreve código |
| Sem definição de «concluído» | Espera que a IA adivinhe o resultado | Dê um exemplo, uma captura de ecrã de referência ou um teste que mostre o que significa «funcionar» |
| Uma sessão para tudo | Passa o dia inteiro numa conversa | Uma tarefa, uma conversa nova, para o contexto não ficar desorganizado |
Reveja a última instrução à qual a IA respondeu mal. É quase certo que um destes cinco erros esteve na origem. O mais comum é o primeiro: deu-lhe uma frase curta e esperou que o Claude completasse corretamente o resto. Completou-o — só que não da maneira que tinha em mente.
## E agora: crie um sistema para a IA o compreender com poucas palavras
Conclusão principal
Instruções individuais resolvem tarefas individuais. Para que a IA o compreenda sem explicações longas de cada vez, precisa de um sistema: o grilling revela a intenção para cada tarefa, um Second Brain guarda o conhecimento do projeto e a engenharia de contexto liga tudo o que o Claude lê antes da instrução. Assim, desaparece a razão pela qual faz a coisa errada: tem sempre contexto suficiente para não precisar de adivinhar.
As três instruções deste guia — grilling, «prova-o» e o pré-mortem — resolvem a tarefa específica em mãos. Isso já é muito: deixa de receber um diff de 14 ficheiros quando só queria uma alteração de uma linha.
Mas o grilling tem limites. Descobrir a sua intenção de raiz de cada vez demora muito tempo. A verdadeira mudança acontece quando parte do contexto está sempre disponível: numa pasta com conhecimento sobre o projeto, num ficheiro CLAUDE.md que o Claude lê em cada arranque e na sua metodologia codificada em skills. Então, a IA chega à tarefa já a conhecer o seu negócio, os seus objetivos e o seu estilo — e compreende-o com poucas palavras, porque preparou metade do contexto com antecedência.
Uma análise recente da Anthropic mostra quanto trabalho isto representa: os programadores usam IA em cerca de 60% do seu trabalho, mas só podem confiar plenamente nela em 0-20% das tarefas. O restante exige a sua compreensão, supervisão e capacidade de explicar o que deve ser construído. É essa a competência que vale a pena desenvolver, em vez de perseguir o modelo mais inteligente.
### Fontes
- [Claude Code Docs - Best Practices (Let Claude interview you, plan mode)](https://code.claude.com/docs/en/best-practices)
- [Anthropic - 2026 Agentic Coding Trends Report](https://resources.anthropic.com/2026-agentic-coding-trends-report)
Conheça a [Ailoot](https://ailoot.ai/).
## Perguntas frequentes
### Quando uso o prompt de entrevista antes de programar?
Quando resultado, casos limite ou restrições são incertos e erros seriam caros. Peça uma pergunta de cada vez e guarde o acordo em SPEC.md; um erro de escrita ou alteração clara de uma linha pode ser pedido diretamente.
### O que verifico antes de aceitar o plano?
Peça duas ou três abordagens e compare o cumprimento da especificação e restrições. Execute depois o prompt de pré-análise de falhas, reveja as causas e trate riscos pertinentes antes de implementar.
## 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.