Como dar instruções ao Claude Code: escopo, critérios e teste

Como dar instruções ao Claude Code: escopo, critérios e teste

Para dar instruções ao Claude Code, descreva o objetivo da tarefa, o que ele pode e não pode mexer, os critérios que definem o trabalho como aceito e o comando que prova que funcionou. Pedidos específicos, com um jeito claro de verificar, reduzem retrabalho porque o agente deixa de adivinhar o que "pronto" significa. O formato abaixo vale para quem programa e para quem lidera uma equipe que usa a ferramenta.

Principais pontos

• Um bom pedido tem cinco partes: objetivo, contexto, limites, critérios de aceite e forma de verificar.
• Peça um plano antes do código em tarefas que mexem em vários arquivos, e aprove o plano antes de seguir.
• Limites valem mais que boa vontade: diga quais arquivos, comandos e dados estão fora do alcance.
• Critério de aceite precisa ser observável, de preferência com um teste ou comando que qualquer pessoa consiga rodar.
• Quem decide se a entrega vale é a pessoa responsável, não o agente: revise o resultado como revisaria o de um colega.

Por que um pedido vago dá um resultado ruim?

Quando alguém escreve "melhore o cadastro de clientes", o agente precisa decidir sozinho o que melhorar, até onde ir e como saber que terminou. Ele vai decidir, e a decisão pode não ser a sua. O resultado costuma ser uma mudança grande demais, em arquivos que você não queria tocar, com uma justificativa convincente.

O problema raramente é falta de capacidade da ferramenta. É falta de informação no pedido. A própria Anthropic, no material de boas práticas sobre o Claude Code, recomenda ser específico nas instruções e dar ao agente uma forma de conferir o próprio trabalho, como testes ou uma meta verificável. Vale ler o texto original: Claude Code: best practices for agentic coding.

Há também uma questão de contexto. Tudo o que você escreve, mais o que o agente lê durante a tarefa, ocupa a mesma memória de trabalho. Pedido enxuto e preciso deixa mais espaço para o que importa. Se quiser entender esse limite, veja janela de contexto em IA e o texto da Anthropic sobre engenharia de contexto para agentes.

Qual formato de pedido funciona na prática?

Use a estrutura abaixo como um molde. Nem toda tarefa precisa das cinco partes preenchidas por extenso, mas toda tarefa de risco médio ou alto precisa de todas.

• Objetivo: o resultado que você quer, em uma ou duas frases, no ponto de vista do usuário ou do negócio, não da implementação.
• Contexto: onde isso vive no projeto, o que já existe, qual convenção seguir e qual documento ou arquivo consultar.
• Limites: o que não pode ser alterado, quais comandos não devem ser executados, que dados não devem ser lidos e quando parar para perguntar.
• Critérios de aceite: lista de condições observáveis que, juntas, definem a tarefa como concluída.
• Verificação: o comando, teste ou passo manual que prova cada critério, e o que o agente deve relatar ao final.

Um exemplo curto de objetivo bem escrito: "Quando o cliente corrigir o telefone no cadastro, o sistema deve salvar o número só com dígitos e rejeitar entradas inválidas com uma mensagem clara." Compare com "arrumar o telefone". O primeiro já traz metade dos critérios dentro dele.

Cenário ilustrativo: ajuste no cálculo de desconto de uma proposta

Imagine uma empresa de serviços que tem um sistema interno de propostas. O desconto aparece arredondado de forma diferente na tela e no PDF, e o time comercial reclama. Este é um cenário ilustrativo, sem relação com nenhum caso real.

Um pedido fraco seria: "Corrija o desconto das propostas." Um pedido bom seria assim:

