Nos capítulos anteriores você aprendeu a mecânica de uma sessão e a explorar um projeto sem alterar nada. Neste capítulo, você vai aprender a redigir pedidos que geram o resultado correto na primeira ou na segunda tentativa. Ao final, saberá ser específico sobre o que quer e sobre o que não quer, fornecer o contexto certo, definir quando uma tarefa está pronta, dividir trabalho grande em passos, pedir um plano antes de executar e corrigir o rumo com poucas palavras.
Por que a instrução decide o resultado
O Claude Code é muito bom em executar o que foi pedido. O problema é que ele preenche as lacunas do pedido com suposições. Quando você escreve pouco, ele adivinha muito, e cada adivinhação errada vira uma rodada extra de correção que consome janela de contexto e paciência. Pense na instrução como um bom ticket entregue a um colega recém-chegado ao time: ela diz o que fazer, onde fazer, quais restrições respeitar e como saber que terminou. Os exemplos deste capítulo usam o pequeno projeto de lista de tarefas em Node.js que você conheceu no capítulo dois.
Seja específico sobre o resultado e sobre o que não deve ser tocado
Compare dois pedidos para a mesma necessidade. O pedido ruim é curto demais:
Melhora a validação das tarefas.
Com essa frase, o Claude Code costuma tocar em três ou quatro arquivos, adicionar uma biblioteca de validação que o projeto não usava e trocar as mensagens de erro por textos em inglês. Nada disso foi pedido, mas nada disso foi proibido. Agora o pedido bom:
No arquivo @src/tarefas.js, na função criarTarefa, rejeite títulos vazios ou com mais de cem caracteres, lançando um Error com a mensagem “título inválido”. Não altere a assinatura da função, não adicione dependências e não mexa em outros arquivos.
O resultado é um diff de poucas linhas, exatamente onde você esperava, fácil de revisar e aprovar. Repare que dizer o que não pode ser tocado é tão importante quanto dizer o que deve ser feito. Sempre que houver algo frágil, sensível ou fora do escopo, declare isso explicitamente.
- Ouça o áudio com a tela desligada
- Ganhe Certificado após a conclusão
- + de 5000 cursos para você explorar!
Baixar o aplicativo
Forneça contexto: arquivos, erros e exemplos de estilo
Você já sabe referenciar arquivos com o arroba. Use isso sempre que souber onde o trabalho acontece, porque poupa a busca e evita que a ferramenta edite um arquivo parecido, mas errado. O segundo tipo de contexto é a mensagem de erro. Um pedido ruim diz apenas “está dando erro quando salvo uma tarefa”. Um pedido bom cola a mensagem completa e o stack trace, sem parafrasear, e informa o comando que produziu o erro. Antes de colar, revise o texto e remova dados sensíveis que costumam aparecer em logs, como tokens, senhas, chaves de API, strings de conexão e dados pessoais. O Claude Code lê o rastro, vai direto ao arquivo e à linha indicados e economiza várias rodadas de investigação.
O terceiro tipo de contexto é um exemplo de código existente para seguir o estilo. Se você pedir “crie a rota de categorias seguindo o mesmo padrão de @src/rotas/usuarios.js, inclusive o tratamento de erros e o formato de resposta”, o código novo nasce parecido com o que já existe. Sem essa referência, cada arquivo gerado pode adotar um estilo diferente, e o projeto vai perdendo consistência.
Defina critérios de pronto
Sem um critério claro, a ferramenta tende a declarar a tarefa concluída assim que o código parece correto. Um critério de pronto é uma verificação objetiva que você e o Claude Code podem executar. Por exemplo:
Considere a tarefa concluída apenas quando npm test passar sem falhas e quando node src/index.js iniciar sem erros no terminal.
Com isso, ele roda os testes, lê o resultado, corrige o que falhou e só então informa que terminou. Bons critérios de pronto são coisas como testes passando, um comando executando sem erro, uma saída específica aparecendo no console ou um linter sem avisos. Critérios vagos, como “funcionar bem”, não servem porque não podem ser verificados.
Divida tarefas grandes e peça um plano antes
Um pedido como “adicione autenticação ao projeto” envolve modelo de usuário, hash de senha, rota de login, geração de token e proteção das rotas existentes. Entregue tudo isso de uma vez e você receberá um diff enorme, difícil de revisar e provavelmente com decisões que você não tomaria. O caminho seguro tem dois movimentos.
Primeiro, peça um plano. Você pode entrar no modo de planejamento pressionando Shift Tab, que alterna entre os modos e em geral precisa ser pressionado mais de uma vez até o rodapé do terminal indicar o modo de planejamento, como viu no capítulo dois, ou simplesmente escrever “antes de alterar qualquer arquivo, me apresente um plano com os passos, os arquivos que serão tocados e as decisões que precisam da minha confirmação”. Leia o plano com atenção, corte o que não quer, ajuste a ordem e só depois autorize.
Segundo, execute um passo por vez. Peça “implemente apenas o passo um do plano” e revise o diff. Quando estiver satisfeito, siga para o próximo. Passos pequenos geram diffs pequenos, e diffs pequenos são os únicos que uma pessoa consegue revisar de verdade.
Itere com feedback curto e direto
Quando o resultado diverge do esperado, a tentação é reescrever o pedido inteiro ou, pior, aceitar o diff e consertar na mão. As duas opções são ruins. Reescrever tudo descarta o que já estava certo. Consertar na mão deixa a correção fora da conversa e o problema volta na próxima vez. Vale lembrar que o Claude Code não aprende de forma permanente com o seu feedback: ele considera apenas o que está na sessão atual, então preferências que devem valer sempre precisam ser registradas em um arquivo CLAUDE.md do projeto. O melhor é apontar exatamente o que está errado, em uma ou duas frases:
A validação está correta, mas a mensagem de erro precisa ficar em português, e falta o teste para o caso de título vazio. Mantenha o resto como está.
Evite reações genéricas como “não ficou bom” ou “tenta de novo”, porque elas obrigam a ferramenta a adivinhar o que desagradou. Feedback específico converge em uma rodada; feedback vago pode não convergir nunca.
Use exemplos de entrada e saída
Para funções de transformação, formatação ou análise de texto, um exemplo concreto vale mais do que um parágrafo de descrição. Em vez de pedir “formate a data no padrão brasileiro”, escreva:
Crie a função formatarData em @src/utils.js. Dada a entrada “2024-03-05T14:30:00Z”, que está em UTC, a saída convertida para o fuso de Brasília (UTC-3) deve ser “05/03/2024 às 11:30”. Diga sempre qual fuso usar, porque o sufixo Z indica UTC e uma conversão silenciosa muda o horário exibido. Dada a entrada nula, a saída deve ser a string vazia. Adicione um teste para cada exemplo.
Dois ou três exemplos, incluindo um caso de borda, eliminam quase toda a ambiguidade e ainda servem de base para os testes. Essa técnica também funciona para formatos de resposta de API, mensagens de log e saídas de linha de comando.
Peça explicações, alternativas e trade-offs antes de decidir
Nem toda instrução precisa pedir uma ação. Quando você está em dúvida sobre o caminho, peça opções: “antes de implementar, apresente duas ou três formas de armazenar as sessões de usuário, com as vantagens, as desvantagens e o impacto em cada uma, e recomende uma”. Você recebe uma comparação objetiva, decide e só então pede a implementação da alternativa escolhida. A decisão continua sendo sua.
Vale também pedir explicação depois de uma alteração: “explique por que escolheu essa abordagem e o que aconteceria com a anterior”. Além de ensinar, isso revela suposições erradas antes que virem código em produção.
Recapitulando
Uma instrução eficiente para o Claude Code diz o que fazer, onde fazer e o que não pode ser tocado. Ela fornece contexto com referências de arquivo, mensagens de erro completas e exemplos de código existente para manter o estilo. Ela define um critério de pronto verificável, como testes passando ou um comando executando sem erro. Tarefas grandes são divididas em passos, com um plano revisado antes da primeira alteração. Quando algo sai errado, o feedback é curto e específico, sem reescrever o pedido nem remendar na mão. Exemplos de entrada e saída eliminam ambiguidade, e pedir alternativas com trade-offs mantém a decisão final nas suas mãos.
