compressão-de-contexto

Estratégias de Compressão de Contexto

Quando as sessões de agente geram milhões de tokens de histórico de conversa, a compressão se torna obrigatória. A abordagem ingênua é a compressão agressiva para minimizar tokens por requisição. O alvo de otimização correto é tokens por tarefa: total de tokens consumidos para completar uma tarefa, incluindo custos de re-busca quando a compressão perde informações críticas.

Quando Ativar

Ative esta skill quando:

• Sessões de agente excedem os limites da janela de contexto
• Bases de código excedem as janelas de contexto (sistemas com 5M+ tokens)
• Projetando estratégias de sumarização de conversa
• Depurando casos onde agentes "esquecem" quais arquivos modificaram
• Construindo estruturas de avaliação para qualidade de compressão
• Criando resumos de handoff duráveis que preservam decisões, arquivos, riscos e próximas ações

Não ative esta skill para trabalhos adjacentes de propriedade de outras skills:

• Táticas gerais de eficiência de token, como mascaramento, prefix caching ou particionamento: context-optimization.
• Diagnosticando por que um contexto longo está falhando antes de escolher uma mitigação: context-degradation.
• Escrevendo saídas brutas, logs ou planos em arquivos sem resumi-los: filesystem-context.
• Projetando memória semântica de longo prazo entre sessões: memory-systems.
• O modelo decidindo quando e onde reescrever seu próprio contexto: self-managed-context. Esta skill ainda define o que o texto de substituição deve preservar.

Conceitos Centrais

A compressão de contexto troca economia de tokens por perda de informação. Selecione entre três abordagens prontas para produção com base nas características da sessão:

1. Sumarização Iterativa Ancorada: Implemente esta para sessões de longa duração onde o rastreamento de arquivos é importante. Mantenha sumários persistentes e estruturados com seções explícitas para intenção da sessão, modificações de arquivos, decisões e próximos passos. Quando a compressão for acionada, sumarize apenas o trecho recém-truncado e mescle com o sumário existente, em vez de regenerar do zero. Isso evita o desvio que se acumula quando os sumários são regenerados por completo — cada regeneração corre o risco de perder detalhes que o modelo considera de baixa prioridade, mas a tarefa exige. A estrutura força a preservação porque seções dedicadas atuam como listas de verificação que o sumarizador deve preencher, capturando a perda silenciosa de informação.

2. Compressão Opaca: Reserve esta para sessões curtas onde os custos de re-busca são baixos e a economia máxima de tokens é necessária. Ela produz representações comprimidas otimizadas para fidelidade de reconstrução, alcançando taxas de compressão de 99%+, mas sacrificando completamente a interpretabilidade. A compensação é importante: não há como verificar o que foi preservado sem uma avaliação baseada em sondas, portanto, nunca use esta quando a depuração ou o rastreamento de artefatos for crítico.

3. Sumário Regenerativo Completo: Use esta quando a legibilidade do sumário for crítica e as sessões tiverem limites de fase claros. Ela gera sumários estruturados detalhados em cada gatilho de compressão. A fraqueza é a perda cumulativa de detalhes ao longo de ciclos repetidos — cada regeneração completa é uma nova passagem que pode despriorizar detalhes preservados em sumários anteriores.

Tópicos Detalhados

Otimize para Tokens por Tarefa, Não Tokens por Requisição

Meça o total de tokens consumidos do início ao fim da tarefa, não tokens por requisição individual. Quando a compressão elimina caminhos de arquivo, mensagens de erro ou justificativa de decisão, o agente precisa re-explorar, reler arquivos e re-derivar conclusões — desperdiçando muito mais tokens do que a compressão economizou. Uma estratégia que economiza 0,5% a mais de tokens por requisição, mas causa 20% mais re-buscas, custa mais no geral. Monitore a frequência de re-busca como o principal sinal de qualidade: se o agente pede repetidamente para reler arquivos que já processou, a compressão está muito agressiva.

Resolva o Problema do Rastro de Artefatos Primeiro

