Como escrever prompts para o Claude Sonnet 5.5

Este guia aborda os padrões de prompt específicos do Claude Sonnet 5.5. Para as mudanças de API do modelo, consulte Novidades do Claude Sonnet 5.5. Para técnicas que se aplicam a todos os modelos Claude atuais, consulte Melhores práticas de prompt.

Os prompts existentes do Claude Sonnet 5 devem ter bom desempenho sem alterações, e os padrões em Como escrever prompts para o Claude Sonnet 5 continuam sendo um ponto de partida razoável. Para o trabalho de longo horizonte mais difícil, um modelo Opus é a melhor escolha. Comece pela seção que corresponde ao que você observa:

• Não sabe qual nível de esforço usar, ou os turnos duram mais ou menos do que duravam no Claude Sonnet 5: Calibre o esforço
• O modelo para e pede confirmação antes de concluir uma tarefa de código, ou faz mais do que você pediu: Direcione a iniciativa e o escopo
• Sua integração roda hoje com o pensamento desativado: Execução sem pensamento prévio
• Respostas JSON para tarefas que exigem algumas etapas de raciocínio estão erradas ou não podem ser analisadas: Tarefas de raciocínio com saída JSON
• Turnos agênticos longos parecem silenciosos: Atualizações de progresso voltadas ao usuário
• O modelo responde com base em seu conhecimento de treinamento quando uma pesquisa detectaria detalhes que mudaram: Uso de ferramentas em chat e trabalho de conhecimento
• Mensagens que os usuários enviam no meio da tarefa são ignoradas ou tratadas como texto injetado: Mensagens do usuário no meio do turno
• Alterações de código são relatadas como concluídas sem a execução de um teste ou build: Verificação em tarefas de código
• O modelo chama uma ferramenta com maiúsculas/minúsculas erradas ou passa um parâmetro com um nome ligeiramente diferente: Tratamento tolerante de chamadas de ferramentas
• Respostas sobre gráficos densos ou desenhos técnicos deixam passar detalhes: Ferramentas para entradas visuais complexas
• Solicitações retornam stop_reason: "refusal": Recusas de salvaguarda

Calibre o esforço

O "effort" (esforço) é o principal controle de quanto o Claude Sonnet 5.5 pensa e, com isso, de qualidade, "latency" (latência) e custo. Seus níveis foram recalibrados: um nível não produz a mesma quantidade de pensamento que o mesmo nível no Claude Sonnet 5. Faça uma nova varredura com suas próprias avaliações em vez de manter a configuração que você usava no Claude Sonnet 5. Comece em high, o padrão na Claude API, a menos que sua carga de trabalho seja agêntica ou sensível à latência. Para programação agêntica e uso de ferramentas em várias etapas, comece em medium para tarefas bem especificadas e passe para high para tarefas mais difíceis ou mais longas. Para chat e outros trabalhos sensíveis à latência, comece em medium ou low, porque um esforço maior significa uma espera mais longa antes de a resposta começar. Aumente o esforço se a qualidade exigir.

Um esforço menor também muda a forma como o modelo conclui o trabalho agêntico. Em low, ele mantém o pensamento curto e pode deixar de verificar uma alteração. Consulte Verificação em tarefas de código. Em low e medium, em tarefas agênticas longas, é mais provável que ele pare e peça confirmação ao usuário antes de terminar. Consulte Direcione a iniciativa e o escopo.

Três ajustes ajudam:

• Defina max_tokens com espaço para o pensamento e para a resposta que você espera. O pensamento conta para max_tokens mesmo quando o conteúdo do pensamento não é retornado a você. Um limite dimensionado para uma solicitação sem pensamento pode cortar a resposta. Para programação agêntica, defina max_tokens como 128.000, o máximo do modelo, e faça streaming da resposta.
• Reserve xhigh e max para trabalhos em que você mediu um ganho de qualidade, porque o pensamento e as respostas ficam muito mais longos nesses níveis. Nesses níveis, between_tools não é aceito, então o pensamento prévio não pode ser desativado.
• Para obter menos pensamento, reduza o nível de esforço. A partir de medium, o modelo pensa brevemente antes de quase todas as respostas, até mesmo uma saudação, o que aumenta o tempo até o primeiro token visível. Pedir no "system prompt" (prompt do sistema) que ele pense menos não reduz seu pensamento de forma confiável. Em low, ele pula o pensamento na maioria das solicitações simples.

