fundamentos-de-engenharia-de-contexto

Fundamentos da Engenharia de Contexto

Contexto é o estado completo disponível para um modelo de linguagem no momento da inferência: instruções do sistema, definições de ferramentas, documentos recuperados, histórico de mensagens e saídas de ferramentas. Engenharia de contexto é a disciplina de selecionar o menor conjunto de tokens de alto sinal que maximiza a probabilidade dos resultados desejados.

Esta habilidade é a base conceitual sobre a qual todas as outras habilidades da coleção se constroem. Ela explica o que é contexto, como funciona a mecânica de atenção, por que a qualidade do contexto importa mais que a quantidade e os modelos mentais necessários para interpretar qualquer outra decisão de engenharia de contexto. Ela não é responsável pelo trabalho operacional: depuração de falhas de atenção pertence a context-degradation, táticas de eficiência de tokens pertencem a context-optimization, sumarização de conversas pertence a context-compression, offloading baseado em arquivos pertence a filesystem-context, e decisões de formato de projeto pertencem a project-development.

Quando Ativar

Ative esta habilidade quando o trabalho for conceitual:

• Explicar o que é contexto e como a mecânica de atenção restringe o comportamento do agente.
• Integrar novos contribuidores que precisam dos modelos mentais antes de mergulhar em habilidades operacionais.
• Raciocinar sobre uma decisão de design relacionada a contexto a partir de primeiros princípios (o que essa restrição significa, por que essa compensação existe) antes de escolher uma tática específica.
• Escrever ou revisar documentação que precisa fundamentar a orientação operacional na mecânica subjacente.

Não ative esta habilidade para trabalho operacional. As habilidades especializadas lidam com a execução:

• Diagnosticar problemas de "perdido no meio", envenenamento de contexto ou falhas de atenção: context-degradation.
• Reduzir custo de tokens via mascaramento, particionamento, cache de prefixo, orçamentos: context-optimization.
• Comprimir uma sessão longa em um resumo de transição: context-compression.
• Descarregar saídas grandes de ferramentas ou manter um bloco de rascunho durável: filesystem-context.
• Decidir o formato de um projeto ou pipeline de LLM: project-development.

Conceitos Centrais

Trate o contexto como um orçamento finito de atenção, não como um recipiente de armazenamento. Cada token adicionado compete pela atenção do modelo e esgota um orçamento que não pode ser reabastecido no meio da inferência. O problema de engenharia é maximizar a utilidade por token diante de três restrições: o limite rígido de tokens, o teto mais suave de capacidade efetiva e a curva de atenção em forma de U que penaliza informações colocadas no meio do contexto (claim-context-degradation-lost-middle-ruler).

Aplique quatro princípios ao montar o contexto:

1. Informatividade sobre exaustividade — inclua apenas o que importa para a decisão atual; projete sistemas que possam recuperar informações adicionais sob demanda.
2. Posicionamento consciente da posição — coloque restrições críticas no início e no fim do contexto, porque avaliações de contexto longo mostram que informações em posição intermediária são recuperadas de forma menos confiável do que informações nas bordas (claim-context-degradation-lost-middle-ruler).
3. Divulgação progressiva — carregue nomes e resumos de habilidades na inicialização; carregue o conteúdo completo somente quando uma habilidade for ativada para uma tarefa específica.
4. Curadoria iterativa — a engenharia de contexto não é um exercício único de escrita de prompt, mas uma disciplina contínua aplicada toda vez que o conteúdo é passado para o modelo.

Tópicos Detalhados

A Anatomia do Contexto

Prompts de Sistema Organize os prompts de sistema em seções distintas usando tags XML ou cabeçalhos Markdown (contexto, instruções, orientação de ferramentas, formato de saída). Os prompts de sistema persistem durante toda a conversa, portanto, coloque as restrições mais críticas no início e no fim, onde a atenção é mais forte.

