Context Engineering: A Habilidade que Substituiu Prompt Engineering

Contexto é o novo código

Prompt engineering morreu. Não no sentido de "jornais declararam morto", mas do mesmo jeito que assembly morreu. Você ainda pode escrever. A maioria dos profissionais seguiu em frente para algo de nível mais alto. Esse algo é context engineering: a disciplina de estruturar, selecionar e sequenciar informação para que agentes de AI produzam resultados confiáveis em sistemas de produção.

Na product.engineer, nós definimos context engineering como a prática de projetar o ambiente completo de informação dentro do qual um modelo de AI opera, incluindo instruções de sistema, documentos recuperados, definições de ferramentas, histórico de conversação e metadados estruturados. Ele determina não apenas o que o modelo sabe, mas como ele raciocina, o que prioriza e para onde direciona sua atenção. Se prompt engineering era sobre escrever uma pergunta esperta, context engineering é sobre construir a sala inteira onde o modelo pensa.

Essa distinção importa profundamente para o product engineer. Quando você tem responsabilidade pelo ciclo completo, da definição do problema até a feature lançada, você precisa de AI que funcione de forma confiável em escala de produção. Não AI que funciona de forma impressionante numa demo e depois desmorona em edge cases. Essa confiabilidade vem do contexto, não dos prompts.

A mudança ficou visível em 2025. Na AI Engineer World's Fair, o time de engenharia da Shopify apresentou seu framework interno para o que chamaram de "agent design context-first." A palestra já acumulou mais de 73.000 visualizações. O argumento central: a qualidade do output de um agent é 90% determinada pelo contexto que ele recebe e 10% determinada pela capacidade bruta do modelo. Eles mostraram dados de produção de suas ferramentas de AI voltadas para lojistas. Quando melhoraram prompts sem mudar a arquitetura de contexto, a precisão foi de 71% para 74%. Quando reestruturaram o contexto sem mudar o prompt, a precisão saltou de 71% para 93%.

Essa diferença de 22 pontos é o caso inteiro para context engineering em um único dado.

Por que prompt engineering bateu no teto

Prompt engineering funcionava quando o caso de uso era simples: humano digita uma pergunta, modelo retorna uma resposta. Você podia iterar na formulação, adicionar exemplos few-shot, especificar formato de output é obter resultados significativamente melhores. Era uma disciplina válida para uma era específica.

Essa era acabou quando comecamos a construir agents.

Um agent não é um único par prompt-resposta. E um sistema que toma ações ao longo do tempo, mantém estado entre interações, chama ferramentas, le documentos e toma decisões com consequências. Quando sua feature de AI reserva um restaurante, modifica um banco de dados ou faz commit de código, o risco de uma resposta errada vai de "levemente irritante" para "incidente de produção."

O problema com prompt engineering para agents e estrutural. Um prompt é uma única string. O contexto de um agent é um sistema dinâmico, multi-fonte, que muda a cada turno. Considere o que um coding agent como Cursor ou Windsurf precisa para funcionar corretamente:

• A instrução atual do usuário
• O arquivo atualmente aberto
• Arquivos relacionados no projeto
• As convenções de código do projeto (do CLAUDE.md ou similar)
• Histórico recente do git para contexto de mudanças
• Definicoes de ferramentas para operações de arquivo, comandos de terminal, busca na web
• Histórico de conversação (comprimido ou completo)
• Mensagens de erro de tentativas anteriores
• Resultados de testes da última execução

São nove fontes de informação diferentes, cada uma com frequencias de atualização diferentes, janelas de relevância diferentes e níveis de prioridade diferentes. "Escrever um prompt melhor" aborda exatamente uma dessas nove dimensões. Context engineering aborda todas elas simultaneamente.

Pesquisas do time de avaliações da Anthropic, publicadas no model card do Claude 3.5 Sonnet, mostraram que contexto estruturado (system prompts com secoes explícitas, descrições de ferramentas com exemplos e documentos recuperados com scores de relevância) melhorou taxas de conclusão de tarefas em 34% comparado a contexto não estruturado com o mesmo conteúdo informacional. Mesma informação. Estrutura diferente. 34% de melhoria.

Isso não é um truque de prompting. Isso é arquitetura.

A anatomia de um sistema de contexto