A integridade do rastro de artefatos é frequentemente a dimensão mais fraca nas avaliações de compressão (claim-context-compression-factory-benchmark). Aborde isso proativamente porque a sumarização geral não consegue mantê-la de forma confiável.

Preserve estas categorias explicitamente em cada ciclo de compressão:

• Quais arquivos foram criados (caminhos completos)
• Quais arquivos foram modificados e o que mudou (inclua nomes de funções, não apenas nomes de arquivos)
• Quais arquivos foram lidos, mas não alterados
• Identificadores específicos: nomes de funções, nomes de variáveis, mensagens de erro, códigos de erro

Implemente um índice de artefatos separado ou rastreamento explícito de estado de arquivos no scaffolding do agente, em vez de confiar no sumarizador para capturar esses detalhes. Mesmo a sumarização estruturada com seções de arquivo dedicadas tem dificuldades com a completude ao longo de sessões longas.

Estruture Sumários com Seções Obrigatórias

Construa sumários estruturados com seções explícitas que evitam a perda silenciosa de informação. Cada seção atua como uma lista de verificação que o sumarizador deve preencher, tornando as omissões visíveis em vez de silenciosas.

## Intenção da Sessão
[O que o usuário está tentando realizar]

## Arquivos Modificados
- auth.controller.ts: Corrigida geração de token JWT
- config/redis.ts: Atualizado pooling de conexão
- tests/auth.test.ts: Adicionada configuração de mock para novo config

## Decisões Tomadas
- Usando pool de conexão Redis em vez de conexões por requisição
- Lógica de retry com backoff exponencial para falhas transitórias

## Estado Atual
- 14 testes passando, 2 falhando
- Restante: configuração de mock para testes do service de sessão

## Próximos Passos
1. Corrigir falhas de teste restantes
2. Executar suíte de teste completa
3. Atualizar documentação

Adapte as seções ao domínio do agente. Um agente de depuração precisa de "Causa Raiz" e "Mensagens de Erro"; um agente de migração precisa de "Esquema de Origem" e "Esquema de Destino". A estrutura importa mais do que as seções específicas — qualquer esquema explícito supera a sumarização de forma livre.

Escolha Gatilhos de Compressão Estrategicamente

Quando acionar a compressão importa tanto quanto como comprimir. Selecione uma estratégia de gatilho com base na previsibilidade da sessão:

Estratégia	Ponto de Gatilho	Compensação
Limite fixo	70-80% de utilização do contexto	Simples, mas pode comprimir cedo demais
Janela deslizante	Manter últimos N turnos + sumário	Tamanho de contexto previsível
Baseado em importância	Comprimir seções de baixa relevância primeiro	Complexo, mas preserva o sinal
Limite de tarefa	Comprimir em conclusões lógicas de tarefa	Sumários limpos, mas tempo imprevisível

Padrão: janela deslizante com sumários estruturados para agentes de codificação — oferece o melhor equilíbrio entre previsibilidade e qualidade. Use gatilhos de limite de tarefa quando as sessões tiverem transições de fase claras (ex.: pesquisa, depois implementação, depois testes).

Avalie a Compressão com Sondas, Não Métricas

Métricas tradicionais como ROUGE ou similaridade de embedding falham em capturar a qualidade funcional da compressão. Um sumário pode pontuar alto em sobreposição lexical, mas perder o único caminho de arquivo que o agente precisa para continuar.

Use avaliação baseada em sonda: após a compressão, faça perguntas que testem se informações críticas sobreviveram. Se o agente responder corretamente, a compressão preservou a informação certa. Caso contrário, ele adivinha ou alucina.

Tipo de Sonda	O que Testa	Exemplo de Pergunta
Recall	Retenção factual	"Qual era a mensagem de erro original?"
Artefato	Rastreamento de arquivo	"Quais arquivos modificamos?"
Continuação	Planejamento de tarefa	"O que devemos fazer a seguir?"
Decisão	Cadeia de raciocínio	"O que decidimos sobre o problema do Redis?"

Pontue a Compressão em Seis Dimensões

Avalie a qualidade da compressão para agentes de codificação nestas dimensões. Acurácia e preservação do rastro de artefatos tendem a separar métodos mais claramente do que a similaridade lexical (claim-context-compression-factory-benchmark), então a compressão precisa de tratamento especializado além da sumarização geral.