Calibre a altitude da instrução para equilibrar dois modos de falha. Altitude muito baixa codifica lógica frágil que quebra quando as condições mudam. Altitude muito alta fornece orientação vaga que falha em dar sinais concretos para o comportamento desejado. Busque instruções orientadas por heurística: específicas o suficiente para guiar o comportamento, flexíveis o suficiente para generalizar — por exemplo, etapas numeradas com espaço para julgamento em cada etapa.

Comece com o mínimo e adicione instruções reativamente com base nos modos de falha observados, em vez de incluir preventivamente casos extremos. Selecione exemplos diversos e canônicos de few-shot que retratem o comportamento esperado, em vez de listar todos os cenários possíveis.

Definições de Ferramentas Escreva descrições de ferramentas que respondam a três perguntas: o que a ferramenta faz, quando usá-la e o que ela retorna. Inclua contexto de uso, valores padrão de parâmetros e casos de erro — os agentes não conseguem desambiguar ferramentas que um engenheiro humano também não consegue desambiguar.

Mantenha o conjunto de ferramentas mínimo. Consolide ferramentas sobrepostas, pois conjuntos de ferramentas inchados criam pontos de decisão ambíguos e consomem contexto desproporcionalmente após a serialização JSON (os esquemas de ferramentas normalmente inflam 2-3 vezes em comparação com descrições de texto simples equivalentes).

Documentos Recuperados Mantenha identificadores leves (caminhos de arquivo, consultas armazenadas, links da web) e carregue dados no contexto dinamicamente usando recuperação just-in-time. Isso espelha a cognição humana — mantenha um índice, não uma cópia. Identificadores fortes (por exemplo, customer_pricing_rates.json) permitem que os agentes localizem arquivos relevantes mesmo sem ferramentas de busca; identificadores fracos (por exemplo, data/file1.json) forçam carregamentos desnecessários.

Ao dividir documentos grandes em partes, divida nos limites semânticos naturais (cabeçalhos de seção, quebras de parágrafo) em vez de limites arbitrários de caracteres que cortam conceitos no meio.

Histórico de Mensagens O histórico de mensagens serve como a memória de bloco de rascunho do agente para rastrear o progresso, manter o estado da tarefa e preservar o raciocínio entre as etapas. Para tarefas de longa duração, pode crescer a ponto de dominar o uso do contexto — monitore e aplique compactação antes que ele tome o espaço das instruções ativas.

Refine ciclicamente o histórico: uma vez que uma ferramenta tenha sido chamada no fundo da conversa, o resultado bruto raramente precisa permanecer textualmente. Substitua saídas de ferramentas obsoletas por resumos compactos ou referências para reduzir o volume de baixo sinal.

Saídas de Ferramentas As saídas de ferramentas geralmente dominam o contexto nas trajetórias dos agentes (claim-context-optimization-tool-output-dominance). Aplique mascaramento de observação: substitua saídas detalhadas por referências compactas depois que o agente processar o resultado. Retenha apenas os conteúdos de arquivo mais recentemente relevantes; comprima ou remova os mais antigos.

Janelas de Contexto e Mecânica de Atenção

O Orçamento de Atenção Para n tokens, o mecanismo de atenção calcula relacionamentos aos pares de n ao quadrado. À medida que o contexto cresce, a capacidade do modelo de manter esses relacionamentos se degrada — não como um limite abrupto, mas como um gradiente de desempenho. Modelos treinados predominantemente em sequências mais curtas têm menos parâmetros especializados para dependências de largura de contexto, criando um teto efetivo bem abaixo do tamanho nominal da janela.

Projete para esse gradiente: assuma que a capacidade efetiva está materialmente abaixo da janela anunciada até que seja medida na carga de trabalho alvo. Janelas de contexto nominais grandes não eliminam a necessidade de testes de degradação específicos da tarefa (claim-context-degradation-lost-middle-ruler).

