Melhores Práticas de Engenharia de Prompt e Contexto

Reduzir o gasto de tokens e proteger a qualidade da resposta não são objetivos conflitantes: a mesma disciplina geralmente alcança ambos ao mesmo tempo.

Este é um checklist independente de práticas para decidir o que entra em um prompt, qual modelo o processa e como um agente de longa duração gerencia seu contexto ao longo do tempo.

Como Usar Este Checklist

• Trate cada categoria como uma passagem de revisão sobre um prompt, tarefa ou agente específico, não como uma auditoria global única.
• Marque os itens em relação a uma carga de trabalho real, não de forma abstrata; uma regra que parece correta, mas não tem efeito medido em sua tarefa, não vale a pena ser aplicada.
• Revise esta lista sempre que as entradas, o volume ou os riscos de uma tarefa mudarem significativamente.
• Emparelhe cada regra aqui com um conjunto de avaliação real, sempre que possível; uma melhor prática sem uma forma de medir seu efeito é um palpite disfarçado de regra.

A - Minimize o Que Você Envia

• Envie apenas os trechos que uma tarefa necessita, não arquivos ou repositórios inteiros. Cortar para o material relevante remove tokens diretamente, sem a necessidade de uma chamada de API adicional.
• Para tarefas de código, use um grafo de dependências para selecionar arquivos relevantes em vez de adivinhar. Um bairro de um salto de importações e importadores geralmente é contexto suficiente para uma alteração de arquivo único.
• Corte dados estruturados (JSON, linhas de banco de dados) para uma lista explícita de campos permitidos. Uma lista de permissões é mais segura do que uma lista de negação, pois novos campos adicionados posteriormente não serão silenciosamente incluídos nos prompts.
• Descarte o histórico de conversas obsoleto que não afeta mais a tarefa atual. Cada turno anterior mantido em uma conversa com múltiplos turnos é reenviado como tokens de entrada em cada chamada futura.
• Meça as contagens de tokens antes e depois do corte, não apenas a intuição. Uma chamada rápida count_tokens transforma "isso parece menor" em um número que você pode acompanhar ao longo do tempo.

B - Resuma Documentos Longos Reutilizáveis

• Use um modelo barato e rápido para pré-condensar documentos longos antes de enviá-los para um modelo mais caro. O custo da própria chamada de sumarização é pequeno em comparação com a economia assim que o documento for reutilizado.
• Resuma apenas documentos que serão referenciados mais de uma vez. Um documento de uso único raramente compensa o custo da chamada de sumarização adicional.
• Passe uma instrução de foco para o sumarizador quando você souber o que a tarefa downstream precisa. Um resumo genérico corre o risco de descartar o único detalhe que importava.
• Armazene resumos em cache por identidade do documento e invalide o cache quando a origem mudar. Re-sumarizar um documento inalterado em cada chamada descarta todo o benefício de custo.
• Evite resumir texto crítico de precisão, como contratos ou figuras exatas. A sumarização é inerentemente com perdas; extraia a seção relevante exata em vez disso quando a precisão for importante.

C - Combine o Nível do Modelo com a Tarefa

• Roteie cada categoria de tarefa para o modelo mais barato que ainda atende ao seu padrão de qualidade. Reserve modelos mais fortes como Opus 4.8 para tarefas que realmente necessitam de raciocínio mais profundo.
• Baseie as decisões de nivelamento em um conjunto de avaliação, não em intuição. Um checklist de nivelamento de modelo estreita a busca, mas apenas a taxa de aprovação medida confirma a escolha.
• Permita que o risco financeiro, de conformidade ou de reversibilidade substitua a aparente simplicidade de uma tarefa. Uma tarefa que parece fácil pelo número de etapas de raciocínio ainda pode justificar um nível mais forte se uma resposta errada for custosa.
• Revise as decisões de nivelamento quando as entradas da tarefa ou um novo modelo na linha de frente mudarem o cenário. Uma decisão de nível tomada uma vez no lançamento pode ficar desatualizada.
• Documente qual nível lida com qual categoria de tarefa e por quê. O nivelamento ad hoc e não documentado é difícil para uma equipe manter ou revisar.

D - Ajuste o Esforço de Raciocínio Deliberadamente

