Pensamento Estendido, Esforço e Melhores Práticas Multimodais

Práticas numeradas para obter resultados confiáveis e eficientes em termos de custo a partir do pensamento estendido, do parâmetro de esforço e da entrada multimodal.

Como Usar Esta Lista

• Trate cada regra como um padrão para desviar deliberadamente, não como uma lei rígida.
• Aplique primeiro as regras de esforço e pensamento, pois elas afetam o custo em cada solicitação.
• Aplique as regras multimodais quando sua carga de trabalho incluir imagens ou documentos.
• Revise periodicamente estas práticas à medida que os padrões de uso e as metas de custo mudam.

A - Pensamento Estendido

• Habilite o pensamento adaptativo com thinking={"type": "adaptive"} em vez de adivinhar um orçamento fixo de raciocínio. O pensamento adaptativo permite que o Claude calibre a profundidade por solicitação, evitando tanto o sub-raciocínio em tarefas difíceis quanto o desperdício de raciocínio em tarefas fáceis.
• Trate um bloco thinking ausente como esperado, não como um erro. Prompts simples geralmente não produzem raciocínio visível sob pensamento adaptativo; investigue apenas se um prompt genuinamente complexo não retornar nenhum.
• Analise response.content iterando e verificando block.type, nunca por índice fixo. O bloco thinking, quando presente, pode ocupar o índice 0, deslocando a posição do bloco text.
• Orce max_tokens generosamente para prompts que provavelmente acionarão raciocínio profundo. Tokens de raciocínio e tokens de resposta compartilham o mesmo orçamento de saída, e um bloco thinking truncado pode cortar a resposta final.
• Registre ou armazene o bloco thinking separadamente da resposta voltada para o usuário. Isso suporta a depuração e a auditoria do raciocínio sem confundi-lo com a resposta que seus usuários veem.

B - Ajuste de Esforço

• Mapeie o nível de esforço ao tipo de tarefa em vez de codificar uma configuração para toda a aplicação. Classificação e extração se encaixam em low, respostas gerais de assistente se encaixam em medium, revisão de código e planejamento se encaixam em high, análise crítica de segurança se encaixa em max.
• Avalie a latência e o custo em cada nível de esforço candidato em relação ao tráfego real antes de enviar uma alteração. high e max podem desacelerar significativamente um endpoint voltado para o usuário; meça antes de se comprometer.
• Crie um conjunto de avaliação que inclua seus prompts do mundo real mais difíceis antes de escolher um nível de esforço padrão. O impacto da qualidade do esforço é mais visível em tarefas genuinamente difíceis; testar apenas em prompts fáceis esconde a diferença.
• Valide as strings de esforço contra o conjunto conhecido (low, medium, high, max) antes de enviar a solicitação. Capturar um erro de digitação como "med" no ponto de chamada é mais barato do que depurar um erro opaco da API mais tarde.
• Reserve o esforço max para chamadas genuinamente de alto risco. Aplicá-lo amplamente "por segurança" infla o custo e a latência em toda a aplicação sem um benefício de qualidade correspondente em tarefas rotineiras.

C - Exibição do Pensamento

• Mantenha a exibição do pensamento separada do esforço em seu modelo mental e em seu código. O esforço controla a profundidade do raciocínio e o custo; a exibição controla se esse raciocínio é retornado resumido ou omitido.
• Padrão para exibição omitida para respostas de produção voltadas para o usuário. O raciocínio bruto ou mesmo resumido geralmente é destinado à depuração, não como a superfície de resposta principal.
• Proteja qualquer exibição de raciocínio por meio de uma opção de interface do usuário explícita. Se você mostrar aos usuários uma justificativa, faça disso uma ação deliberada de "mostrar raciocínio" em vez de uma saída sempre visível.
• Mantenha o raciocínio resumido em um log de auditoria para cargas de trabalho críticas de segurança ou sensíveis à conformidade, mesmo quando omitido da resposta do usuário final. Isso preserva a rastreabilidade sem expor o raciocínio interno aos usuários finais.
• Remova ou resuma blocos thinking anteriores antes de anexá-los ao histórico de uma conversa com vários turnos. Reenviar blocos de raciocínio brutos como texto simples do assistente incha o uso de tokens em uma conversa longa.

D - Envio de Imagens

• Derive media_type do formato real do arquivo, nunca o codifique ou adivinhe. Um media_type incompatível pode causar um erro na solicitação ou uma leitura incorreta da imagem.
• Sempre codifique em base64 os bytes da imagem com base64.standard_b64encode(...).decode("utf-8") antes de atribuir a data. A API espera uma string base64, não bytes brutos ou um caminho de arquivo.
• Redimensione ou comprima imagens excessivamente grandes antes de codificar. Base64 infla o tamanho da carga útil em aproximadamente um terço em relação ao arquivo bruto, e imagens desnecessariamente grandes aumentam o tamanho da solicitação e o custo.
• Associe cada bloco de imagem a uma instrução de texto específica descrevendo o que analisar. Uma imagem sem uma pergunta acompanhante deixa o Claude adivinhando a intenção.
• Prefira a API de Arquivos em vez de base64 inline para qualquer imagem ou documento usado em mais de uma solicitação. Reenviar a mesma carga útil codificada repetidamente desperdiça largura de banda e tokens para conteúdo que não mudou.

E - API de Arquivos e Documentos de Múltiplas Solicitações

• Faça o upload de um documento uma vez e armazene seu file_id de forma durável, não apenas em uma variável local. Persistir file_id ao lado do seu próprio identificador de documento evita uploads redundantes entre execuções de processo.
• Lide com o caso em que um file_id referenciado expirou ou é inválido. As políticas de retenção variam por conta; capture o erro e faça o upload novamente se o arquivo de origem ainda estiver disponível.
• Inclua apenas os turnos anteriores relevantes na solicitação de acompanhamento messages, não todo o seu histórico de sessão local. A API sabe apenas o que está na lista messages da solicitação atual; mantenha um histórico mais completo localmente para registro sem reenviar tudo.
• Varie o esforço por pergunta ao fazer uma sequência de perguntas sobre o mesmo documento. Uma simples consulta e uma pergunta de referenciamento cruzado têm necessidades de raciocínio diferentes, mesmo contra o mesmo arquivo.
• Defina purpose explicitamente em cada chamada de upload da API de Arquivos. Omitir ou definir incorretamente pode tornar o arquivo carregado inutilizável em um bloco de conteúdo de documento posteriormente.

FAQs

Relacionado

• Pensamento Estendido e o Parâmetro de Esforço Explicados - a base conceitual para as práticas A a C.
• Ajustando o Parâmetro de Esforço para Custo e Velocidade - um guia mais aprofundado da prática B.
• Níveis de Esforço e Opções de Exibição de Pensamento Referência - a tabela de referência que essas práticas assumem.
• Enviando Imagens para Análise de Visão com Codificação Base64 - os detalhes completos por trás do grupo de práticas D.
• Carregando e Referenciando PDFs com a API de Arquivos - os detalhes completos por trás do grupo de práticas E.

Versões da Stack: Escrito contra a linha de modelos Claude atual em aproximadamente junho de 2026 - Claude Fable 5, Claude Opus 4.8, Claude Sonnet 5 (o padrão) e Claude Haiku 4.5 - e o SDK oficial anthropic Python (última versão 0.x). Nomes de modelos, versões de SDK e preços mudam rapidamente - verifique os detalhes atuais em platform.claude.com/docs antes de confiar neles.