Context engineering para agentes de código sem desperdício

Context engineering para agentes de código é a prática de controlar quais evidências, ferramentas e memórias entram no trabalho do agente. Não é colocar mais coisa no prompt. É decidir, antes do loop começar, que evidência entra, que ruído fica fora e qual verificação encerra a tarefa.

Em 2025, o Google Cloud informou no relatório DORA que a adoção de IA entre profissionais de software chegou a 90%, com mediana de duas horas diárias de uso (Google Cloud, "How are developers using AI? Inside our 2025 DORA report", 2025). O problema deixou de ser acesso à IA. O problema virou memória útil, custo, confiança e revisão.

TL;DR: principais aprendizados

• A DORA mediu 90% de adoção de IA em software, mas Stack Overflow viu 46% de desconfiança na precisão. O caminho prático é contexto menor, verificação melhor e loops com parada clara.
• Subagentes ajudam quando devolvem sínteses, não despejos de log.
• MCP deve expor ferramentas e recursos com escopo, não a empresa inteira.

Por que context engineering virou o gargalo dos agentes?

Em 2025, Stack Overflow mediu que 84% dos respondentes usam ou planejam usar ferramentas de IA no desenvolvimento, mas 46% desconfiam da precisão desses resultados (Stack Overflow, "2025 Developer Survey: AI", 2025). Context engineering virou o gargalo porque o agente precisa de evidência suficiente para agir, sem receber ruído suficiente para se perder.

O erro comum é tratar a janela de contexto como um depósito. O agente recebe README, logs longos, conversas antigas, árvore completa, issue inteira, stack trace bruto e regras duplicadas. Isso parece seguro, mas piora a revisão. A pessoa que recebe o diff não sabe qual premissa foi usada, qual arquivo importou e qual teste realmente fechou a tarefa.

Um fluxo melhor separa contexto em camadas. A camada fixa explica como o repositório trabalha. A camada recuperada traz arquivos e decisões relevantes. A camada operacional define comandos, limites e permissões. A camada de evidência registra o que foi testado. Cada camada precisa ter dono, validade e forma de expirar.

Esse assunto se conecta ao que escrevi sobre harness de agentes de código para PRs confiáveis. O harness decide se o trabalho passa. O context engineering decide se o agente recebeu material bom o bastante para chegar lá sem desperdiçar iterações.

Segundo o Stack Overflow, em 2025 apenas 3,1% dos respondentes disseram confiar muito na precisão de ferramentas de IA, enquanto 19,6% disseram desconfiar muito (Stack Overflow, "2025 Developer Survey: AI", 2025). O ponto não é abandonar agentes. É projetar o contexto para que o erro apareça cedo, com rastro verificável.

O que entra no orçamento de contexto?

Em 2025, a DORA relatou que 65% dos profissionais pesquisados dependiam bastante de IA para desenvolvimento de software, somando uso moderado, alto e muito alto (Google Cloud, "How are developers using AI? Inside our 2025 DORA report", 2025). Um orçamento de contexto transforma essa dependência em um contrato operacional: o agente recebe objetivo, restrições, evidências e critérios de parada.

Comece pelo contexto que raramente muda. Ele deve caber em um arquivo curto, como AGENTS.md, CLAUDE.md ou um documento equivalente. Inclua layout do repositório, comandos de build, padrões de PR, regras de segurança e definição de pronto. A própria documentação do Codex recomenda que AGENTS.md cubra estrutura do repo, comandos, convenções, restrições e verificação de trabalho (OpenAI Developers, "Best practices - Codex", 2026).

Depois vem o contexto recuperado. Aqui entram busca lexical, busca vetorial, grafo de dependências e histórico de decisões. Para bases grandes, RAG sobre codebase só funciona quando retorna trechos pequenos com motivo. Uma busca que entrega dez arquivos inteiros é só outra forma de poluir o prompt.

Por fim, defina o contexto operacional. Ele responde: quais ferramentas podem ser usadas, quais comandos são baratos, quais comandos exigem autorização e qual saída deve voltar para a conversa principal. Em loops longos com Claude Code ou Codex, eu uso uma regra simples: logs brutos ficam em arquivo; o agente principal recebe uma síntese com caminhos, falhas e próximo passo.

Um orçamento de contexto para agentes de código limita o que entra na conversa principal e desloca ruído para artefatos auditáveis. Essa disciplina reduz retrabalho porque o agente para de discutir logs antigos e passa a operar sobre objetivo, prova e restrição. É a diferença entre "leia tudo" e "use estes sinais para tomar esta decisão".

Como montar um loop agentic que se corrige?