Um contexto bem engenheirado tem cinco camadas. Cada camada serve uma função diferente, é o product engineer que entende todas as cinco lança features de AI que realmente funcionam em produção.

Camada 1: Identidade e restrições

Esse é o system prompt, mas pensar nele como "um system prompt" subestima o que ele faz. Ele estabelece os parametros operacionais do modelo: quem ele e, o que pode e não pode fazer, como deve lidar com ambiguidade é como devem ser seus modos de falha.

As features de AI da Linear usam camadas de identidade que especificam não apenas tom ("conciso, técnico") mas limites de decisão ("se o pedido do usuário afetaria mais de 50 issues, confirme antes de prosseguir"). O assistente de docs da Stripe tem camadas de restrição que o impedem de gerar chamadas de API com combinações invalidas de parametros, mesmo se o usuário solicitar explicitamente.

A camada de identidade responde: quais são os limites do mundo desse agent?

Camada 2: Conhecimento (recuperado e injetado)

É aqui que o RAG (retrieval-augmented generation) vive, mas é mais amplo que RAG. Contexto de conhecimento inclui:

• Documentos recuperados por busca semantica
• Dados estruturados extraidos de bancos de dados
• Informação em tempo real de chamadas de API
• Dados específicos do usuário (preferências, histórico, permissões)

O desafio de engenharia aqui não é a recuperação. E a seleção e compressao. Um modelo com 128K de contexto pode armazenar muita informação. Mas pesquisas do Google DeepMind (publicadas no paper "Lost in the Middle", 2023) demonstraram que informação posicionada no meio de contextos longos e lembrada com 20-30% menos precisão do que informação no início ou no fim. Posição importa. Ordem importa. Context engineering significa decidir não apenas o que incluir, mas onde posicionar.

Camada 3: Ferramentas e capacidades

Definicoes de ferramentas são contexto. Quando você descreve os parametros de uma função, seu comportamento esperado, seus modos de falha e seus efeitos colaterais, você está engenheirando o entendimento do modelo sobre o que ele pode fazer. Descrições ruins de ferramentas produzem modelos que chamam a ferramenta errada, passam parametros errados ou falham em usar ferramentas disponíveis.

O produto v0 da Vercel demonstra isso bem. Suas definições de ferramentas incluem não apenas a assinatura da função, mas exemplos explícitos de quando usar cada ferramenta, erros comuns a evitar é o formato de output esperado. Isso é harness engineering na prática: construir a infraestrutura que torna o comportamento do agent previsível.

Camada 4: Memória e estado de conversação

O que aconteceu antes deste turno? O que o usuário disse três mensagens atrás? O que o agent tentou que falhou? Gerenciamento de memória é um problema de context engineering porque modelos tem janelas finitas e conversas reais tem comprimento potencial infinito.

A abordagem ingenua e incluir o histórico completo de conversação até bater no limite de contexto, e então truncar do início. A abordagem engenheirada e manter um resumo comprimido de interações anteriores, preservar pontos de decisão críticos na integra e descartar turnos de baixa informação inteiramente.

As features de AI da Notion implementam o que chamam de "sumarizacao progressiva" para contexto. Mensagens recentes são incluidas na integra. Mensagens de 10+ turnos atrás são sumarizadas em fatos-chave. Mensagens de 50+ turnos atrás são reduzidas apenas a relações entre entidades (usuário prefere X, projeto requer Y). Isso mantém a janela de contexto eficiente enquanto preserva a informação que o modelo realmente precisa.

Camada 5: Scaffolding de output

A camada final diz ao modelo como estruturar seu output. Isso não é "responda em JSON." E fornecer o formato da resposta esperada, incluindo passos intermediários de raciocínio, validações obrigatórias antes do output final e restrições de formato das quais sistemas downstream dependem.

Quando as features de AI da Figma geram sugestões de design, o scaffolding de output inclui metadados obrigatórios (tipo de componente, compatibilidade de variante, notas de acessibilidade) que o sistema de renderizacao precisa. O modelo não decide quais metadados incluir. O context engineering define isso.

O framework de context engineering

