Como usar prompts no Claude Code: um guia prático para melhores resultados

Claude Code não é um chatbot, então pare de usá-lo como um

A maioria das pessoas chega ao Claude Code a partir de uma janela de chat, e o usa da mesma forma: uma solicitação vaga, uma parede de ida e volta, muito "não, não assim." Funciona na maioria das vezes, e também é a forma mais lenta de usar a ferramenta.

O modelo mental é diferente. Como a Anthropic coloca em seu guia de melhores práticas, o Claude Code "explora, planeja e implementa" por conta própria: lê arquivos, executa comandos e trabalha em um problema enquanto você observa, redireciona ou vai embora. Então seu trabalho deixa de ser "digitar a resposta" e se torna "preparar o trabalho". Sean Tierney, que passou um ano construindo aplicativos reais com a ferramenta, descreve como aprender "a agir como o armador, não o quarterback."

Essa reformulação é o artigo todo. Tudo abaixo é uma forma concreta de preparar o trabalho para que o Claude acerte na primeira vez em vez da quarta.

Seja específico: descreva o resultado, não os passos

"Quanto mais precisas forem suas instruções, menos correções você precisará", observa a Anthropic. "Claude pode inferir intenção, mas não pode ler sua mente." Esta é a única mudança de maior alavancagem que você pode fazer, e não custa nada.

O antes e depois no próprio guia da Anthropic torna óbvio. Não diga "adicione testes para foo.py." Diga: "escreva um teste para foo.py cobrindo o caso extremo onde o usuário está desconectado. sem mocks." Não diga "corrija o bug de login." Diga "usuários relatam que o login falha após o tempo limite da sessão, verifique o fluxo de autenticação em src/auth/, especialmente a atualização de tokens, escreva um teste com falha que reproduza o problema, depois corrija-o."

O truque é declarar o resultado e as restrições, depois deixar o Claude encontrar o onde. O centro de ajuda da Anthropic chama isso de "Declare o resultado, não os passos": não "abra userService.ts, encontre a função validate, adicione uma verificação nula na linha 42", mas "usuários sem e-mail estão quebrando a validação, faça-a lidar com isso graciosamente e adicione um teste." Você não está microgerenciando o diff, está descrevendo o mundo que quer que seja verdade.

Uma ressalva que vale manter: vago está bem quando você está explorando. "O que você melhoraria neste arquivo?" é um ótimo prompt precisamente porque revela coisas que você não pensaria em perguntar. A especificidade é para quando você sabe o que quer, não para explorar.

Dê a ele o material bruto: arquivos, capturas de tela, URLs, logs canalizados

Um prompt preciso ainda precisa de material bruto. O Claude Code tem várias formas de extrair contexto diretamente para a conversa, e usá-las supera descrever as coisas da memória:

• Referencie arquivos com @. Digitar @src/auth/login.ts faz o Claude ler o arquivo antes de responder. Quando você já conhece o caminho, isso é mais rápido e barato do que deixá-lo pesquisar. É também por isso que uma estrutura de repositório limpa compensa, e por que artigos como navegar uma base de código com o Claude Code importam.
• Cole imagens. Arraste ou cole uma captura de tela de um design ou um erro, depois diga "implemente este design, tire uma captura de tela do resultado e liste as diferenças." O Claude pode ver a interface do usuário.
• Dê URLs. Aponte-o para uma página de documentação ou uma referência de API. Você pode colocar domínios que usa frequentemente na lista de permissões com /permissions.
• Canalise dados. cat error.log | claude envia o arquivo diretamente. Esta é a porta de entrada para usar o Claude Code no terminal como uma ferramenta Unix composável.

O centro de ajuda tem uma regra direta anexada a isso: dê a ele o erro, literalmente. Cole o stack trace completo em vez de resumi-lo. O nome exato do arquivo, o número de linha e a mensagem são o que permitem ao Claude pular para o código certo em vez de adivinhar. Para sessões mais complicadas, nosso guia de depuração com Claude Code aprofunda mais.

Faça-o planejar antes de escrever uma linha de código

Isso é o que separa as pessoas que gostam do Claude Code das que o amam. "Deixar o Claude pular direto para a codificação pode produzir código que resolve o problema errado", avisa a Anthropic. A solução é um ciclo de quatro fases: explorar, planejar, implementar, confirmar.

As primeiras duas fases acontecem no modo de planejamento, onde o Claude lê arquivos e propõe uma abordagem, mas não faz nenhuma edição. Você entra com Shift+Tab (pressione duas vezes para chegar ao modo de planejamento), ou inicie uma sessão com claude --permission-mode plan. No VS Code, o plano se abre como um documento markdown em que você pode comentar inline; no terminal, Ctrl+G abre o plano em seu editor para que você possa editá-lo diretamente antes que o Claude prossiga. Você pode ler a configuração completa em nosso guia de modo interativo.