Em 2025, a OpenAI descreveu o Codex como um agente que trabalha em tarefas paralelas e que normalmente leva de 1 a 30 minutos por tarefa (OpenAI, "Introducing Codex", 2025). Um loop que se corrige precisa usar essa capacidade como sistema de prova, não como licença para aceitar qualquer diff.

O loop começa com uma tarefa estreita. Ela deve dizer qual comportamento muda, onde observar o resultado e o que não pode ser alterado. Depois o agente cria um plano curto, consulta a codebase, aplica a mudança, roda verificação e registra evidência. Se falhar, ele não recomeça do zero; ele reduz a hipótese e tenta de novo.

Use evals quando a saída não cabe em um teste unitário. A OpenAI recomenda começar problemas difíceis definindo como o sucesso será medido, combinando checagens determinísticas e avaliações por rubrica quando necessário (OpenAI Developers, "Iterate on difficult problems", 2026). Para software, isso vira uma mistura de teste automatizado, análise estática, revisão semântica e inspeção do artefato final.

Um exemplo de contrato simples:

tarefa:
  objetivo: "corrigir falha de expiracao de sessao no endpoint de renovacao"
  fora_de_escopo: "nao alterar provedor de autenticacao"
contexto:
  arquivos_obrigatorios:
    - "src/auth/session.service.ts"
    - "src/auth/session.controller.ts"
  recuperar:
    - "testes que mencionam renovacao de sessao"
    - "decisoes de arquitetura sobre tokens"
verificacao:
  comandos:
    - "npm run test -- auth"
    - "npm run lint"
  parada: "diff pequeno, testes passando e explicacao do risco residual"

Na prática, esse contrato funciona melhor quando o agente é obrigado a escrever a própria hipótese antes de editar. Se a hipótese não cita arquivo, comportamento e verificação, a tarefa ainda está vaga. Isso força uma pausa barata antes da parte cara: alterar código.

Em minha experiência revisando mudanças geradas por agentes, a hipótese curta reduz discussão circular. Quando o agente escreve "vou tocar este arquivo, por este comportamento, e provar com este comando", o revisor consegue separar falha de contexto, falha de implementação e falha de teste.

Para loops que precisam atravessar várias sessões, uma ferramenta como o RemoteCode para estender Claude Code e Codex em fluxos agentic entra como recurso do próprio autor para manter contexto de trabalho mais econômico e fazer agentes irem mais longe sem carregar todo o histórico no prompt principal.

Um loop agentic autocorretivo não é um agente "autônomo" no sentido solto. Ele é um processo com memória limitada, ferramentas explícitas e saída verificável. O agente pode tentar várias vezes, mas cada tentativa precisa produzir uma evidência menor e melhor que a anterior.

Quando usar subagentes em vez de uma conversa maior?

Em 2025, Stack Overflow apontou que 69% dos usuários de agentes concordaram que eles aumentaram produtividade, mas só 17% concordaram que melhoraram colaboração no time (Stack Overflow, "2025 Developer Survey: AI", 2025). Subagentes ajudam quando reduzem coordenação, não quando criam uma reunião paralela entre modelos.

Use subagentes para trabalho de leitura, investigação e crítica independente. Um subagente pode procurar riscos de segurança. Outro pode mapear testes quebrados. Outro pode resumir mudanças em um módulo legado. O agente principal não precisa receber todos os comandos que eles rodaram. Ele precisa receber achados com arquivo, linha, confiança e recomendação.

A documentação de subagentes do Codex alerta que despejar notas de exploração, logs e stack traces na conversa principal causa poluição e degradação de contexto. A recomendação é manter o agente principal focado em requisitos, decisões e saída final, enquanto subagentes retornam sínteses (OpenAI Developers, "Subagents", 2026).

Essa divisão combina bem com RAG sobre codebase e grafos de conhecimento. O subagente de recuperação pode explicar por que escolheu certos arquivos. O subagente de teste pode explicar qual suíte cobre o comportamento. O subagente de revisão pode apontar regressões prováveis. A conversa principal vira o lugar de decisão.

Evite subagentes escrevendo no mesmo trecho de código ao mesmo tempo. Isso aumenta conflito e torna a autoria da decisão nebulosa. Se precisar paralelizar escrita, divida por fronteiras reais: pacote, serviço, rota, schema ou camada de infraestrutura. Mesmo assim, consolide com um agente revisor antes de abrir PR.

Um fan-out útil tem três propriedades. A tarefa de cada subagente é pequena. A saída de cada subagente é uma síntese. O merge final exige prova. Se qualquer uma dessas propriedades faltar, uma conversa única com contexto mais limpo costuma ser melhor.

Como MCP muda a disciplina de contexto?

