Claude Code respondendo genérico demais: o que falta no seu pedido

Fala aí, beleza? Aquela resposta que chega certa no geral e completamente inútil no seu caso é o sintoma mais comum de quem começou no Claude Code agora

Ele explica o conceito direitinho, sugere uma estrutura que existe em qualquer projeto do mundo e não toca no SEU problema

Aí bate aquela sensação de "esse negócio é hype", né?

Só que na maioria das vezes o problema não é o modelo, é o pedido: sem alvo, sem restrição e sem forma dele checar o resultado

A documentação oficial de boas práticas fala isso com todas as letras: "Claude can infer intent, but it can’t read your mind", ou seja, ele infere a intenção mas não lê sua mente, e orienta você a referenciar arquivos específicos, citar restrições e apontar padrões de exemplo

Quanto mais precisa a instrução, menos correção depois

Esse post aqui é diagnóstico com correção de pedido, sintoma por sintoma

Não é lista de prompt mágico, dessas coisas toscas que prometem desbloquear a IA 😛

Pré-inscrição Formação Claude Code

Domine o Claude Code do básico ao avançado

Você vai aprender a criar sistemas completos com Claude Code, sem precisar ser programador. Inscreva-se para ter acesso a um desconto de lançamento e bônus especiais!

Quero minha vaga

Sintoma 1: ele responde sobre um código que não é o seu

O sintoma: você pede ajuda num bug e vem uma explicação genérica sobre "seu componente de autenticação", com um exemplo inventado que não existe no repositório

A causa: o pedido DESCREVE onde o código mora em vez de APONTAR o arquivo

"lá no meu login" não é endereço, é pista

A solução: no Claude Code você referencia arquivo com @, e ele lê o arquivo antes de responder

Ruim:
tem um bug no login, acho que é na parte de autenticação

Bom:
@src/auth/login.ts está devolvendo 401 mesmo com a senha correta
leia o arquivo e me diga onde a comparação de hash está falhando

E dá pra referenciar vários arquivos na mesma mensagem, no estilo @file1.js and @file2.js, quando o bug mora na conversa entre dois arquivos

Pra não repetir: comece todo pedido nomeando os arquivos e as interfaces envolvidos

A doc chama isso de spec autocontida, e é o mesmo princípio: se a informação não está no pedido, ele preenche o buraco com o caso médio da internet

Sintoma 2: a solução funciona mas mexe em tudo que você não pediu

O sintoma: você pediu um ajuste de validação e voltou uma refatoração completa, biblioteca nova instalada e três arquivos tocados sem necessidade

Funciona? Funciona

Você queria isso? Não haha

A causa: o pedido não declarou restrição nenhuma e, principalmente, não disse o que está FORA de escopo

Sem limite, tudo é escopo

A solução: citar as restrições e escrever explicitamente o que não deve ser alterado

A doc lista justamente isso como parte de uma spec útil: nomear os arquivos e interfaces envolvidos, declarar o que está fora de escopo e terminar com um passo de verificação ponta a ponta

Ajuste só a validação de e-mail em @src/forms/signup.ts

Fora de escopo: não altere @src/forms/schema.ts, não instale
biblioteca nova, não renomeie função exportada

Pra não repetir: padrão de código e biblioteca preferida não deveriam ser digitados a cada pedido

Esse tipo de coisa mora no CLAUDE.md da raiz do projeto, que o Claude Code lê no início de toda sessão (volto nele no sintoma 6)

Sintoma 3: a resposta vem no formato errado toda vez

O sintoma: você queria um diff pra aplicar, veio um textão explicando

Você queria uma tabela comparando, veio parágrafo

E aí você gasta o dobro do tempo traduzindo a resposta pro formato que precisava

A causa: o pedido descreveu o CONTEÚDO e esqueceu a FORMA

Como ele não viu a forma que você espera, ele escolhe uma

A solução: apontar padrões de exemplo do próprio projeto

A doc da plataforma Claude coloca exemplos como uma das formas mais confiáveis de direcionar formato de saída, tom e estrutura da resposta, e reforça que poucos exemplos bem elaborados melhoram precisão e consistência

É a diferença entre dizer "escreva no nosso estilo" e mostrar um arquivo que já está no estilo

A lógica é a mesma de quando você vai importar seu design system no Claude Design: referência concreta vale MUITO mais que adjetivo

Pra não repetir: guarde o exemplo canônico dentro do repositório e referencie com @

Siga exatamente o formato de @src/services/user.service.ts
na hora de criar o novo service

Sintoma 4: ele para na primeira tentativa e você vira o revisor

O sintoma: a entrega parece ótima, o raciocínio fecha, e aí você roda e quebra

O trabalho de verificar sobrou todo pra você

A causa: o pedido não deu critério de aceite nem uma forma dele checar o próprio trabalho

E se liga nisso: a doc oficial classifica dar ao Claude uma forma de checar o próprio trabalho (testes, screenshots ou saídas esperadas) como "the single highest-leverage thing you can do", a coisa de maior alavancagem que você pode fazer no pedido

Não é detalhe fino, é o item de maior impacto

A solução: incluir o teste, o screenshot ou a saída esperada, e pedir explicitamente pra rodar, testar, comparar ou verificar dentro do MESMO prompt

A doc é clara: pedir isso no mesmo prompt faz ele iterar em vez de parar depois de uma tentativa

Corrija o parser em @src/utils/parse-date.ts

Entrada "12/08/2026" tem que virar 2026-08-12
Rode os testes com npm test e ajuste até passar

Pra não repetir: termine o pedido com um passo de verificação ponta a ponta, aquele que prova que a funcionalidade funciona de verdade