1. Acurácia: Os detalhes técnicos estão corretos — caminhos de arquivo, nomes de função, códigos de erro?
2. Consciência de Contexto: A resposta reflete o estado atual da conversa?
3. Rastro de Artefatos: O agente sabe quais arquivos foram lidos ou modificados?
4. Completude: A resposta aborda todas as partes da pergunta?
5. Continuidade: O trabalho pode continuar sem re-buscar informações?
6. Seguimento de Instruções: A resposta respeita as restrições declaradas?

Orientação Prática

Aplique o Fluxo de Trabalho de Compressão em Três Fases para Grandes Bases de Código

Para bases de código ou sistemas de agente que excedem janelas de contexto, comprima em três fases sequenciais. Cada fase reduz o contexto para que a próxima opere dentro do orçamento.

1. Fase de Pesquisa: Explore diagramas de arquitetura, documentação e interfaces principais. Comprima a exploração em uma análise estruturada de componentes, dependências e limites. Saída: um único documento de pesquisa que substitui a exploração bruta.

2. Fase de Planejamento: Converta o documento de pesquisa em uma especificação de implementação com assinaturas de função, definições de tipo e fluxo de dados. Uma base de código de 5M tokens comprime para aproximadamente 2.000 palavras de especificação neste estágio.

3. Fase de Implementação: Execute contra a especificação. O contexto permanece focado na especificação mais arquivos de trabalho ativos, não na exploração bruta da base de código. Esta fase raramente precisa de mais compressão porque a especificação já é compacta.

Use Artefatos de Exemplo como Sementes de Compressão

Quando fornecido com um exemplo de migração manual ou PR de referência, use-o como modelo para entender o padrão alvo em vez de explorar a base de código do zero. O exemplo revela restrições que a análise estática não consegue descobrir: quais invariantes devem ser mantidos, quais serviços quebram com mudanças e como é uma implementação limpa.

Isso é mais importante quando o agente não consegue distinguir complexidade essencial (requisitos de negócio) de complexidade acidental (soluções legadas). O artefato de exemplo codifica essa distinção implicitamente, economizando tokens que, de outra forma, iriam para exploração por tentativa e erro.

Implemente a Sumarização Iterativa Ancorada Passo a Passo

1. Defina seções de sumário explícitas correspondentes ao domínio do agente (depuração, migração, desenvolvimento de funcionalidades)
2. No primeiro gatilho de compressão, sumarize o histórico truncado nessas seções
3. Em compressões subsequentes, sumarize apenas o conteúdo recém-truncado — não resuma o sumário existente
4. Mescle novas informações nas seções existentes em vez de regenerá-las, deduplicando por caminho de arquivo e identidade de decisão
5. Marque qual informação veio de qual ciclo de compressão — isso permite depuração quando os sumários divergem

Selecione a Abordagem Certa para o Perfil da Sessão

Use sumarização iterativa ancorada quando:

• As sessões são de longa duração (100+ mensagens)
• O rastreamento de arquivos é importante (codificação, depuração)
• A verificação da informação preservada é necessária

Use compressão opaca quando:

• A economia máxima de tokens é necessária
• As sessões são relativamente curtas
• Os custos de re-busca são baixos (ex.: nenhum acesso ao sistema de arquivos necessário)

Use sumários regenerativos quando:

• A interpretabilidade do sumário é crítica para revisão humana
• As sessões têm limites de fase claros
• A revisão completa do contexto é aceitável em cada gatilho de compressão

Calibre as Taxas de Compressão por Método

Método	Taxa de Compressão	Pontuação de Qualidade	Compensação
Iterativo Ancorado	98,6%	3,70	Melhor qualidade, compressão ligeiramente menor
Regenerativo	98,7%	3,44	Boa qualidade, compressão moderada
Opaco	99,3%	3,35	Melhor compressão, perda de qualidade

Use estes como valores de referência específicos da fonte, não constantes universais (claim-context-compression-factory-benchmark). Para qualquer tarefa onde existam custos de re-busca, esta compensação geralmente favorece abordagens estruturadas.