Alterar o valor de effort de nível superior entre solicitações invalida o cache de prompt. Para executar turnos individuais em um nível diferente, use uma alteração de esforço por mensagem (beta), que preserva o cache. Por exemplo, execute uma sessão interativa em low e aumente o esforço para high quando o usuário enviar um problema difícil. Alterações de esforço por mensagem exigem "adaptive thinking" (pensamento adaptativo). Com between_tools, elas retornam um erro 400, como explica Execução sem pensamento prévio.

Direcione a iniciativa e o escopo

O quanto o Claude Sonnet 5.5 avança por conta própria depende do nível de esforço e da solicitação. Com esforço menor, ele às vezes pede confirmação antes de concluir uma tarefa de código. Com esforço maior, ou em uma solicitação aberta, ele pode fazer mais do que você pediu. Direcione-o com o nível de esforço e com instruções no seu prompt do sistema.

Levar o trabalho até o fim. Em tarefas de programação agêntica com esforço low e medium, o modelo às vezes pede confirmação antes de o trabalho estar concluído. Ele pode pausar para confirmar um plano, fazer uma pergunta que poderia responder sozinho ou parar após uma parte de uma tarefa com várias partes para perguntar se deve continuar. Tente primeiro um nível de esforço maior. Para manter o modelo trabalhando sem alterar o esforço, adicione isto ao seu prompt do sistema:

Keep working until everything the user asked for is done, and only stop to ask when you can't go on without the user or before a risky step.

When the work the user asked for is done and checked, stop and report. Don't add features, tests, files, docs or refactors that weren't asked for. If you think one would help, mention it at the end instead of doing it.

Com esse prompt, o modelo leva mais trabalho até o fim com esforço low e medium, então as sessões nesses níveis duram mais e custam mais. O prompt não substitui suas próprias regras sobre ações arriscadas ou irreversíveis. Mantenha essas regras no seu prompt do sistema.

Adições não solicitadas ao programar. O modelo tende a adicionar testes, documentação e pequenos arquivos de apoio que seguem as convenções do seu repositório, mesmo quando você não os pede. Ele faz isso em todos os níveis de esforço, e mais com esforço maior. A alteração solicitada em si permanece próxima do que foi pedido. A maioria das equipes vai gostar disso. Se você preferir alterações limitadas ao que foi explicitamente solicitado, adicione apenas o segundo parágrafo daquele prompt, que começa com "When the work the user asked for is done". Com esforço xhigh e max, esse parágrafo reduz essas adições e torna as alterações menores no geral.

Minúcia com esforço xhigh e max. Nesses níveis, o modelo é especialmente minucioso. Depois de concluir uma tarefa, ele pode iniciar suas próprias rodadas de revisão e verificação, às vezes com "subagents" (subagentes), se o seu harness os fornecer. Ele também pode fazer correções relacionadas que notou pelo caminho. Isso consome mais tempo e tokens, então execute o trabalho rotineiro em high ou abaixo, onde isso é raro. Se você quiser essa minúcia extra desses níveis de esforço, mas quiser direcioná-la para a própria tarefa, adicione isto ao seu prompt do sistema:

When the work the user asked for is done and its checks pass, stop and report. Don't start extra rounds of review or hardening on your own, and don't launch reviewer sub-agents unless the user asked for a review. If you think a deeper review is worth doing, say so at the end.

Em testes com tarefas de código com esforço max, isso impediu o modelo de iniciar subagentes revisores e reduziu o custo da sessão em cerca de um terço, sem alteração na qualidade. Isso torna menos frequentes as rodadas de revisão iniciadas pelo próprio agente principal, mas não as elimina completamente.

Solicitações abertas. Quando uma solicitação é aberta, por exemplo "mostre o que você consegue fazer com isto", o modelo pode começar a criar uma apresentação, um relatório ou um vídeo quando você só queria ideias. Se você quiser ideias ou um plano primeiro, diga isso na solicitação ou adicione isto ao seu prompt do sistema:

When the user asks for ideas, options or a plan, give them that and stop. Don't start building or changing anything until they say to go ahead.

Execução sem pensamento prévio

Para executar o Claude Sonnet 5.5 sem pensamento prévio, envie thinking: {"type": "between_tools"}. Essa é a configuração de pensamento mais baixa neste modelo, e ela é aceita com esforço high ou abaixo. Se sua integração roda hoje com o pensamento desativado, mude-a para between_tools e verifique estes pontos:

• Envie between_tools com esforço high ou abaixo. Com esforço xhigh ou max, uma solicitação com between_tools retorna um erro 400. Com between_tools, o esforço também não pode mudar no meio da conversa: um output_config.effort por mensagem que difere do nível em vigor retorna um erro 400. Para variar o esforço por turno, use o pensamento adaptativo. Com between_tools, remova qualquer instrução que diga ao modelo para não pensar. Essas instruções aumentam a probabilidade de o modelo escrever tags XML internas em sua saída visível.
• Leia a resposta por tipo de bloco. Com o pensamento adaptativo, uma resposta pode começar com um bloco thinking, cujo campo thinking fica vazio sob o padrão display: "omitted". Com between_tools, uma resposta pode começar com um bloco thinking de atualização de progresso. Não presuma que o primeiro bloco de conteúdo é texto.
• Devolva os blocos thinking sem alterações. Com between_tools, as notas que o modelo escreve entre chamadas de ferramentas ainda retornam como blocos thinking quando têm mais de uma ou duas frases. Cada bloco traz um resumo da nota. Devolva-os sem alterações junto com o restante do turno do assistente. Um bloco que você devolve fornece ao modelo a nota completa que ele escreveu, não o resumo.
• Use o pensamento adaptativo para tarefas de raciocínio sem ferramentas. Em uma solicitação sem ferramentas, between_tools significa que o modelo responde sem pensar antes. Para tarefas que exigem algumas etapas de raciocínio, use o pensamento adaptativo. Consulte Tarefas de raciocínio com saída JSON.

Tarefas de raciocínio com saída JSON

Esta seção se aplica quando você pede ao Claude Sonnet 5.5 uma resposta JSON para uma tarefa que exige algumas etapas de raciocínio. Exemplos incluem somar valores de um documento, aplicar uma regra ou classificar itens. Em tarefas como essas, o modelo frequentemente responde sem pensar antes, especialmente com esforço low e medium. O que ajuda depende de como você solicita o JSON. Use "structured outputs" (saídas estruturadas) onde estiverem disponíveis. O texto da resposta é então um JSON que corresponde ao seu schema, então não há nada para analisar.

Com saídas estruturadas, o texto da resposta contém apenas o JSON, então o modelo só pode resolver o problema em seu pensamento. Quando ele pula o pensamento, pode ser menos preciso nessas tarefas. Estas mudanças ajudam a manter a precisão alta.

Peça ao modelo para pensar primeiro. Com o pensamento adaptativo, adicione esta linha ao final do seu prompt do sistema:

Think the problem through before you answer.

Com essa linha, o modelo pensa com mais frequência antes de responder. Com esforço high, a linha aproxima a precisão daquela que o modelo alcança em xhigh, com um aumento modesto de tokens de saída. Com esforço low e medium, ela aumenta a precisão, embora não até o nível que o modelo alcança em high, e o aumento de tokens de saída é maior.

Ou use esforço xhigh. Com o pensamento adaptativo, xhigh oferece a maior precisão nessas tarefas mesmo sem a linha. Ele usa mais tokens de saída do que high.

Use o pensamento adaptativo em vez de between_tools. Em uma solicitação sem ferramentas, o modelo não pensa antes de responder sob between_tools. A linha não tem efeito nesse caso, e a precisão nessas tarefas é menor. Use o pensamento adaptativo para essas solicitações, com as etapas desta seção. Em testes, dividir a solicitação em duas, uma para a resposta e outra para o JSON, resultou em alta precisão das respostas e conformidade do JSON, mas com custo e latência muito altos.