Depois de trabalhar com sistemas de AI em escala, tanto na AWS quanto nas minhas próprias empresas, convergi para um framework de context engineering que ensino aos engenheiros que faco mentoria. Eu chamo de PRISM: Priority, Relevance, Instruction, Structure, Measurement.

Priority determina qual informação vai onde na janela de contexto. Restrições críticas vão primeiro (system prompt). Definicoes de ferramentas vão perto da query do usuário. Documentos recuperados vão entre os dois, ordenados por score de relevância.

Relevance é o filtro que decide o que entra no contexto. Nem tudo que o modelo poderia saber deveria estar no contexto. Um coding agent trabalhando num componente React não precisa do schema do banco de dados do projeto, a menos que o componente faca fetch de dados. Filtragem de relevância é a diferença entre um contexto focado de 4K tokens é um contexto ruidoso de 90K tokens. O contexto focado ganha quase sempre.

Instruction é a camada de restrições. Regras explícitas que o modelo deve seguir, formuladas como imperativos. Não "você pode querer considerar" mas "você deve validar inputs antes de chamar APIs externas." Pesquisas da própria Anthropic mostraram que formulação imperativa em system prompts aumentou a aderência a instruções em 18% comparado a formulação sugestiva.

Structure significa usar formatacao consistente. Headers, bullet points, tags XML, schemas JSON. Modelos processam texto estruturado de forma mais confiável do que prosa. A Anthropic recomenda tags XML para delimitacao de secoes. A documentação da OpenAI recomenda headers em markdown. Ambos funcionam. Consistência é o que importa.

Measurement é o ciclo de feedback. Você instrumenta seu contexto para entender o que o modelo realmente usa. Se você inclui 50 documentos recuperados é o modelo referência apenas 3, sua filtragem de relevância precisa de trabalho. Se o modelo viola uma restrição, sua camada de instrução precisa ser fortalecida.

Context engineering no workflow do product engineer

Isso não é um exercício academico. Para qualquer pessoa construindo features de AI, context engineering e trabalho diário. Ele aparece em três lugares.

Projetando features de agents

Quando você específica uma feature de AI (seguindo spec-driven development), a arquitetura de contexto faz parte da spec. Você define quais fontes de informação o agent precisa, como elas são recuperadas e qual prioridade recebem. Isso é tão parte do design da feature quanto o mockup de UI.

Na AWS, já vi times perderem meses porque projetaram a UX de uma feature de AI sem projetar o contexto. Construiram uma interface de chat linda. As respostas eram terriveis porque ninguém engenheirou o que o modelo realmente recebia. A correção era sempre a mesma: voltar, projetar o sistema de contexto, lançar de novo.

Configurando ferramentas de desenvolvimento

Todo engenheiro usando Cursor, Claude Code, Windsurf ou GitHub Copilot está fazendo context engineering, percebendo ou não. Seu arquivo CLAUDE.md e context engineering. Seu arquivo .cursorrules e context engineering. A forma como você estrutura sua codebase para que um AI consiga navegar nela e context engineering.

Isso conecta diretamente com agentic engineering. Os engenheiros que conseguem ganhos de 10x de produtividade com ferramentas de AI não estão escrevendo prompts melhores. Estão engenheirando contexto melhor: estruturas de arquivos mais claras, convenções de nomenclatura melhores, documentação explícita de decisões e restrições.

Construindo sistemas de AI para produção

Quando você lança uma feature de AI para usuários, o sistema de contexto e infraestrutura de produção. Precisa de monitoramento, versionamento, testes A/B e resposta a incidentes, assim como qualquer outro sistema de produção.

O PostHog trata seus contextos de features de AI como código. Eles versionam no git, revisam em PRs e medem o impacto com o mesmo rigor que aplicam a qualquer mudança de produto. Quando uma mudança de contexto produz uma regressão na qualidade do output, eles revertem como reverteriam um deploy ruim.

O toolkit de context engineering do product engineer

Aqui está como o toolkit se parece na prática:

Padrões do mundo real em produção

Vou compartilhar três padrões que vi funcionar repetidamente em diversos times.

Padrão 1: O contrato de contexto. Antes de construir uma feature de AI, escreva um documento que especifica exatamente o que o modelo recebe em cada cenário. Trate como um contrato de API. Quando o produto muda, atualize o contrato de contexto primeiro, depois atualize a implementação. Isso previne divergencia entre o que você acha que o modelo vê é o que ele realmente vê.