O consenso dos praticantes é ainda mais forte do que o da Anthropic. Aqui está Sean Tierney, que constrói com a ferramenta diariamente:

"Sempre comece no Modo de Plano. Resista à tentação de mergulhar diretamente na implementação. Você pode dar ao CC exatamente o mesmo prompt, mas começando primeiro no modo de plano e fazendo-o pensar nas coisas antecipadamente, dará um resultado muito melhor toda vez, pois terá que propor e defender um plano antecipadamente. Essa gratificação levemente atrasada versus se precipitar na implementação vale bem os 2 minutos de espera."

Sean Tierney, Vibecode Lisboa

Quando não planejar? A regra geral da Anthropic é a que eu uso: se você pudesse descrever o diff em uma frase, pule o plano. Um erro de digitação, uma linha de log, um renomeamento de variável, apenas peça. O planejamento vale a pena quando você não tem certeza sobre a abordagem, a mudança abrange múltiplos arquivos ou você ainda não conhece bem o código.

Dê ao Claude uma forma de verificar seu próprio trabalho

Aqui está o modo de falha sobre o qual ninguém avisa: o Claude para quando o trabalho parece feito. Sem uma verificação executável, "parece feito" é o único sinal que ele tem, o que significa que você se torna o loop de verificação, relendo cada diff à mão.

A solução é dar a ele algo que retorne aprovado ou reprovado: um conjunto de testes, uma compilação, um linter, um script que compara a saída com um fixture, ou uma captura de tela para comparar com um design. "Dê ao Claude uma verificação que ele possa executar", diz a Anthropic. "É a diferença entre uma sessão que você observa e uma da qual você pode se afastar." Então a verificação pertence ao prompt: "escreva uma função validateEmail, casos de teste de exemplo: user@example.com é true, invalid é false, user@.com é false, execute os testes após implementar."

É por isso que o prompting orientado a testes funciona tão bem. Peça ao Claude para escrever os testes primeiro, confirme que falham, depois implemente até que passem. E peça a ele para mostrar evidências em vez de afirmar sucesso: a saída do teste, o comando que executou, a captura de tela. Revisar as evidências é mais rápido do que executar novamente a verificação você mesmo. Se você quiser que isso seja mais rígido, pode escalá-lo para um hook determinístico que dispara quando o Claude tenta terminar, o que nossa referência de hooks explica.

Trate sua janela de contexto como um orçamento

Quase todo problema de prompting no Claude Code remonta a uma coisa: a janela de contexto contém toda a sessão (cada mensagem, cada leitura de arquivo, cada saída de comando) e o desempenho do modelo degrada à medida que essa janela se enche. Uma única sessão de depuração pode queimar dezenas de milhares de tokens, e uma vez que está cheia, o Claude começa a "esquecer" suas instruções anteriores.

Então gerencie-a deliberadamente:

• /clear entre tarefas não relacionadas. Este é o principal. Tierney o chama de "opção nuclear, use liberalmente entre features." Uma janela limpa com um prompt preciso supera uma longa cheia de becos sem saída.
• /compact <instruções> quando quiser continuar mas eliminar o excesso, por exemplo /compact foque nas mudanças de API.
• Delegue para subagentes. Investigar uma base de código grande preenche sua janela com leituras de arquivos. Um subagente faz essa leitura em sua própria janela e relata apenas o resumo. "Como o contexto é sua restrição fundamental, os subagentes são uma das ferramentas mais poderosas disponíveis", diz a Anthropic. Apenas diga "use um subagente para investigar como lidamos com a atualização de tokens." Nosso guia sobre subagentes do Claude Code que você pode construir tem mais padrões.

Se você quiser ver exatamente o que está consumindo sua janela, /context visualiza o que está carregado, incluindo quais ferramentas conectadas são as que mais consomem tokens.

Corrija rapidamente e saiba quando recomeçar

A Anthropic é clara que "os melhores resultados vêm de ciclos de feedback apertados." Você não espera o Claude terminar um caminho errado para explicar tudo de novo. As ferramentas de correção:

• Esc para o Claude no meio da ação. O contexto é preservado, então você pode redirecionar na hora.
• Esc Esc (ou /rewind) abre o menu de retrocesso para restaurar um estado anterior de conversa ou código.
• "Desfaça isso" faz o Claude reverter suas próprias mudanças.

