Context engineering: a skill nº1 do AI engineer em 2026

Abre uma vaga sênior de AI engineer hoje, em 2026. Procura "prompt engineer" no texto.

Não acha.

O que vai aparecer no lugar é uma frase parecida com isso: "experiência desenhando pipelines de contexto para agentes em produção". Em alguns lugares vem com o nome explícito — context engineering. Em outros vem disfarçado de "RAG avançado", "context window optimization", "agentic memory design". É tudo a mesma coisa. E é a skill que decide quem passa do screening técnico em 2026.

A Anthropic chamou esse movimento pelo nome em Effective context engineering for AI agents: "the set of strategies for curating and maintaining the optimal set of tokens (information) during LLM inference". Prompt engineering não morreu. Virou subdisciplina. O que cresceu por cima foi a engenharia de o que entra na janela de contexto, em que ordem, com qual densidade, e quanto custa cada token gasto sem retorno.

Esse post é a régua técnica. Os 5 pilares do context engineering, uma stack rodando em Laravel com pgvector e bge-reranker, e a métrica nova que recrutador olha quando você fala que "fez RAG": o context utilization ratio.

TL;DR

O que é: disciplina de desenhar o que o modelo vê em cada inferência — retrieval, compaction, estrutura, recency e budget de tokens.
Stack: PHP 8.3, Laravel 11, Postgres 16 + pgvector, bge-reranker-v2-m3, Claude Sonnet 4.6 via API.
Custo/Acesso: Postgres self-hosted, reranker open-source roda em CPU, Claude pay-as-you-go.
Fonte de cabeceira: Context engineering cookbook da Anthropic.

O contexto — por que prompt virou subdisciplina

O LLM tem um orçamento de atenção finito. A Anthropic chama o efeito de context rot: quanto mais tokens você empilha, pior a fidelidade do modelo nas decisões. Não é teoria. É observação direta da equipe que treina o Claude.

Prompt engineering responde a pergunta "como escrevo isso?". Context engineering responde "o que precisa estar na janela agora?". A Elastic Search Labs coloca dessa forma: o prompt é a fala do ator, o contexto é o palco inteiro. Sem palco, qualquer fala soa fora de lugar.

O motivo de a vaga ter mudado é simples. Em 2023 a aplicação era um chat single-turn. Em 2026 é um agente que abre tickets, lê PDFs, consulta API, mantém memória de sessão e devolve um plano executável. A Gartner projeta que 40% das aplicações enterprise vão usar agentes específicos até o fim de 2026. Cada um desses agentes vive ou morre pelo desenho do contexto que recebe a cada passo.

E aqui está a parte que assusta o dev acomodado: prompt bonito não salva contexto mal desenhado. A Anthropic é direta no blog oficial — o princípio é "find the smallest set of high-signal tokens that maximize the likelihood of your desired outcome". Tudo que não maximiza, custa. Custa latência, custa dinheiro, custa qualidade.

Os 5 pilares do context engineering

Não é framework de PowerPoint. É como o sênior pensa quando senta para desenhar o pipeline.

1. Retrieval quality

A qualidade do que entra na janela é mais importante do que a quantidade. Embedding ruim recupera doc errado. Doc errado polui contexto. Modelo alucina ou contradiz. Erro caro, difícil de auditar.

A combinação que ganhou força em 2026 é busca híbrida com reranking: vector search recupera 50 candidatos, full-text recupera outros 50, união passa por um reranker cross-encoder que devolve os 5 ou 10 mais relevantes. O bge-reranker-v2-m3 da BAAI virou padrão de mercado porque é open-source, suporta português decente e roda em CPU sem GPU dedicada.

2. Context compaction

Histórico cresce. Sempre. A Anthropic lançou no Developer Platform o tipo compact_20260112, que dispara um resumo automático quando a janela passa de um limite (default 150K tokens, mínimo 50K). O cookbook deles tem um caso documentado de um agente de pesquisa lendo 8 PDFs (~320K tokens) que cai de 335K para 169K de pico só ligando compaction — e ainda consegue completar 7 turnos em vez de 5.

A armadilha: compaction preserva fatos de alto nível e perde specifics obscuros. O probe deles é direto — 3/3 fatos preservados, 0/3 detalhes específicos. Quem desenha o agente decide o que é alto nível.

3. Structure

LLM lê estrutura. Bloco solto vira ruído. Sênior estrutura o contexto em camadas: system prompt curto e prescritivo, depois <summary> do histórico, depois <retrieved_docs> com os chunks rerankeados, depois a query do usuário. Tags XML não são frescura — são âncoras de atenção. O Claude foi treinado prestando atenção nelas.

4. Recency