• Objetivo: o desconto exibido na tela e o desconto no PDF devem ser calculados pela mesma regra e mostrar o mesmo valor.
• Contexto: o cálculo está hoje duplicado entre o módulo de proposta e o gerador de PDF. A regra correta é a do módulo de proposta.
• Limites: não alterar o banco de dados nem migrações. Não mexer no módulo de pagamento. Não instalar dependências novas. Se a regra do módulo de proposta parecer incorreta, parar e perguntar.
• Critérios de aceite: existe uma única função de cálculo usada pelos dois lugares. Os testes novos cobrem desconto zero, desconto parcial e desconto total. Os testes antigos continuam passando.
• Verificação: rodar a suíte de testes do projeto e relatar quais testes foram adicionados, quais falharam antes da correção e o que mudou nos arquivos.

Repare que o pedido bom não diz como programar. Ele diz o que deve ser verdade no final e o que está fora de alcance. Isso deixa o agente livre para escolher a implementação, e deixa você com um jeito objetivo de conferir.

Como definir limites sem engessar o trabalho?

Limites existem para proteger o que é difícil de desfazer. Pense em três categorias: arquivos e áreas do sistema, comandos e ações, e dados.

Sobre arquivos e áreas, diga o que pode ser editado e o que não pode. Se a tarefa é local, avise que mudanças fora da pasta indicada exigem confirmação. Sobre comandos e ações, deixe claro o que exige aprovação humana: apagar arquivos, alterar o banco, publicar, enviar mensagens a clientes, mexer em configuração de servidor. Sobre dados, não coloque credenciais, base de clientes ou documentos pessoais no pedido nem em arquivos que o agente vá ler sem necessidade. Se o trabalho envolve dados pessoais, vale checar antes o que a LGPD exige quando o processamento ocorre fora do país, tema tratado em transferência internacional de dados com IA.

A ferramenta tem mecanismos de permissão que pedem sua aprovação antes de certas ações. Eles ajudam, mas não substituem o pedido: o que está escrito no pedido orienta o comportamento, e o que está configurado nas permissões limita o que é possível. Use os dois. Quando o agente precisar de acesso a sistemas externos, configure isso com critério, como explicado em configurar MCP no Claude Code.

Um limite útil, e muitas vezes esquecido, é a regra de parada: "se o teste falhar mais de uma vez pelo mesmo motivo, pare e explique o que tentou". Isso evita que a tarefa vire uma sequência de tentativas que ninguém acompanha.

Como escrever critérios de aceite e a verificação?

Um critério de aceite bom pode ser respondido com sim ou não por alguém que não participou da conversa. "O código está limpo" não serve. "A função nova tem teste para entrada vazia e a suíte inteira passa" serve.

Use esta checagem rápida antes de enviar o pedido:

• Cada critério é observável, e não uma opinião?
• Existe um comando ou passo que prova cada um?
• Há pelo menos um critério sobre o que não deve mudar (comportamento antigo, arquivos, interface)?
• O caso de erro está coberto, e não só o caminho feliz?
• Fica claro o que o agente deve relatar no final: arquivos alterados, comandos rodados, o que não conseguiu verificar?

Sobre a verificação, a prática mais útil é pedir que os testes venham primeiro. Em tarefas que se prestam a isso, escreva ou peça os testes que descrevem o comportamento esperado, confirme que eles falham, e só então peça a implementação. O material de boas práticas da Anthropic descreve esse tipo de fluxo orientado a testes como um dos que funcionam bem com o Claude Code. Mas atenção: teste escrito pela própria IA também precisa de revisão. Ele pode testar o que o código faz, e não o que o negócio precisa. Para esse cuidado, veja testes automatizados gerados por IA: como validar e confiar.

Quando a tarefa não é código, como um relatório ou um script de planilha, a lógica é a mesma: defina uma amostra de entrada com saída conhecida e peça que o agente mostre o resultado nela. Para ideias de como estruturar essa avaliação, a Anthropic tem um bom texto sobre avaliações de agentes.

Qual é o passo a passo para conduzir a tarefa?

Um bom pedido é o começo, não o fim. Este roteiro funciona para tarefas de tamanho médio:

• Escreva o pedido com as cinco partes e inclua o que não deve ser feito.
• Peça um plano antes de qualquer alteração: quais arquivos pretende tocar, em que ordem e como vai verificar. Nada de código ainda.
• Leia o plano. Corte o que passa do escopo, corrija suposições erradas e só então autorize a execução.
• Acompanhe os primeiros passos. Se a direção estiver errada, interrompa cedo e corrija, em vez de esperar o fim.
• Peça que o agente rode a verificação combinada e relate o resultado com evidências, não com adjetivos.
• Revise você mesmo as diferenças (o diff) antes de aceitar, com atenção a arquivos que não deveriam aparecer.
• Se a conversa ficou longa e confusa, comece uma nova sessão com um resumo curto do estado atual em vez de insistir na mesma.

Para tarefas grandes, divida em etapas pequenas, cada uma com seu critério. A Anthropic discute, em harnesses para agentes de longa duração, que trabalhos extensos funcionam melhor com progresso registrado e passos verificáveis. Essa é uma orientação de documentação. Na prática, a consequência para quem delega é simples: tarefa grande vira várias tarefas pequenas, cada uma com seu pedido.

O que se repete em todo pedido pode virar memória do projeto. As convenções de código, os comandos de teste e as áreas proibidas ficam melhor em um arquivo de instruções do projeto (o CLAUDE.md) do que copiados em cada mensagem. E fluxos que sua equipe repete com frequência podem virar skills, assunto de skills no Claude Code.

Como o método mapear, limitar, pilotar e transferir se aplica?

O mesmo raciocínio que usamos para projetos de IA em processos de negócio vale para a delegação de uma tarefa. Mapear é entender o estado atual antes de pedir: onde está o problema, como funciona hoje e qual é a linha de base (por exemplo, quais testes passam antes da mudança). Limitar é definir arquivos, comandos e dados permitidos, além do ponto em que o agente deve parar e perguntar. Pilotar é começar por uma tarefa real e pequena, com log do que foi feito e um critério combinado de sucesso, antes de delegar algo maior. Transferir é deixar o aprendizado registrado: o pedido que funcionou vira modelo, as regras viram arquivo de projeto, e a equipe decide se amplia, ajusta ou interrompe o uso.

Esta seção descreve um método de trabalho, não uma garantia de resultado. A qualidade do que sai continua dependendo do contexto do projeto e da revisão feita por quem entende do assunto.

Perguntas frequentes

Preciso escrever pedidos longos toda vez? Não. Para uma mudança pequena e fácil de desfazer, duas ou três frases com objetivo e forma de verificar bastam. Reserve o formato completo para tarefas que tocam várias partes do sistema, mexem com dados de clientes ou são difíceis de reverter.

Devo sempre pedir um plano antes do código? Em tarefas que envolvem vários arquivos ou decisões de desenho, sim, porque corrigir um plano custa muito menos que corrigir uma implementação inteira. Em ajustes pequenos e óbvios, o plano só atrasa. A regra prática é: quanto mais difícil de desfazer, mais vale ler o plano antes.

Como sei se posso confiar no que o Claude Code diz que fez? Confie na evidência, não no resumo. Rode os testes combinados, leia o diff e confira se apenas os arquivos esperados mudaram. Se o agente disser que não conseguiu verificar algo, trate isso como pendência e não como detalhe.

Uma pessoa que não programa consegue usar esse formato? Consegue, e o formato ajuda justamente porque obriga a descrever o resultado esperado em termos de negócio. O cuidado é pedir revisão técnica antes de colocar qualquer coisa em uso real. Para um primeiro contato, veja Claude Code para quem não programa.

Fontes

• Anthropic: Claude Code, best practices for agentic coding
• Anthropic: Effective context engineering for AI agents
• Anthropic: Demystifying evals for AI agents
• Anthropic: Effective harnesses for long-running agents