Exemplos

Exemplo 1: Compressão de Sessão de Depuração

Contexto original (89.000 tokens, 178 mensagens):

• Erro 401 no endpoint /api/auth/login
• Rastreamento através do controller de auth, middleware, armazenamento de sessão
• Encontrada conexão Redis obsoleta
• Corrigido pooling de conexão, adicionada lógica de retry
• 14 testes passando, 2 falhando

Sumário estruturado após compressão:

## Intenção da Sessão
Depurar erro 401 Unauthorized em /api/auth/login apesar de credenciais válidas.

## Causa Raiz
Conexão Redis obsoleta no armazenamento de sessão. JWT gerado corretamente, mas a sessão não pôde ser persistida.

## Arquivos Modificados
- auth.controller.ts: Sem alterações (somente leitura)
- middleware/cors.ts: Sem alterações (examinado)
- config/redis.ts: Corrigida configuração de pooling de conexão
- services/session.service.ts: Adicionada lógica de retry para falhas transitórias
- tests/auth.test.ts: Configuração de mock atualizada

## Status do Teste
14 passando, 2 falhando (problemas de configuração de mock)

## Próximos Passos
1. Corrigir falhas de teste restantes (mock do service de sessão)
2. Executar suíte de teste completa
3. Implantar em staging

Exemplo 2: Qualidade da Resposta da Sonda

Após a compressão, perguntando "Qual foi o erro original?":

Resposta boa (sumarização estruturada):

"O erro original foi uma resposta 401 Unauthorized do endpoint /api/auth/login. Os usuários receberam este erro com credenciais válidas. A causa raiz foi uma conexão Redis obsoleta no armazenamento de sessão."

Resposta ruim (compressão agressiva):

"Estávamos depurando um problema de autenticação. O login estava falhando. Corrigimos alguns problemas de configuração."

A resposta estruturada preserva endpoint, código de erro e causa raiz. A resposta agressiva perde todos os detalhes técnicos.

Diretrizes

1. Otimize para tokens por tarefa, não tokens por requisição
2. Use sumários estruturados com seções explícitas para rastreamento de arquivos
3. Acione a compressão em 70-80% de utilização do contexto
4. Implemente mesclagem incremental em vez de regeneração completa
5. Teste a qualidade da compressão com avaliação baseada em sonda
6. Rastreie o rastro de artefatos separadamente se o rastreamento de arquivos for crítico
7. Aceite taxas de compressão ligeiramente menores para melhor retenção de qualidade
8. Monitore a frequência de re-busca como um sinal de qualidade da compressão

Armadilhas

1. Nunca comprima definições de ferramentas ou esquemas: Comprimir esquemas de chamada de função, especificações de API ou definições de ferramentas destrói completamente a funcionalidade do agente. O agente não pode invocar ferramentas com esquemas corrompidos. Mantenha estes sempre no contexto completo.

2. Evite ciclos de regeneração profunda: Múltiplas regenerações completas de sumários (3+) levam à perda cumulativa de detalhes. Após a terceira regeneração, a sessão pode perder metade dos artefatos originalmente rastreados. A mesclagem incremental evita isso.

3. Cuidado com a falsa completude: Sumários estruturados parecem abrangentes mesmo quando faltam detalhes importantes. Sempre teste com perguntas de sonda direcionadas a artefatos e decisões, mesmo quando a estrutura parece completa.

4. Não comprima se o agente estiver prestes a concluir: Se a sessão estiver a 2-3 mensagens da conclusão natural (por exemplo, "implante isso"), a compressão adiciona latência e risco sem benefício. Use gatilhos de compressão conscientes da proximidade da conclusão.

5. Evite seções de sumário de forma livre para domínios complexos: Seções como "Detalhes Técnicos" ou "Atualizações Diversas" são menos eficazes do que seções específicas como "Mensagens de Erro", "Nomes de Função Modificados" ou "Dependências Alteradas". Seções vagas incentivam o sumarizador a pular detalhes importantes em favor de generalizações mais seguras.