Prompting para Claude Opus 5

Este guia cobre os padrões de "prompting" (elaboração de prompts) específicos do Claude Opus 5. Para as capacidades do modelo e mudanças na API, consulte O que há de novo no Claude Opus 5. Para técnicas que se aplicam a todos os modelos Claude atuais, consulte Melhores práticas de prompting.

Claude Opus 5 foi construído para codificação agêntica complexa e trabalho empresarial, com pontos fortes particulares em tarefas agênticas de longo horizonte. Ele tem bom desempenho imediato com prompts existentes do Claude Opus 4.8. Os padrões a seguir cobrem os comportamentos que mais frequentemente exigem ajustes.



Melhorias de capacidade

Em comparação com o Claude Opus 4.8, as melhorias mais relevantes para prompting são:

• Codificação agêntica: Claude Opus 5 é mais forte em tarefas de codificação difíceis: funcionalidades multi-arquivo, refatorações maiores e trabalho de funcionalidades de ponta a ponta. Ele completa tarefas inteiras em vez de deixar stubs ou placeholders, e tem melhor desempenho quando recebe a especificação completa da tarefa desde o início e é deixado para executar. Ele também tem bom desempenho em tarefas mais fáceis, como edições de turno único, onde a diferença em relação a modelos anteriores é menor.
• Revisão de código e detecção de bugs: Claude Opus 5 revisa código com alta precisão e "recall" (revocação): ele encontra bugs reais a uma taxa alta por passagem, e suas descobertas adicionais são em sua maioria problemas reais em vez de falsos positivos. A precisão se mantém em configurações de esforço mais baixas, o que permite uma passagem rápida no momento da revisão e uma passagem mais completa depois. Se o seu prompt de revisão diz "reporte apenas problemas de alta severidade" ou "seja conservador", o modelo pode seguir essa instrução literalmente e reportar menos; em vez disso, peça para ele reportar tudo e filtre em uma passagem separada.
• Eficiência em esforço mais baixo: effort (esforço) low e medium produzem qualidade forte com uma fração dos tokens e da latência de configurações mais altas. Comece com o padrão (high) e ajuste com base em suas avaliações: use low e medium liberalmente como seu controle principal para custo de tokens e tempo de resposta onde a qualidade se mantiver, e suba para xhigh para trabalho de codificação e agêntico exigente. Se você transferiu padrões de esforço de um modelo anterior, execute novamente uma varredura de esforço em suas próprias avaliações. Consulte Effort para as recomendações completas.
• Visão: Claude Opus 5 é forte na compreensão de gráficos, documentos e diagramas, e na replicação visual de UI e frontend. Revalide quaisquer soluções alternativas de visão no lado do prompt que você ajustou para modelos anteriores; elas podem não ser mais necessárias. O desempenho de visão é mais forte quando o modelo tem ferramentas para analisar iterativamente, recortar e verificar visualmente seu trabalho, e o uso de ferramentas é uma alavanca mais econômica do que o pensamento sozinho.
• Trabalho com contexto longo: Claude Opus 5 tem uma janela de contexto de 1M de tokens tanto como padrão quanto como máximo, e seu seguimento de instruções, chamadas de ferramentas e raciocínio permanecem consistentes ao longo de toda a janela.
• Tarefas de escritório e documentos: Claude Opus 5 gera e trabalha com planilhas complexas de múltiplas abas com fórmulas não triviais, e produz apresentações de slides bem estruturadas. Inclua no prompt quaisquer estilos ou templates específicos que ele precise seguir.
• Coordenação multiagente: Claude Opus 5 coordena bem equipes de subagentes, com padrões eficazes de escritor-verificador e poucos casos de agentes sobrescrevendo o trabalho uns dos outros. Para cargas de trabalho sensíveis a custo, limite a delegação; consulte Controlando a criação de subagentes.



Comprimento e verbosidade das respostas

As respostas padrão voltadas ao usuário do Claude Opus 5 são mais longas do que as dos modelos Opus anteriores. O parâmetro effort controla o quanto o modelo pensa em vez de quanto ele diz: reduzir o esforço pode reduzir o volume de pensamento sem encurtar de forma confiável a resposta visível. Para controlar o comprimento da resposta, solicite isso explicitamente no prompt.

Uma instrução curta de concisão é eficaz. Por exemplo, para um produto multi-turno voltado ao usuário:

Keep responses focused, brief, and concise. Keep disclaimers and caveats short, and spend most of the response on the main answer. When asked to explain something, give a high-level summary unless an in-depth explanation is specifically requested.

Em um prompt do sistema longo, combine a instrução com um lembrete curto perto do final do prompt:

<tone_preference>
Keep outputs reasonably concise.
</tone_preference>



Atualizações de progresso voltadas ao usuário

Claude Opus 5 narra prontamente durante o trabalho agêntico: ele tende a anunciar o que está prestes a fazer, e sua saída por mensagem em sessões agênticas é frequentemente mais longa do que a de modelos anteriores. Ele se beneficia de orientação explícita sobre como se comunicar com o usuário durante uma tarefa. Para reduzir a narração, descreva a cadência e o formato que você deseja:

Before your first tool call, say in one sentence what you're about to do. While working, give a brief update only when you find something important or change direction. When you finish, lead with the outcome: your first sentence should answer "what happened" or "what did you find," with supporting detail after it for readers who want it.