Just-in-time retrieval substituiu o "joga tudo na janela e reza". A Anthropic chama o padrão de lightweight identifiers: o agente carrega referências (file paths, IDs, stored queries) e busca o conteúdo só quando precisa, via tool call. Espelha cognição humana — você não decora a Wikipedia inteira, você sabe onde procurar.

5. Token budget

Tudo isso vira número. Quantos tokens cabem no system prompt? Quantos no retrieved? Quantos sobram para o output? Sênior chega na reunião com planilha. Júnior chega achando que "o contexto do Claude é 1M, dá pra colocar tudo".

A métrica nova que recrutador olha — context utilization ratio

Em entrevista técnica de AI engineer em 2026, a pergunta caiu nesse formato: "qual é o context utilization ratio do seu pipeline em produção?". Quem trava aí, perde a vaga.

É uma métrica simples. Razão entre tokens de alto sinal que o modelo de fato usou e tokens totais que entraram na janela. Tokens de alto sinal são os que aparecem citados, parafraseados ou usados como base de decisão na resposta. Os outros são ruído pago.

Como medir na prática — três passos:

Logue todo input e output do modelo no agente.
Use um modelo barato (Haiku 4.5 ou similar) como juiz, com prompt do tipo "liste os trechos do input que foram realmente usados na resposta".
Some os tokens dos trechos citados, divida pelo total de input. Pronto, seu ratio.

Time bom mira 0.4 ou mais. Time descuidado roda em 0.1 e queima cinco vezes mais dinheiro pelo mesmo resultado. O cookbook da Anthropic mostra que a combinação de compaction + tool clearing pode levar um pipeline de 335K de pico para 120K, completando o dobro de turnos. Isso é context utilization ratio melhorando na prática.

Pré-requisitos

[ ] PHP 8.3 + Laravel 11
[ ] Postgres 16 com extensão pgvector instalada
[ ] Conta na Anthropic com chave API (ANTHROPIC_API_KEY)
[ ] Modelo de embeddings (Voyage 3, OpenAI text-embedding-3-large ou bge-m3 local)
[ ] Container rodando bge-reranker-v2-m3 (texto pequeno, CPU dá conta)
[ ] Familiaridade com queues do Laravel (ingestão de docs é assíncrona)

Mão na massa — pipeline em Laravel

Vou montar o esqueleto do que rodaria em produção. Sem mágica, sem framework gigante por cima.

Passo 1: schema pgvector e ingestão

Migration cria a tabela de chunks com coluna vetorial e índice ivfflat. Cada doc é quebrado em chunks de ~400 tokens com overlap de 50.

// database/migrations/2026_05_30_create_chunks_table.php
public function up(): void
{
    DB::statement('CREATE EXTENSION IF NOT EXISTS vector');

    Schema::create('chunks', function (Blueprint $table) {
        $table->id();
        $table->foreignId('document_id')->constrained();
        $table->text('content');
        $table->jsonb('metadata');
        $table->timestamps();
    });

    DB::statement('ALTER TABLE chunks ADD COLUMN embedding vector(1024)');
    DB::statement('CREATE INDEX chunks_embedding_idx ON chunks USING ivfflat (embedding vector_cosine_ops) WITH (lists = 100)');
    DB::statement('CREATE INDEX chunks_content_fts ON chunks USING gin(to_tsvector(\'portuguese\', content))');
}

A ingestão roda numa Job. Chunking, embed, insert. Sem ciência espacial — só atenção a chunk overlap para não cortar frases no meio.

Passo 2: retrieval híbrido com rerank

A função recebe a query, faz busca vetorial e full-text em paralelo, une candidatos, passa pelo reranker e devolve top N.

// app/Services/Retrieval/HybridRetriever.php
public function retrieve(string $query, int $topK = 5): Collection
{
    $embedding = $this->embedder->embed($query);

    $vectorHits = DB::table('chunks')
        ->selectRaw('id, content, metadata, embedding <=> ? AS distance', [$embedding])
        ->orderBy('distance')
        ->limit(50)
        ->get();

    $textHits = DB::table('chunks')
        ->selectRaw("id, content, metadata, ts_rank(to_tsvector('portuguese', content), plainto_tsquery('portuguese', ?)) AS rank", [$query])
        ->whereRaw("to_tsvector('portuguese', content) @@ plainto_tsquery('portuguese', ?)", [$query])
        ->orderByDesc('rank')
        ->limit(50)
        ->get();

    $candidates = $vectorHits->concat($textHits)->unique('id')->values();

    return $this->reranker->rerank($query, $candidates, $topK);
}

O Reranker é um wrapper HTTP para o container do bge-reranker. Recebe (query, lista de docs), devolve scores, ordena, fatia top K. Cinco linhas de cliente Guzzle, nada a ver com a complicação que parece.

Passo 3: montagem do contexto com estrutura