• Varra o parâmetro de esforço de baixo para máximo contra um conjunto de avaliação real, em vez de usar o máximo por padrão. A configuração mais barata que ainda passa no seu padrão de qualidade é a que deve ser enviada.
• Defina o limite de qualidade com base no custo de uma resposta errada para essa tarefa específica. Uma tarefa de baixo risco pode tolerar um limite mais flexível do que uma adjacente a faturamento ou conformidade.
• Aumente o conjunto de avaliação a partir de falhas reais de produção ao longo do tempo. Um punhado de casos escolhidos a dedo se ajustará excessivamente ao que você pensou quando os escreveu.
• Trate o esforço e o tamanho do contexto como alavancas independentes. Aumentar o esforço não corrige um prompt que carece de contexto necessário, e cortar o contexto não substitui o esforço em uma tarefa de raciocínio genuinamente difícil.
• Reexecute a varredura de esforço quando o modelo de prompt ou a versão do modelo mudarem. Um resultado de varredura é um instantâneo, não um fato permanente sobre a tarefa.

E - Gerencie o Contexto de Agente Multi-Turno

• Armazene em cache os resultados das ferramentas e deduplique chamadas repetidas idênticas dentro de uma sessão. Uma chamada de ferramenta redundante custa duas vezes: uma para executar e outra enquanto é carregada em cada histórico de turno futuro.
• Nunca armazene em cache chamadas de ferramentas mutáveis, apenas consultas somente leitura. Reexecutar uma escrita, como cobrar um cartão, é o objetivo, não uma redundância a ser eliminada.
• Defina um orçamento explícito de janela de contexto para agentes de longa duração, não um implícito. Um orçamento que não é documentado tende a ser descoberto apenas depois que uma sessão atinge um limite rígido.
• Defina um gatilho de compactação concreto e o que ele preserva. Saiba exatamente qual condição dispara a sumarização ou truncamento, e o que deve sobreviver a ela, como o objetivo original do usuário.
• Escopo os caches de resultados de ferramentas por sessão, não globalmente, em sistemas multi-inquilino. Um cache compartilhado e sem escopo pode vazar resultados de um usuário para o contexto de outro usuário.

F - Proteja Contra a Degradação do Contexto

• Trate "devo incluir isso" como uma pergunta real, não como um sim padrão. Material irrelevante pode degradar a qualidade da resposta, não apenas adicionar custo.
• Fique atento a conteúdo distrator: material irrelevante que se assemelha superficialmente à resposta correta. Uma variável com o mesmo nome ou uma definição duplicada obsoleta pode induzir o modelo ao erro ativamente, em vez de ser simplesmente ignorada.
• Não trate uma janela de contexto maior como permissão para pular o corte. Uma janela maior muda o que cabe, não o que é relevante.
• Compare a qualidade da resposta em um prompt cortado versus um preenchido quando em dúvida. Se a qualidade não cair mensuravelmente com um prompt menor, o material extra não estava justificando seu custo.
• Equilibre contra o corte excessivo. Cortar algo genuinamente relevante produz uma falha diferente da degradação do contexto; o objetivo é a relevância, não o minimalismo por si só.

G - Documente e Revise Decisões

• Escreva os orçamentos de contexto, gatilhos de compactação e decisões de nivelamento à medida que são tomadas, não depois do fato. Um registro no estilo ADR torna essas decisões revisáveis em vez de conhecimento tribal.
• Nomeie um responsável por cada decisão de custo/qualidade. Uma decisão sem responsável tende a ficar desatualizada à medida que a tarefa subjacente ou a linha de frente de modelos muda.
• Defina uma cadência de revisão, não uma decisão única. A revisão trimestral é um padrão razoável para categorias de tarefas de alto volume.
• Rastreie uma métrica concreta que sinalizaria que as configurações atuais estão erradas. A compactação disparando com muita frequência, a taxa de aprovação caindo ou o custo excedendo a meta são todos sinais que valem a pena alertar.

FAQs

Relacionados

• Como a Engenharia de Contexto Reduz o Gasto de Tokens - o modelo mental por trás de cada prática nesta página.
• Checklist de Nivelamento de Modelos - uma análise mais aprofundada da categoria C.
• Degradação do Contexto: Por Que Mais Tokens Não Significam Respostas Melhores - o raciocínio por trás da categoria F.
• Modelo ADR: Definindo um Orçamento de Janela de Contexto para um Agente de Produção - um modelo para documentar as decisões na categoria G.
• Evitando Chamadas de Ferramentas Redundantes em Loops de Agente Multi-Turno - uma análise mais aprofundada da categoria E.

Versões da Stack: Escrito contra a linha de modelos Claude atual em ~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 para Python (última versão 0.x). Nomes de modelos, preços e versões de SDK mudam rapidamente - verifique os detalhes atuais em platform.claude.com/docs antes de confiar neles.