Com saídas estruturadas e esforço low e medium, o modelo ocasionalmente continua pensando até atingir max_tokens. Com esforço high e acima, isso quase nunca acontece. Trate qualquer resposta cujo stop_reason seja "max_tokens" como falha, mesmo que seu texto contenha JSON válido, e tente novamente. Defina max_tokens alto o suficiente para o pensamento e o JSON, como descreve Calibre o esforço, mas não mais alto do que você está disposto a gastar em uma tentativa.

Se você não puder usar saídas estruturadas, peça o JSON no prompt. O modelo então frequentemente resolve o problema no texto da resposta e escreve o JSON no final. O JSON geralmente contém a resposta certa, mas um parser que espera que a resposta inteira seja JSON falha. Duas coisas ajudam:

• Analise o último valor JSON da resposta. Leia apenas os blocos text e trate uma resposta cujo stop_reason seja "max_tokens" como falha. A partir de cada { ou [, tente analisar um valor JSON. Quando um for analisado com sucesso, continue a partir do final desse valor, para que os valores aninhados dentro dele não sejam contados separadamente. Mantenha o último valor encontrado. Não pegue tudo do primeiro { até o último }. O modelo ocasionalmente escreve um rascunho antes do JSON final, e esse intervalo incluiria ambos. Se sua resposta for vários valores JSON em sequência, como um registro por linha, mantenha a última sequência de valores separados apenas por espaços, vírgulas ou quebras de linha. Verifique se o resultado tem os campos que você espera e tente novamente uma vez se não tiver. Em testes, isso tornou quase todas as respostas utilizáveis sem alterar sua precisão.
• Considere também o esforço xhigh com pensamento adaptativo. O modelo então resolve o problema em seu pensamento e quase sempre retorna apenas o JSON. O total de tokens de saída permanece aproximadamente o mesmo que em high, porque o raciocínio passa do texto da resposta para o pensamento.

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

Entre chamadas de ferramentas, o Claude Sonnet 5.5 escreve notas voltadas ao usuário sobre o que acabou de encontrar e o que fará em seguida. Notas com mais de uma ou duas frases retornam como blocos thinking de atualização de progresso. Comentários mais curtos permanecem como text. Com o thinking.display padrão, o texto de um bloco de atualização de progresso fica vazio, então um cliente que renderiza apenas blocos text pode parecer silencioso durante um turno agêntico longo. Isso importa mais em interfaces de chat e outros produtos em que o usuário acompanha o trabalho do modelo em tempo real.

Para exibir essas notas, defina display: "updates" (beta, cabeçalho thinking-display-updates-2026-08-18). Com between_tools, as notas retornam com seu texto de resumo, então nenhum campo display é necessário. between_tools não aceita nenhum outro campo: display, budget_tokens ou block_binding enviados com ele retornam um erro 400. O guia de migração mostra como renderizar as notas. Às vezes, o modelo precisa mostrar ao usuário um texto exato no meio de um turno longo, como um trecho de código ou uma pergunta que precisa ser respondida. Para esse caso, dê a ele uma ferramenta simples para enviar uma mensagem ao usuário. Diga ao modelo para usar essa ferramenta apenas para esse tipo de conteúdo. Declare a ferramenta na primeira solicitação da sessão, para que a lista tools não mude depois.

Em seguida, remova instruções antigas como "guarde todas as descobertas para a resposta final". Se você quiser atualizações em pontos previsíveis, por exemplo uma linha sobre o que o modelo está prestes a fazer antes da primeira chamada de ferramenta e um breve resumo no final, diga isso no prompt do sistema. O modelo segue instruções como essa. Atualizações em pontos definidos ajudam mais em trabalhos com "human-in-the-loop" (humano no circuito).

Se turnos longos com chamadas de ferramentas ainda ficarem silenciosos por mais tempo do que você deseja, seu harness pode solicitar uma atualização. Faça-o contar as etapas consecutivas de chamada de ferramentas que não enviam ao usuário nenhum texto ou atualização de progresso. Após várias seguidas, por exemplo cinco, anexe um lembrete de um turno após os resultados de ferramentas mais recentes. Envie-o como uma mensagem do sistema com escopo de turno (beta), com um texto como este:

The user hasn't heard from you in a while — say in a few words what you're doing, then continue.

Se o turno continuar silencioso, pare de enviar lembretes após o segundo ou terceiro. Texto frequente do harness após resultados de ferramentas pode fazer o modelo suspeitar de uma "prompt injection" (injeção de prompt), como explica Mensagens do usuário no meio do turno. Mantenha cada lembrete em messages nas solicitações posteriores. Como o lembrete é anexado, e não inserido e depois excluído, o cache de prompt e o pensamento preservado permanecem intactos. Com esforço high, com uma ferramenta disponível para enviar mensagens ao usuário, o lembrete leva o modelo a atualizar o usuário com mais frequência e encurta seus trechos silenciosos mais longos, sem alteração mensurável na qualidade da tarefa.

Uso de ferramentas em chat e trabalho de conhecimento

Em tarefas de chat e de trabalho de conhecimento, o Claude Sonnet 5.5 às vezes responde com base em seu conhecimento de treinamento quando uma pesquisa na web detectaria detalhes que mudaram. Exemplos incluem o que é permitido, exigido ou cobrado.

Primeiro, verifique se o seu prompt contém linguagem que desencoraja o "tool use" (uso de ferramentas), como "use ferramentas apenas quando estritamente necessário" ou "minimize as chamadas de ferramentas", e remova-a. Depois, se o seu produto fornece ao modelo uma ferramenta de pesquisa, adicione isto ao seu prompt do sistema:

Use the search tool to check specifics that may have changed since your training, such as what is allowed, required or charged, even when you feel confident. For researched work such as a report or a comparison, gather current sources rather than writing from your training knowledge.

Isso importa mais para produtos de pesquisa e suporte, em que as respostas dependem de detalhes atuais.

Mensagens do usuário no meio do turno

O Claude Sonnet 5.5 é treinado para resistir à injeção de prompt indireta, ou seja, instruções maliciosas que chegam por meio de resultados de ferramentas e outros conteúdos que ele lê durante uma tarefa. Às vezes, ele trata uma mensagem genuína do usuário como uma possível injeção. Suponha que uma mensagem que o usuário digitou no meio da tarefa chegue ao modelo como uma mensagem do sistema no meio da conversa colocada logo após um resultado de ferramenta, ou dentro de um bloco tool_result. O modelo pode então dizer ao usuário que o resultado da ferramenta continha um texto se passando por uma mensagem dele e ignorar a mensagem ou pedir ao usuário que a confirme.

Uma contagem regressiva de tokens que seu harness adiciona após cada resultado de ferramenta pode causar isso. O mesmo pode acontecer ao permitir que os usuários enviem mensagens enquanto o modelo está no meio de um turno com várias etapas, ou ao fazer seu harness adicionar instruções ou contexto após os resultados de ferramentas em cada etapa. Em cada caso, o texto chega logo após os resultados de ferramentas. Com uma contagem regressiva ou instruções por etapa, isso pode acontecer em cada chamada de ferramenta. Um lembrete ocasional de um turno, como o de Atualizações de progresso voltadas ao usuário, chega com muito menos frequência. Se você observar essa reação a um lembrete seu, envie o lembrete com menos frequência. Para evitar a interpretação equivocada:

• Nunca coloque texto do usuário dentro de um bloco tool_result. É nessa posição que o modelo mais interpreta errado.
• Entregue a entrada do usuário no meio do turno como um turno do usuário. Anexe as palavras do usuário como um bloco de texto na mensagem do usuário que carrega os blocos tool_result, após o último tool_result.
• Mantenha os avisos do harness, como lembretes, em uma mensagem do sistema no meio da conversa separada, após as palavras do usuário. Nunca coloque um aviso e as palavras do usuário no mesmo bloco.
• Em sessões interativas em que os usuários podem digitar no meio do turno, não adicione sua própria contagem regressiva de tokens ou de orçamento após os resultados de ferramentas. Os orçamentos de tarefa (beta) adicionam uma contagem regressiva semelhante, mas não foi observado que causem essa interpretação equivocada. Se você observar a interpretação equivocada enquanto um orçamento de tarefa estiver definido, experimente a sessão sem ele.

Verificação em tarefas de código

Em tarefas de programação agêntica, o Claude Sonnet 5.5 geralmente verifica seu trabalho antes de relatar uma alteração como concluída. Com esforço low, porém, ele às vezes relata uma alteração como concluída sem executar uma verificação que a exercite. Por exemplo, ele pode pular os testes do projeto porque as dependências do projeto não estão instaladas.

Se você observar alterações relatadas como concluídas sem saída de teste ou build na transcrição, adicione este parágrafo, ou um semelhante, ao prompt do sistema. Com esforço low, ele torna raras as verificações puladas ou superficiais, sem alteração mensurável na qualidade da tarefa e com um custo por tarefa apenas ligeiramente maior:

When you change code that can be run, built, or type-checked, run a real check that exercises the change before reporting it done: the project's tests, type-checker, or build, or the changed command itself. A syntax-only check, or a check command that failed to start, does not count; if all that is missing is the project's declared dependencies, install them with its own package manager and lockfile (e.g. npm install, pip install -r requirements.txt), never via sudo or the system package manager, unless told not to. Only if no real check can run here, say which one you did not run and why instead of reporting the change as done.

Tratamento tolerante de chamadas de ferramentas

O Claude Sonnet 5.5 ocasionalmente chama uma ferramenta declarada por um nome que difere apenas em maiúsculas/minúsculas, como bash para Bash. Ele também pode passar um parâmetro conhecido com um nome ligeiramente diferente. Em vez de tratar essa chamada como um erro fatal, faça seu harness lidar com ela de uma de duas formas:

• Aceite a chamada quando a correspondência for inequívoca, mesmo que as maiúsculas/minúsculas estejam erradas.
• Retorne um tool_result com is_error: true que informe o nome exato esperado. O modelo geralmente corrige a chamada no turno seguinte. Consulte Tratamento de erros com is_error.

Ferramentas para entradas visuais complexas

Para gráficos densos e desenhos técnicos, dê ao Claude Sonnet 5.5 uma forma de recortar, ampliar ou executar código na imagem. Com essas ferramentas, o modelo lê essas entradas com precisão significativamente maior. Em gráficos, as ferramentas ajudam em todos os níveis de esforço. Em desenhos técnicos, elas ajudam apenas a partir do esforço high, e mais em xhigh e max. Para gráficos, adicionar ferramentas ajuda mais do que aumentar o esforço: em testes, com ferramentas e esforço high, o modelo leu gráficos com mais precisão do que sem ferramentas e com esforço max, por uma fração do custo. A receita da ferramenta de recorte tem uma definição de ferramenta funcional.

Recusas de salvaguarda

O Claude Sonnet 5.5 executa classificadores de segurança que podem recusar uma solicitação. Uma recusa chega como uma resposta normal com stop_reason: "refusal", e stop_details.category indica a categoria da recusa:

• cyber: a solicitação poderia possibilitar danos cibernéticos, como o desenvolvimento de malware ou exploits. Encontrar vulnerabilidades em código-fonte é permitido. Trabalho de cibersegurança de uso duplo de alto risco não é permitido.
• bio: a solicitação poderia possibilitar danos biológicos, como métodos laboratoriais perigosos. Perguntas cotidianas de saúde e educacionais não são afetadas.
• frontier_llm: a solicitação poderia auxiliar o desenvolvimento de modelos de IA concorrentes.
• reasoning_extraction: a solicitação pede ao modelo que reproduza seu raciocínio interno no texto da resposta.
• general_harms: a solicitação se enquadra em outra área da política de uso. Trabalhos benignos também podem acionar essa categoria.

Se o classificador bio bloquear o trabalho de ciências da vida da sua organização, você pode se inscrever no Programa de Verificação de Ciências da Vida.

Se você ativar o fallback no lado do servidor (beta), ele tenta novamente as recusas cyber e frontier_llm no Claude Sonnet 5. Ele não tenta novamente as recusas bio, reasoning_extraction ou general_harms. Consulte Recusas, fallback e cobrança.

Se seus prompts pedem ao modelo que inclua seu raciocínio na resposta, remova essas instruções, porque elas provocam recusas reasoning_extraction. Com o pensamento adaptativo, leia o raciocínio a partir de blocos de pensamento resumido (display: "summarized").