Em 2025, a especificação do Model Context Protocol definiu três superfícies centrais para servidores: recursos, prompts e ferramentas (Model Context Protocol, "Specification 2025-11-25", 2025). MCP muda a disciplina de contexto porque transforma acesso em interface: o agente não precisa receber tudo quando pode consultar a coisa certa, na hora certa.

Para agentes de código, recursos MCP podem expor arquivos, schemas de banco, documentação interna ou decisões arquiteturais. Ferramentas MCP podem rodar busca, consulta SQL, inspeção de fila, leitura de feature flags ou execução controlada de testes. Prompts MCP podem padronizar fluxos como triagem de bug, revisão de segurança ou análise de migração.

O risco é confundir capacidade com permissão. Um servidor MCP que acessa todo o banco, todos os segredos e todos os repositórios transforma um erro de prompt em erro operacional. A regra prática é expor ferramentas estreitas, com argumentos tipados, escopo por workspace e saída resumida. O agente deve pedir mais contexto, não ganhar tudo por padrão.

OWASP lista prompt injection, vazamento de informação sensível, supply chain, negação de serviço de modelo e excesso de agência entre os riscos de aplicações com LLMs em 2025 (OWASP, "Top 10 for Large Language Model Applications", 2025). Em um ambiente com MCP, esses riscos deixam de ser teóricos porque a ferramenta pode executar efeitos reais.

O melhor desenho de MCP para desenvolvimento não imita um terminal ilimitado. Ele parece mais com uma API interna: ferramentas pequenas, nomes explícitos, logs de auditoria e respostas que cabem em uma decisão. Se a ferramenta devolve uma enciclopédia, ela está competindo com o orçamento de contexto.

Como medir se o contexto ficou melhor?

Em 2025, GitHub relatou que desenvolvedores mesclaram em média 43,2 milhões de pull requests por mês e criaram mais de 230 repositórios por minuto (GitHub, "Octoverse 2025", 2025). Em escala real, medir contexto melhor significa medir revisão, retrabalho e tempo até prova, não apenas linhas geradas.

Escolha métricas que o time já sente. Quantas tentativas o agente faz antes de um teste passar? Quantos arquivos irrelevantes ele toca? Quantas observações de code review repetem a mesma falha? Quantas vezes o agente pede contexto que já deveria estar em AGENTS.md? Essas respostas mostram onde o orçamento de contexto está vazando.

Para times TypeScript, uma métrica simples é taxa de falha em typecheck depois de mudanças geradas por IA. GitHub observou em 2025 que TypeScript chegou ao primeiro lugar em crescimento de contribuidores e conectou essa ascensão a sistemas tipados que ajudam a levar código assistido por IA para produção (GitHub, "Octoverse 2025", 2025). Tipos viram parte do harness de contexto.

Use uma revisão de pós-loop curta. Peça ao agente para responder o que faltou no contexto, o que sobrou e que regra deveria virar instrução estável. Se a resposta for útil, atualize AGENTS.md ou o documento equivalente. Se a resposta for vaga, o loop não produziu aprendizado operacional.

Uma boa meta não é fazer o agente "usar menos tokens" a qualquer custo. A meta é fazer cada token carregar decisão. Um arquivo certo vale mais que cinco arquivos quase relacionados. Um teste que falha com mensagem clara vale mais que uma longa explicação. Um resumo honesto de subagente vale mais que mil linhas de log.

Checklist de adoção para uma base real

Em 2025, Google Cloud anunciou que o relatório DORA combinou mais de 100 horas de dados qualitativos com respostas de quase 5.000 profissionais de tecnologia (Google Cloud, "Announcing the 2025 DORA Report", 2025). A conclusão prática é que IA amplifica o sistema existente; por isso, adote context engineering como melhoria de plataforma, não como truque de prompt.

Antes de automatizar PRs, escreva um arquivo de instruções curto e real. Ele deve explicar como rodar o projeto, como testar, como revisar e quais áreas são sensíveis. Depois, crie um mapa de recuperação: onde ficam decisões arquiteturais, schemas, contratos de API, filas, jobs e runbooks. Sem esse mapa, RAG vira busca genérica.

Em seguida, padronize ferramentas. Se o agente precisa consultar banco, exponha uma ferramenta de leitura com escopo. Se precisa testar fila, exponha um comando controlado. Se precisa revisar segurança, forneça checklist e teste. Conecte isso ao CI para que a prova não dependa da boa vontade do modelo.

Por fim, feche o ciclo no PR. O diff deve vir com resumo, comandos rodados, evidência, riscos residuais e pontos que exigem revisão humana. Esse formato conversa com o post sobre tipos de testes no desenvolvimento de software e com práticas de arquitetura de serviços em TypeScript, porque agente bom ainda precisa de fronteiras claras.

