Prompting do Claude Opus 5

Este guia aborda os padrões de prompting específicos do Claude Opus 5. Para as capacidades do modelo e as 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.

O Claude Opus 5 foi construído para trabalho complexo de codificação agêntica e corporativo, 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 abrangem os comportamentos que mais frequentemente exigem ajuste.

Melhorias de capacidade

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

• Codificação agêntica: O Claude Opus 5 é mais forte em tarefas de codificação difíceis: funcionalidades que abrangem vários arquivos, refatorações maiores e trabalho de funcionalidades de ponta a ponta. Ele conclui tarefas completas em vez de deixar stubs ou placeholders, e tem melhor desempenho quando recebe a especificação completa da tarefa de antemão 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 aos modelos anteriores é menor.
• Revisão de código e detecção de bugs: O Claude Opus 5 revisa código com alta precisão e recall: 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 minuciosa depois. Se o seu prompt de revisão disser "relate apenas problemas de alta severidade" ou "seja conservador", o modelo pode seguir essa instrução literalmente e relatar menos; em vez disso, peça que ele relate tudo e filtre em uma passagem separada.
• Eficiência com esforço mais baixo: Os níveis de "effort" (esforço) low e medium effort produzem qualidade forte com uma fração dos tokens e da latência das configurações mais altas. Comece com o padrão (high) e ajuste com base nas suas avaliações: use low e medium livremente como seu controle principal de custo de tokens e tempo de resposta sempre que a qualidade se mantiver, e suba para xhigh em trabalhos exigentes de codificação e agênticos. Se você trouxe padrões de esforço de um modelo anterior, execute novamente uma varredura de esforço nas suas próprias avaliações. Consulte Esforço para as recomendações completas.
• Visão: 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, recortar e verificar visualmente seu trabalho de forma iterativa, e o "tool use" (uso de ferramentas) é uma alavanca mais econômica do que o pensamento sozinho.
• Trabalho com contexto longo: O Claude Opus 5 tem uma "context window" (janela de contexto) de 1M de tokens tanto como padrão quanto como máximo, e seu seguimento de instruções, chamada de ferramentas e raciocínio permanecem consistentes ao longo de toda a janela.
• Tarefas de escritório e documentos: O Claude Opus 5 gera e trabalha com planilhas complexas de várias abas com fórmulas não triviais, e produz apresentações de slides bem estruturadas. Forneça no prompt quaisquer estilos ou modelos específicos que ele precise seguir.
• Coordenação multiagente: O 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 das respostas e verbosidade

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 quanto o modelo pensa, e não quanto ele diz: reduzir o esforço pode diminuir o volume de pensamento sem encurtar de forma confiável a resposta visível. Para controlar o comprimento da resposta, peça isso explicitamente no prompt.

Uma instrução curta de concisão é eficaz. Por exemplo, para um produto multiturno 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 "system prompt" (prompt do sistema) longo, combine a instrução com um breve lembrete próximo ao final do prompt:

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

Atualizações de progresso voltadas ao usuário

O 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 costuma ser mais longa do que a dos 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 direção oposta: 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

Separadamente da verbosidade conversacional, os arquivos que o Claude Opus 5 grava em disco (relatórios, documentos Markdown, resumos) costumam ser mais longos do que nos modelos anteriores. Se o seu produto inclui documentos de autoria do Claude, adicione uma 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 da tarefa e verificação excessiva

O Claude Opus 5 verifica seu próprio trabalho sem que lhe seja pedido. 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 o desperdício de tokens sem perda de qualidade. O mesmo se aplica a estruturas de harness legado que adicionam etapas de verificação separadas.

O 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

O Claude Opus 5 delega a subagentes mais prontamente do que os 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 oferece suporte a subagentes, forneça orientação explícita sobre quais cenários justificam delegação, ou defina limites determinísticos de 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.

Se o seu harness é o Claude Code ou o Claude Agent SDK, os limites determinísticos são as variáveis de ambiente CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH e CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS e a opção max_budget_usd do SDK. Elas exigem o Claude Code 2.1.217 ou posterior, portanto atualize um SDK fixado antes de apontá-lo para o Claude Opus 5. O Claude Code adiciona uma instrução de delegação própria no Claude Opus 5 apenas quando você usa seu preset de prompt do sistema claude_code; com um prompt do sistema personalizado ou omitido, adicione você mesmo uma instrução de delegação como o exemplo desta seção. Consulte Limitar profundidade, concorrência e gasto de subagentes na documentação do Agent SDK.

Autocorreção

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

O modelo também narra correções de suas declarações anteriores mais do que os modelos anteriores, o que pode ser indesejável em produtos voltados ao usuário. Para limitar a narração de correções à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 desativado

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

Chamadas de ferramentas como texto. Com o pensamento desativado, 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 os 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 desativado, 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 desativado, 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 as tags de pensamento pelo nome são menos eficazes do que a forma geral, portanto evite nomeá-las especificamente.