Limites de Codificação Posicional A interpolação de codificação posicional estende o manuseio de sequências além dos comprimentos de treinamento, mas introduz degradação na precisão posicional. Espere precisão reduzida para recuperação de informações e raciocínio de longo alcance em contextos estendidos em comparação com o desempenho em entradas mais curtas.

Divulgação Progressiva na Prática Implemente a divulgação progressiva em três níveis:

1. Seleção de habilidade — carregue apenas nomes e descrições na inicialização; ative o conteúdo completo da habilidade sob demanda.
2. Carregamento de documento — carregue resumos primeiro; busque seções de detalhes somente quando a tarefa exigir.
3. Retenção de resultado de ferramenta — mantenha resultados recentes na íntegra; comprima ou remova resultados mais antigos.

Mantenha o limite nítido: se uma habilidade ou documento for ativado, carregue-o completamente, em vez de parcialmente — carregamentos parciais criam lacunas confusas que degradam a qualidade do raciocínio.

Qualidade Versus Quantidade do Contexto

Rejeite a suposição de que janelas de contexto maiores resolvem problemas de memória. O custo de processamento cresce desproporcionalmente com o comprimento do contexto — não apenas escalonamento linear de custo, mas desempenho degradado do modelo além dos limites de capacidade efetiva. Entradas longas permanecem caras mesmo com cache de prefixo.

Aplique o teste de densidade de sinal: para cada parte do contexto, pergunte se removê-la alteraria a saída do modelo. Se não, remova-a. Conteúdo redundante não apenas desperdiça tokens — ele dilui ativamente a atenção do conteúdo de alto sinal.

Orientação Prática

Esta seção fornece conselhos conceituais de aplicação. As referências a habilidades operacionais são explícitas.

Raciocinando Sobre uma Decisão de Contexto

Quando uma decisão de design relacionada a contexto precisa ser tomada, separe a questão conceitual da operacional. A questão conceitual é "o que isso significa e por que importa"; a questão operacional é "qual técnica específica aplicamos". Use esta habilidade para responder à primeira; direcione para a habilidade especializada que é responsável pela segunda.

Por exemplo, decidir se deve resumir uma longa sessão de agente tem duas partes: (1) por que a sumarização é necessária (o orçamento de atenção é finito, a curva em forma de U degrada o conteúdo do meio, a densidade do sinal importa mais que o volume — esta habilidade) e (2) qual estratégia de compressão preserva o estado certo e em qual limite de utilização acioná-la (context-compression).

Ordem de Leitura para Novos Contribuidores

Um contribuidor que está começando na engenharia de contexto deve ler:

1. Esta habilidade, para internalizar o enquadramento do orçamento de atenção e a curva em forma de U.
2. context-degradation, para ver como as falhas de contexto parecem na prática e como diagnosticá-las.
3. Duas ou três de context-optimization, context-compression, filesystem-context, memory-systems, dependendo de qual preocupação operacional é mais relevante para seu projeto.

Pular o passo 1 produz operadores que aplicam técnicas sem entender por quê; pular as habilidades operacionais produz teóricos que não sabem qual técnica se encaixa em qual modo de falha.

Exemplos

Exemplo 1: Organizando Prompts de Sistema

Ilustra o ponto conceitual de que restrições críticas pertencem a posições favorecidas pela atenção (início e fim), e que limites de seção explícitos ajudam o modelo a analisar o prompt:

<INFORMACOES_DE_CONTEXTO>
Você é um especialista em Python ajudando uma equipe de desenvolvimento.
Projeto atual: Pipeline de processamento de dados em Python 3.9+
</INFORMACOES_DE_CONTEXTO>

<INSTRUCOES>
- Escreva código Python limpo e idiomático
- Inclua dicas de tipo para assinaturas de funções
- Adicione docstrings para funções públicas
- Siga as diretrizes de estilo PEP 8
</INSTRUCOES>