O ponto que separa pipeline amador de profissional. Tudo entra em camadas explícitas, com tags.

// app/Services/Context/ContextBuilder.php
public function build(string $userQuery, ?string $sessionSummary, Collection $chunks): string
{
    $docs = $chunks->map(fn($c) =>
        "<doc id=\"{$c->id}\" source=\"{$c->metadata['source']}\">\n{$c->content}\n</doc>"
    )->implode("\n");

    $summaryBlock = $sessionSummary
        ? "<conversation_summary>\n{$sessionSummary}\n</conversation_summary>\n"
        : '';

    return <<<CTX
{$summaryBlock}
<retrieved_docs>
{$docs}
</retrieved_docs>

<user_query>
{$userQuery}
</user_query>
CTX;
}

A ordem importa. Resumo primeiro porque o modelo lê para baixo e a query final fica fresca na atenção. Tags XML porque o Claude foi otimizado para ancorar atenção nelas — não é folclore, está nas docs oficiais.

Passo 4: chamada com compaction ligada

Na chamada da API, configura context management. A partir de 150K tokens de input, o Claude resume sozinho o histórico anterior.

// app/Services/Agents/ContextAwareAgent.php
$response = $this->claude->messages()->create([
    'model' => 'claude-sonnet-4-6',
    'max_tokens' => 2048,
    'system' => $this->systemPrompt,
    'messages' => $messages,
    'context_management' => [
        'edits' => [[
            'type' => 'compact_20260112',
            'trigger' => ['type' => 'input_tokens', 'value' => 150_000],
            'instructions' => 'Resuma preservando decisões arquiteturais, IDs de docs já consultados e threads não resolvidos.',
        ], [
            'type' => 'clear_tool_uses_20250919',
            'trigger' => ['type' => 'input_tokens', 'value' => 30_000],
            'keep' => ['type' => 'tool_uses', 'value' => 4],
        ]],
    ],
]);

A instrução do compaction não é genérica. Ela diz o que preservar — porque, lembrando, compaction sacrifica specifics obscuros. Quem desenha o agente é quem decide o que é alto nível para aquele domínio.

Limitações e pontos de atenção

Onde o pipeline quebra na prática:

Compaction perde detalhe. Se o agente precisa lembrar de um número específico citado 40 turnos atrás, ele não vai. A solução é structured note-taking — escreve para fora da janela e relê quando precisar.
Reranker custa CPU. Cada query passa 100 candidatos por um cross-encoder. Em pico, vira gargalo. Cacheia rerank de queries comuns e mede latência p95.
Recency vs relevância. Doc mais relevante pode ser antigo, doc mais recente pode ser irrelevante. Misture com weight (0.7 relevância + 0.3 recency funciona como ponto de partida — calibre por domínio).
Não confunda mais contexto com melhor contexto. A Anthropic é literal sobre isso: o princípio é o menor conjunto de tokens de alto sinal. 1M de janela não é convite para encher.
Privacidade. Doc de cliente entra em embedding, vira vetor, fica no Postgres. Tenha política de retenção e mascare PII no chunking, não depois.

FAQ

Preciso largar prompt engineering? Não. Prompt engineering virou subset do context engineering. System prompt continua sendo um dos pilares — só não é o único.

Funciona sem pgvector? Funciona com qualquer vector DB — Qdrant, Weaviate, Pinecone, Milvus. pgvector ganha porque a maioria dos projetos Laravel já tem Postgres rodando. Menos infra, menos coisa para quebrar.

Vale a pena para chatbot simples? Não. Single-turn FAQ sobrevive bem com prompt + RAG básico. Context engineering começa a pagar quando o sistema é multi-turno, multi-tool ou tem horizonte longo.

Como meço o context utilization ratio sem montar pipeline gigante? Logue input e output por turno. Use o Haiku como juiz com prompt curto pedindo a lista de trechos citados. Conta os tokens, divide pelo total. Não precisa de Datadog para começar — uma planilha resolve.

Conclusão

Context engineering não é uma onda nova. É o nome que a indústria deu para o que separa o agente que demora seis meses para chegar em produção do que nunca chega. Os 5 pilares — retrieval, compaction, structure, recency, budget — são o vocabulário comum agora. E quem domina o jeito de medir o que entra na janela, mede direito o que está construindo.

Se você quer continuar conversando sobre isso com gente que está enfiando agente em produção todo dia, essa é exatamente a conversa que rola na Beer and Code, a melhor comunidade de AI engineering em português, com grupo no WhatsApp aberto pra quem está construindo IA em produção.

O próximo passo, para quem ainda não fez, é simples. Pega o seu agente atual. Mede o ratio. Depois liga compaction e clearing. Mede de novo. Vai ver número grande mudando — e vai entender, na pele, porque a vaga não pede mais prompt engineer.