Para aumentar a narração, ou mudar seu estilo, a mesma alavanca se aplica na outra direção: descreva explicitamente como as atualizações devem ser e forneça exemplos. Exemplos positivos do estilo de comunicação que você deseja tendem a ser mais eficazes do que instruções sobre o que não fazer.



Comprimento de entregáveis escritos

Separado da verbosidade conversacional, arquivos que o Claude Opus 5 escreve em disco (relatórios, documentos Markdown, resumos) são frequentemente mais longos do que em modelos anteriores. Se o seu produto inclui documentos criados pelo Claude, adicione calibração explícita de comprimento:

Match the length of written documents to what the task needs: cover the substance, but do not pad with filler sections, redundant summaries, or boilerplate.



Escopo de tarefas e verificação excessiva

Claude Opus 5 verifica seu próprio trabalho sem que isso seja solicitado. Se o seu prompt contém instruções explícitas de verificação ("inclua uma etapa final de verificação para qualquer tarefa não trivial", "use um subagente para verificar"), remova-as: instruções como essas causam verificação excessiva no Claude Opus 5, e removê-las reduz tokens desperdiçados sem perda de qualidade. O mesmo se aplica a scaffolding legado de harness que adiciona etapas de verificação separadas.

Claude Opus 5 também pode expandir o escopo de uma tarefa, adicionando etapas que não foram solicitadas ou aplicando seu próprio julgamento sobre o que a tarefa deveria ser. Para tarefas restritas, limite o escopo explicitamente:

Deliver what was asked, at the scope intended. Make routine judgment calls yourself, and check in only when different readings of the request would lead to materially different work. If the request seems mistaken or a better approach exists, say so in a sentence and continue with the task as asked rather than quietly narrowing, widening, or transforming it. Finish the whole task, and stop short of actions that are clearly beyond what was asked.



Controlando a criação de subagentes

Claude Opus 5 delega a subagentes mais prontamente do que modelos anteriores. A delegação compensa em frentes de trabalho genuinamente independentes e de tamanho considerável, mas multiplica custo e tempo quando aplicada a tarefas pequenas. Se o seu harness suporta subagentes, dê orientação explícita sobre quais cenários justificam delegação, ou defina limites determinísticos sobre quantos agentes podem ser iniciados. Por exemplo:

Delegate to a subagent only for large tasks that are genuinely independent and parallelizable, such as a wide multi-file investigation. Do not delegate work you can finish yourself in a handful of tool calls, and do not use subagents to verify or double-check your own work. If one subagent can complete the task, use one rather than several, and keep spawn counts low.



Autocorreção

Claude Opus 5 detecta e corrige bem seus próprios erros sem necessidade de prompting. Evite instruir reverificações que ele já realiza ("verifique novamente sua resposta", "reverifique antes de responder"); assim como instruções de verificação, essas se acumulam com o comportamento próprio do modelo e adicionam custo sem melhorar os resultados.

O modelo também narra correções a suas declarações anteriores mais do que modelos anteriores, o que pode ser indesejável em produtos voltados ao usuário. Para limitar a narração de correções apenas às correções que importam:

Only correct an earlier statement when the error would change the user's code, conclusions, or decisions. State corrections plainly and briefly, then continue the task. For slips that change nothing for the user, make the fix and move on without noting it.



Executando com o pensamento desabilitado

Claude Opus 5 executa com pensamento ativado por padrão, e o pensamento só pode ser desabilitado em effort high ou inferior; consulte o guia de migração. Com o pensamento desabilitado, dois artefatos podem ocasionalmente aparecer na saída visível do modelo. A mitigação principal para ambos é manter o pensamento habilitado e controlar o custo de tokens com níveis de esforço mais baixos em vez de desabilitar o pensamento: para a maioria das tarefas, o pensamento habilitado com esforço low tem desempenho melhor do que o pensamento desabilitado a custo semelhante.

Chamadas de ferramentas como texto. Com o pensamento desabilitado, o modelo ocasionalmente escreve uma chamada de ferramenta em seu texto voltado ao usuário em vez de emitir um bloco tool_use estruturado. O turno é concluído normalmente e a chamada nunca é executada, e em loops agênticos o texto vazado permanece no histórico da conversa, de modo que turnos posteriores também são afetados. Isso é mais comum em cargas de trabalho com uso intenso de ferramentas, como busca.

Tags XML internas na saída. Com o pensamento desabilitado, o modelo pode emitir tags <thinking> ou outras tags XML internas em sua resposta visível. Se o seu prompt do sistema contém uma regra instruindo o modelo a não pensar ou não raciocinar, remova-a; esse tipo de instrução aumenta o vazamento de tags.

Para integrações que precisam manter o pensamento desabilitado, uma única instrução combinada mitiga ambos os artefatos: ela dá ao modelo permissão explícita para falar antes de uma chamada de ferramenta, uma alternativa a forçar uma chamada quando nenhuma ferramenta se encaixa, e uma regra geral contra tags internas:

When you use a tool, you may say a brief sentence first. If no tool can express what the user asked for, say so instead of guessing. Do not include internal or system XML tags in your response.

Instruções que mencionam tags de pensamento pelo nome são menos eficazes do que a forma geral, então evite nomeá-las especificamente.