Engenharia de Contexto
A engenharia de contexto seleciona o menor conjunto de tokens de alto sinal para tarefas de LLM. O objetivo: maximizar a qualidade do raciocínio enquanto minimiza o uso de tokens.
Quando Ativar
- Projetando/depurando sistemas de agentes
- Limites de contexto restringindo o desempenho
- Otimizando custo/latência
- Construindo coordenação multiagente
- Implementando sistemas de memória
- Avaliando desempenho de agentes
- Desenvolvendo pipelines baseados em LLM
Princípios Fundamentais
- Qualidade do contexto > quantidade - Tokens de alto sinal vencem conteúdo exaustivo
- A atenção é finita - Curva em forma de U favorece posições de início/fim
- Revelação progressiva - Carregue informações no momento certo
- Isolamento previne degradação - Particione o trabalho entre subagentes
- Meça antes de otimizar - Conheça sua linha de base
IMPORTANTE:
- Sacrifique a gramática em prol da concisão.
- Garanta eficiência de tokens mantendo alta qualidade.
- Passe essas regras para subagentes.
Referência Rápida
| Tópico | Quando Usar | Referência |
|---|---|---|
| Fundamentos | Entender anatomia do contexto, mecânica da atenção | context-fundamentals.md |
| Degradação | Depurar falhas, perdido-no-meio, envenenamento | context-degradation.md |
| Otimização | Compactação, mascaramento, cache, particionamento | context-optimization.md |
| Compressão | Sessões longas, estratégias de sumarização | context-compression.md |
| Memória | Persistência entre sessões, grafos de conhecimento | memory-systems.md |
| Multiagente | Padrões de coordenação, isolamento de contexto | multi-agent-patterns.md |
| Avaliação | Testar agentes, LLM-como-Juiz, métricas | evaluation.md |
| Design de Ferramentas | Consolidação de ferramentas, engenharia de descrição | tool-design.md |
| Pipelines | Desenvolvimento de projetos, processamento em lote | project-development.md |
| Consciência de Runtime | Limites de uso, monitoramento da janela de contexto | runtime-awareness.md |
Métricas Principais
- Utilização de tokens: Aviso em 70%, gatilho de otimização em 80%
- Variância de tokens: Explica 80% da variância de desempenho do agente
- Custo multiagente: ~15x a linha de base de agente único
- Alvo de compactação: Redução de 50-70%, perda de qualidade <5%
- Alvo de cache hit: 70%+ para cargas de trabalho estáveis
Estratégia de Quatro Baldes
- Escrever: Salvar contexto externamente (scratchpads, arquivos)
- Selecionar: Puxar apenas contexto relevante (recuperação, filtragem)
- Comprimir: Reduzir tokens preservando informações (sumarização)
- Isolar: Dividir entre subagentes (particionamento)
Antipadrões
- Contexto exaustivo sobre contexto curado
- Informação crítica em posições intermediárias
- Nenhum gatilho de compactação antes dos limites
- Agente único para tarefas paralelizáveis
- Ferramentas sem descrições claras
Diretrizes
- Coloque informações críticas no início/fim do contexto
- Implemente compactação em 70-80% de utilização
- Use subagentes para isolamento de contexto, não role-play
- Projete ferramentas com estrutura de 4 perguntas (o quê, quando, entradas, retornos)
- Otimize por tokens-por-tarefa, não tokens-por-requisição
- Valide com avaliação baseada em probe
- Monitore as taxas de cache KV em produção
- Comece mínimo, adicione complexidade apenas quando comprovadamente necessário
Consciência de Runtime
O sistema injeta automaticamente consciência de uso via hook PostToolUse:
<usage-awareness>
Claude Usage Limits: 5h=45%, 7d=32%
Context Window Usage: 67%
</usage-awareness>
Limiares:
- 70%: AVISO - considere otimização/compactação
- 90%: CRÍTICO - ação imediata necessária
Fontes de Dados:
- Limites de uso: API OAuth Anthropic (
https://api.anthropic.com/api/oauth/usage) - Janela de contexto: Arquivo temporário Statusline (
/tmp/ck-context-{session_id}.json)
Scripts
- context_analyzer.py - Análise de saúde do contexto, detecção de degradação
- compression_evaluator.py - Avaliação de qualidade de compressão