Se a base tem CI frágil, comece pequeno. Escolha um módulo, uma suíte, um tipo de tarefa e um agente. Meça o retrabalho. Só depois adicione subagentes, MCP e automações. Context engineering de verdade é incremental: cada regra nasce de uma falha observada, não de uma lista genérica de boas práticas.

Perguntas frequentes (FAQ)

Em 2025, Stack Overflow mediu 84% de uso ou intenção de uso de IA entre desenvolvedores, mas também registrou 46% de desconfiança na precisão (Stack Overflow, "2025 Developer Survey: AI", 2025). As dúvidas mais importantes, portanto, não são sobre aderir à IA; são sobre limitar risco operacional.

Context engineering é só prompt engineering com outro nome?

Não. Em 2025, a DORA mediu 90% de adoção de IA em desenvolvimento de software, o que mostra que o problema já está no fluxo inteiro, não só no prompt (Google Cloud, "How are developers using AI? Inside our 2025 DORA report", 2025). Context engineering inclui recuperação, ferramentas, memória, permissões, evals e prova.

Quando vale usar subagentes?

Vale usar subagentes quando a tarefa pode ser dividida em investigação independente. Em 2025, Stack Overflow viu que 69% dos usuários de agentes perceberam ganho de produtividade, mas só 17% viram melhora de colaboração (Stack Overflow, "2025 Developer Survey: AI", 2025). Isso favorece subagentes de análise, não edição concorrente sem coordenação.

MCP deixa o agente mais seguro?

MCP melhora a interface, mas não garante segurança sozinho. Em 2025, a especificação oficial separou recursos, prompts e ferramentas como primitivas do protocolo (Model Context Protocol, "Specification 2025-11-25", 2025). Segurança vem de escopo, autenticação, auditoria, revisão humana e ferramentas estreitas.

Qual é o primeiro artefato para criar?

O primeiro artefato deve ser um arquivo de instruções do repositório. Em 2026, a documentação do Codex recomenda AGENTS.md com layout do repo, comandos, convenções, restrições e definição de pronto (OpenAI Developers, "Best practices - Codex", 2026). Sem isso, cada sessão reaprende o básico.

Fechamento

Em 2025, a DORA observou que equipes com mais confiança em IA tinham ganho maior de produtividade, mas também alertou que confiança sem fundamentos pode criar dependência acrítica (Google Cloud, "How are developers using AI? Inside our 2025 DORA report", 2025). Context engineering para agentes de código é uma prática de arquitetura: define o que o agente sabe, como descobre o que falta, que ferramentas aciona e que prova entrega.

O próximo passo é simples: escolha um tipo de tarefa repetitiva, escreva o contrato de contexto, conecte a verificação e rode um loop curto. Se o agente errar, não aumente o prompt primeiro. Descubra qual evidência faltou, qual ruído sobrou e qual gate deveria ter bloqueado o diff.

Fontes consultadas

• Google Cloud, "How are developers using AI? Inside our 2025 DORA report", recuperado em 2026-06-30, https://blog.google/innovation-and-ai/technology/developers-tools/dora-report-2025/
• Google Cloud, "Announcing the 2025 DORA Report: State of AI-Assisted Software Development", recuperado em 2026-06-30, https://cloud.google.com/blog/products/ai-machine-learning/announcing-the-2025-dora-report
• Stack Overflow, "2025 Developer Survey: AI", recuperado em 2026-06-30, https://survey.stackoverflow.co/2025/ai
• GitHub, "Octoverse: A new developer joins GitHub every second as AI leads TypeScript to #1", recuperado em 2026-06-30, https://github.blog/news-insights/octoverse/octoverse-a-new-developer-joins-github-every-second-as-ai-leads-typescript-to-1/
• OpenAI, "Introducing Codex", recuperado em 2026-06-30, https://openai.com/index/introducing-codex/
• OpenAI Developers, "Best practices - Codex", recuperado em 2026-06-30, https://developers.openai.com/codex/learn/best-practices
• OpenAI Developers, "Subagents", recuperado em 2026-06-30, https://developers.openai.com/codex/concepts/subagents
• OpenAI Developers, "Iterate on difficult problems", recuperado em 2026-06-30, https://developers.openai.com/codex/use-cases/iterate-on-difficult-problems
• Model Context Protocol, "Specification 2025-11-25", recuperado em 2026-06-30, https://modelcontextprotocol.io/specification/2025-11-25
• OWASP, "Top 10 for Large Language Model Applications", recuperado em 2026-06-30, https://owasp.org/www-project-top-10-for-large-language-model-applications/