Um pedido sem critério de aceite é um pedido que sempre volta pra sua mesa

Sintoma 5: o pedido é grande demais para caber em uma frase

O sintoma: tarefa complexa, resposta genérica

E olha, muitas vezes é honesto: nem você tinha o recorte fechado na cabeça quando apertou enter

A causa: foi direto pro código sem alinhar direção antes

A solução: plan mode

O modo de planejamento faz ele descrever o que vai fazer e esperar sua aprovação antes de alterar arquivos

1. Aperte Shift+Tab até a barra de status mostrar ⏸ plan mode on

O erro comum aqui: apertar uma vez só e achar que entrou

O ciclo do Shift+Tab é default → acceptEdits → plan, então você passa pelo acceptEdits no caminho, e é bom conferir a barra antes de mandar o pedido

2. Se preferir já começar a sessão nele, use:

claude --permission-mode plan

3. Leia o plano, discuta e refine na conversa

4. Só depois libere a implementação

A doc recomenda exatamente essa abordagem em duas fases pra problemas complexos: usar o plan mode pra analisar o codebase, revisar e refinar o plano, e só então deixar implementar

E afirma que isso produz resultado melhor do que ir direto pro código, além de evitar retrabalho caro quando a direção inicial está errada

Pra não repetir: tarefa grande entra por plano, não por prompt único

Sintoma 6: você corrige a mesma coisa em toda sessão

O sintoma: você explica pela quinta vez que o projeto usa tal padrão, ele acerta, e amanhã o desvio volta igualzinho

A causa: a correção ficou na CONVERSA, não no PROJETO

Conversa acaba, projeto fica

A solução: o CLAUDE.md, um arquivo markdown na raiz do projeto que o Claude Code lê no início de toda sessão

É o lugar de padrões de código, decisões de arquitetura, bibliotecas preferidas e checklist de revisão

Tome cuidado com o tamanho! Os arquivos CLAUDE.md são carregados por inteiro independente do tamanho, mas arquivo mais curto produz melhor aderência

Acima de 200 linhas ele consome mais contexto e pode reduzir a aderência, ou seja, escrever mais pode te fazer ser menos obedecido, engraçado isso né? 😀

Junto disso existe a memória automática, as notas que o próprio Claude escreve a partir das suas correções e preferências

Ela vem LIGADA por padrão, então são dois mecanismos levando conhecimento entre sessões: o que você escreve e o que ele anota

Pra não repetir: rode /clear entre tarefas não relacionadas

Ele reseta a conversa pra contexto vazio, e os prompts seguintes começam sem o histórico daquele papo

E calma que não é perda: a conversa anterior NÃO some, ela continua salva em disco e pode ser retomada pelo session ID, o que muda é só o que entra no contexto dos próximos prompts

A memória do projeto continua de pé, o que sai da frente é só o entulho da tarefa velha

Três pedidos reescritos: antes e depois

Bora ver na prática?

Repare que o "depois" não é um textão, é o mesmo pedido com alvo, restrição, forma e verificação

Caso 1: bug em arquivo específico

Antes:
o upload de imagem tá quebrando às vezes

Depois:
@src/upload/handler.ts falha quando o arquivo passa de 5MB
leia o arquivo, me mostre onde o limite é aplicado e proponha
o ajuste sem mexer em @src/upload/routes.ts
depois rode npm test e me diga o que passou

Melhorou porque ele lê o arquivo antes de opinar, sabe o que NÃO tocar e tem como conferir o resultado sozinho

Caso 2: ajuste com restrição de escopo

Antes:
melhora esse formulário

Depois:
em @src/components/ContactForm.tsx, adicione validação
de telefone seguindo o padrão que já existe em
@src/components/EmailField.tsx
fora de escopo: estilos, biblioteca nova e o schema

Aqui entra o exemplo canônico como referência de forma, que é o que evita ele inventar um padrão próprio

E tem outro jeito de dar contexto rico que a doc recomenda e quase ninguém usa: colar ou arrastar imagem direto no prompt (um print do erro na tela, um mock do layout) e passar URLs de documentação e referências de API

Pra domínio que você usa com frequência, a doc indica colocar na allowlist pelo /permissions

Caso 3: análise a partir de log

Quando o material é um arquivo grande, não precisa copiar e colar no chat

Dá pra alimentar o Claude Code por pipe no terminal:

cat error.log | claude

O erro comum deste passo: mandar o log e não dizer o que você quer dele

Log sozinho gera resumo genérico, então diga o alvo ("agrupe os erros por origem e aponte o mais frequente") e o que fazer com a conclusão

Vale o mesmo raciocínio quando você quer usar o Claude Code pra achar falhas de segurança: pedido com alvo e critério, não "dá uma olhada aí"

Conclusão: o checklist de 4 linhas antes de apertar enter

Pedido bom não é pedido longo, é pedido completo

Antes de apertar enter, passa esses quatro:

1. Alvo: qual arquivo? Referencia com @ em vez de descrever onde o código mora
2. Restrição: o que NÃO pode ser alterado, o que está fora de escopo
3. Forma: qual exemplo do próprio projeto ele deve seguir
4. Verificação: o que ele roda, testa ou compara pra provar que funcionou

É isso que a doc resume como instrução precisa gerando menos correção depois

Se você quer começar por um passo só hoje, começa por dois: escreva um CLAUDE.md curto na raiz com os padrões que você mais repete, e use o plan mode na próxima tarefa complexa em vez de ir direto pro código

O resto do checklist vira hábito rápido, se liga…

Até o próximo post! =)