Há uma nota de tom aqui que importa mais do que soa: corrija-o como um colega, não como um mecanismo de busca. Você não redigita toda a solicitação, apenas diz o que está errado, como "isso muda a API pública, mantenha a mesma assinatura", e o Claude ajusta apenas isso. E a heurística em que mais me apoio: se você corrigiu o Claude mais de duas vezes no mesmo problema, o contexto está contaminado com abordagens fracassadas. Execute /clear e comece de novo com um prompt melhor que incorpore o que você acabou de aprender. Uma sessão limpa quase sempre supera uma longa que carrega correções acumuladas.

Escreva um CLAUDE.md: o prompt que você escreve apenas uma vez

Tudo até agora é por sessão. Um arquivo CLAUDE.md é a parte do seu prompt que persiste. O Claude o lê no início de cada conversa, então é onde vive o contexto permanente do seu projeto: os comandos de compilação que ele não pode adivinhar, suas regras de estilo de código, etiqueta do repositório, as peculiaridades do ambiente de desenvolvimento, os problemas. O centro de ajuda o chama de "o briefing que você daria a um novo membro capaz da equipe em sua primeira manhã."

Execute /init para gerar um inicial a partir do seu projeto, depois mantenha-o enxuto. O aviso da Anthropic é enfático: "Arquivos CLAUDE.md sobrecarregados fazem o Claude ignorar suas instruções reais." Para cada linha, pergunte "remover isso faria o Claude cometer um erro?" Se não, corte. Adicione uma regra quando o Claude errar duas vezes, pode trimestralmente e confirme o arquivo para que toda a equipe contribua. A história completa de configuração, incluindo onde o arquivo vive e como ele se mescla entre diretórios, está em nosso guia de configuração do Claude Code e na referência de settings.json. Para fluxos de trabalho repetíveis, a mesma lógica se estende aos comandos slash.

Os hábitos de prompting que desperdiçam silenciosamente seus tokens

A maioria das sessões desperdiçadas vem de um punhado de erros repetíveis. A Anthropic nomeia cinco, e a solução para cada um é um hábito de prompting:

O meta-ponto com que a Anthropic fecha vale a pena guardar: estes são pontos de partida, não leis. Às vezes você deve deixar o contexto se acumular (quando está fundo em um problema difícil), pular o plano (trabalho exploratório), ou lançar um prompt vago (para ver como ele interpreta antes de restringir). Observe o que acontece quando a saída é ótima, e pergunte por quê quando tem dificuldades. É assim que você constrói a intuição que nenhuma lista de verificação pode substituir. Se você quer um conjunto curado, nosso resumo de melhores práticas do Claude Code coleta as que sobreviveram ao contato com projetos reais.

O que isso tem a ver com IA que responde tickets de suporte

Aqui está o que não esperava quando comecei a usar o Claude Code: a disciplina de prompting é a mesma disciplina que usamos para colocar IA em uma fila de suporte ao vivo. Dê ao agente o contexto certo. Delimite o que ele pode tocar. Faça-o verificar antes de agir. Corrija rapidamente e capture a lição.

Aprendi essa ordem do jeito difícil. No início, assistimos bots que soavam confiantes entregando silenciosamente respostas erradas aos clientes, por isso agora simulamos cada lançamento contra os tickets históricos de uma empresa antes de uma única resposta ao vivo sair. Esse é o modo de planejamento para suporte: ler o mundo, propor como você vai lidar com isso, obter aprovação, depois agir. Quando a Gridwise o executou, o agente resolveu 73% de suas solicitações de nível 1 no primeiro mês, e os resultados apareceram durante um teste de 7 dias. O número veio da configuração, não de um modelo mais inteligente.

Se você escreve conteúdo da mesma forma, o paralelo também vale para a escrita com IA: o escritor de blog do eesel AI é, por baixo dos panos, um agente que você informa e verifica em vez de uma caixa de chat com a qual você luta.

Experimente o eesel

O eesel AI coloca essa mesma disciplina agêntica para trabalhar no seu helpdesk. Você conecta suas ferramentas existentes (Zendesk, Freshdesk, HubSpot, Gorgias, Slack e mais de 100), e o agente aprende com seus tickets passados e documentos de ajuda no primeiro dia. A parte que se mapeia diretamente para tudo acima: você o configura em linguagem simples e o executa em simulação contra milhares de seus tickets reais passados antes que ele responda a um cliente, para que você veja exatamente o que teria dito e onde teria escalado.

É a mesma lição de usar prompts no Claude Code, apontada para sua fila de suporte: o agente é tão bom quanto o contexto e as barreiras que você lhe dá. Você pode Experimentar o eesel grátis, sem cartão de crédito, e vê-lo executar contra seu próprio histórico antes de confiar a ele um cliente.