Padrão 2: O orçamento de contexto. Atribua orçamentos de tokens para cada camada. Exemplo: 2.000 tokens para system prompt, 4.000 para ferramentas, 8.000 para documentos recuperados, 2.000 para histórico de conversação. Quando nova informação precisa entrar, algo precisa sair. Isso força decisões de priorização e previne inchacho de contexto.

Padrão 3: O teste de regressão de contexto. Mantenha um suite de cenários de entrada com outputs esperados. Quando você muda a arquitetura de contexto, rode o suite. Isso não é um eval no sentido de ML; é um teste funcional que garante que suas mudanças de contexto não quebrem comportamento existente. A Stripe roda mais de 2.000 testes de regressão de contexto em suas features de AI antes de qualquer deploy.

Da minha própria experiência

Tendo feito mentoria para mais de 12.000 engenheiros e contratado mais de 600, posso te dizer o padrão que vejo repetidamente: os engenheiros que lutam com features de AI focam no modelo. Os engenheiros que lançam features de AI confiáveis focam no contexto. Isso é verdade tanto se estão construindo ferramentas internas na AWS quanto produtos para consumidor em uma startup.

No meu próprio trabalho como Sr. Product Engineer na AWS, a mudança foi dramática. Features de AI iniciais nas quais trabalhei gastavam 80% do tempo de desenvolvimento em iteração de prompts. Testavamos centenas de variacoes de prompt, encontravamos uma que funcionava bem nos nossos casos de teste, faziam deploy, e então assistiamos falhar em inputs do mundo real que não tinhamos antecipado. O problema nunca era o modelo. Era sempre o contexto: informação faltando, instruções mal estruturadas ou definições de ferramentas que não consideravam edge cases.

Quando mudamos para desenvolvimento context-first, nossos ciclos de iteração caíram de semanas para dias. Gastamos menos tempo ajustando linguagem é mais tempo engenheirando qual informação o modelo recebia, como ela era estruturada e quando era atualizada. As melhorias de qualidade eram consistentes e previsíveis de uma forma que ajuste de prompts nunca foi.

A mudança na contratação

Isso tem implicações para como empresas contratam product engineers. Prompt engineering nunca foi uma disciplina real de engenharia. Era uma habilidade, como "escrever boas buscas no Google." Útil, mas não suficiente para construir sistemas de produção.

Context engineering e diferente. Requer pensamento sistemico, arquitetura de informação, metodologia de testes e habilidades de engenharia de produção. E por isso que empresas como Vercel, Linear e Notion cada vez mais procuram engenheiros que entendem tanto produto quanto sistemas de AI; que conseguem projetar uma arquitetura de contexto com o mesmo rigor que trazem para um schema de banco de dados ou um design de API.

Se você é um product engineer procurando construir features de AI, invista em context engineering. Não em templates de prompt. Não em "prompts magicos" de threads do Twitter. Nos fundamentos: como modelos processam contexto, como prioridade de informação afeta qualidade de output, como testar e medir eficácia de contexto.

Erros comuns

Cinco erros que vejo times cometendo repetidamente:

1. Enfiar tudo dentro. Mais contexto não é melhor contexto. Um contexto de 100K tokens com 80K tokens de documentos marginalmente relevantes performa pior do que um contexto de 20K tokens com informação precisamente relevante. Modelos ficam confusos com ruido.

2. Ignorar efeitos de posição. Instruções críticas enterradas no meio de um contexto longo são seguidas com menos frequência. Coloque suas restrições mais importantes no início e no final.

3. Contexto estático para tarefas dinâmicas. Se seu agent lida com diferentes tipos de requests, o contexto deveria se adaptar. Um agent de suporte ao cliente respondendo perguntas de cobrança precisa de contexto diferente do mesmo agent respondendo perguntas técnicas. Contexto one-size-fits-all produz resultados mediocres para todos os casos.

4. Sem medição. Se você não instrumenta o que o modelo realmente presta atenção e usa, você está adivinhando. Adicione logging que rastreia quais documentos recuperados são referenciados nos outputs, quais ferramentas são chamadas e quais instruções são seguidas.