<DESCRICAO_DA_SAIDA>
Forneça blocos de código com destaque de sintaxe.
Explique decisões não óbvias em comentários.
</DESCRICAO_DA_SAIDA>

Exemplo 2: O Orçamento de Atenção Como Um Modelo Mental

Um modelo de contexto grande não tem um contexto igualmente atendido. A capacidade efetiva é específica da carga de trabalho, e a curva em forma de U penaliza informações colocadas no meio. Ao decidir quanto de uma base de conhecimento upstream carregar, este é o modelo mental: não pergunte "caberá", pergunte "o modelo ainda atenderá às partes que importam".

A questão operacional correspondente (qual técnica deve reduzir a carga) pertence a context-optimization.

Diretrizes

1. Trate o contexto como um recurso finito com retornos decrescentes
2. Coloque informações críticas em posições favorecidas pela atenção (início e fim)
3. Use divulgação progressiva para adiar o carregamento até que seja necessário
4. Organize prompts de sistema com limites de seção claros
5. Monitore o uso do contexto durante o desenvolvimento
6. Implemente acionadores de compactação em 70-80% de utilização
7. Projete para degradação do contexto em vez de esperar evitá-la
8. Prefira contexto menor de alto sinal a contexto maior de baixo sinal

Pegadinhas

1. Janela nominal não é capacidade efetiva: Um modelo que anuncia uma grande janela de contexto pode degradar bem antes desse limite em tarefas complexas de recuperação ou raciocínio. Orce abaixo da janela nominal até que seus próprios testes de degradação provem o contrário.

2. Estimativas de tokens baseadas em caracteres flutuam silenciosamente: A heurística de ~4 caracteres/token para prosa em inglês falha para código (2-3 caracteres/token), URLs e caminhos de arquivo (cada barra, ponto e dois pontos é um token separado) e texto não inglês (geralmente 1-2 caracteres/token). Use o tokenizador real do provedor (por exemplo, tiktoken para modelos OpenAI, a API de contagem de tokens da Anthropic) para qualquer cálculo crítico de orçamento.

3. Esquemas de ferramentas inflam 2-3x após serialização JSON: Uma definição de ferramenta que parece compacta no código-fonte se expande significativamente quando serializada — colchetes, aspas, dois pontos e vírgulas consomem tokens. Dez ferramentas com esquemas moderados podem consumir 5.000-8.000 tokens antes que uma única mensagem seja enviada. Audite contagens de tokens de ferramentas serializadas, não contagens de linhas de código-fonte.

4. O histórico de mensagens incha silenciosamente em loops agentivos: Cada chamada de ferramenta adiciona tanto a solicitação quanto a resposta completa ao histórico. Após 20-30 iterações, o histórico pode consumir 70-80% da janela enquanto o agente não mostra sintomas visíveis até que a qualidade do raciocínio caia. Defina um teto rígido de tokens para o histórico e acione a compactação proativamente.

5. Instruções críticas no meio se perdem: A curva de atenção em forma de U significa que o meio do contexto recebe 10-40% menos precisão de recuperação do que o início e o fim. Nunca coloque restrições de segurança, requisitos de formato de saída ou proteções comportamentais no meio de um prompt de sistema longo — ancore-os no topo ou na base.

6. Divulgação progressiva que carrega com muita avidez derrota seu propósito: Carregar toda habilidade ou documento "potencialmente relevante" ao primeiro indício de relevância recria o problema de entupimento de contexto. Defina limites de ativação rigorosos — uma habilidade deve ser carregada somente quando a tarefa corresponder explicitamente às suas condições de acionamento, não quando o tópico for meramente adjacente.

7. Misturar altitudes de instrução causa comportamento inconsistente: Combinar regras hiperespecíficas ("sempre use exatamente 3 bullets points") com orientação de alto nível ("use seu melhor julgamento") cria sinais conflitantes que o modelo não consegue resolver. Mantenha a altitude consistente em todo o prompt de sistema.