5. Tratar contexto como um prompt. Contexto e infraestrutura. Precisa de versionamento, testes, monitoramento, capacidade de rollback e propriedade. Se seu contexto vive numa string literal dentro de uma função e ninguém revisa mudanças nela, você vai ter incidentes de produção.

Principais conclusões

• Context engineering estrutura todo o ambiente de informação no qual uma AI opera, não apenas o texto do prompt.
• Reestruturar o contexto sem mudar prompts elevou a precisão de 71% para 93% nas ferramentas de AI em produção da Shopify.
• Um contexto bem-engenheirado tem cinco camadas: identidade, conhecimento, ferramentas, memoria e scaffolding de output.
• Trate contexto como infraestrutura de produção que precisa de versionamento, testes, monitoramento e capacidade de rollback.
• Os engenheiros que lançam features de AI confiáveis focam em arquitetura de contexto, não em iteração de prompt.

FAQ

Qual a diferença entre context engineering e prompt engineering?

Prompt engineering foca em elaborar o texto de uma única query para obter respostas melhores de um modelo. Context engineering é mais amplo: abrange todo o ambiente de informação dentro do qual o modelo opera, incluindo instruções de sistema, definições de ferramentas, documentos recuperados, histórico de conversação e estrutura de output. Prompt engineering é um input. Context engineering é o sistema inteiro.

Preciso saber context engineering se não estou construindo produtos de AI?

Sim, se você usa ferramentas de desenvolvimento com AI. Todo engenheiro usando Cursor, Claude Code, GitHub Copilot ou ferramentas similares se beneficia de context engineering. Como você estrutura sua codebase, escreve documentação e configura settings de ferramentas afeta diretamente a qualidade da assistência de AI que você recebe. Os engenheiros conseguindo ganhos de 10x em produtividade engenheiraram seu contexto, não apenas seus prompts.

Como meco se meu context engineering esta funcionando?

Três métricas importam: taxa de conclusão de tarefas (o agent termina o que começa?), aderência a instruções (ele segue as restrições que você definiu?) e utilização de relevância (ele usa a informação que você fornece?). Rastreie essas métricas entre mudanças de contexto para entender quais melhorias realmente movem o ponteiro.

Quais ferramentas devo usar para context engineering?

As ferramentas são menos importantes que a prática. Dito isso, controle de versão (git) para definições de contexto, frameworks de avaliação (como as ferramentas de eval da Anthropic ou da OpenAI) para medir qualidade, e plataformas de observabilidade (como LangSmith ou Helicone) para monitoramento em produção formam uma base sólida. A chave e tratar contexto como código que é revisado, testado e monitorado.

Context engineering só e relevante para sistemas baseados em LLM?

Os princípios se aplicam em qualquer lugar onde um sistema de AI precise de input estruturado para produzir output confiável. Mas as técnicas específicas (orçamento de tokens, otimização de posição, sumarizacao progressiva) são mais diretamente aplicáveis a modelos de linguagem baseados em transformer com janelas de contexto finitas. Conforme as janelas de contexto crescem é as arquiteturas evoluem, os detalhes vão mudar. A disciplina de projetar ambientes de informação não vai.

O futuro tem formato de contexto

Prompt engineering era um jogo single-player. Escreva um prompt melhor, obtenha uma resposta melhor. Context engineering é um esporte coletivo. Ele toca design de produto (qual informação o usuário precisa fornecer?), engenharia de backend (como recuperamos e estruturamos conhecimento?), engenharia de dados (como mantemos o contexto atualizado?) e engenharia de frontend (como apresentamos interações multi-step de agents?).

É por isso que o product engineer e unicamente adequado para ser dono disso. Não o ML engineer que otimiza modelos. Não o data scientist que constrói evals. A pessoa que entende o sistema completo, da intenção do usuário até a feature lançada, é que pode tomar as decisões arquiteturais que determinam se uma feature de AI funciona em produção ou desmorona no primeiro edge case.

Contexto é o novo código. Engenheiro ele de acordo.

Leitura relacionada

• What Is a Product Engineer? The Definitive Guide
• Harness Engineering: Building Infrastructure for AI Agents
• Agentic Engineering: How Product Engineers Build with AI
• Spec-Driven Development for Product Engineers
• Don't Build Agents, Build Skills