Context engineering para agentes de código é a prática de decidir o que entra, o que fica fora e o que só será buscado sob demanda durante um loop agentic. A resposta curta: não dê o repositório inteiro ao agente. Dê uma spec clara, pistas rastreáveis, comandos de verificação e ferramentas para buscar o resto.
Em 2025, o Stack Overflow Developer Survey informou que 84% das pessoas respondentes usam ou planejam usar IA no desenvolvimento, contra 76% no ano anterior (Stack Overflow, Developer Survey 2025 AI, acesso em 2026-07-01). Essa adoção cria uma nova disciplina prática: controlar contexto virou parte do trabalho de engenharia.
Este post continua o raciocínio de harness para agentes de código antes do PR. O harness decide quando o agente pode entregar. O context engineering decide o que o agente precisa saber antes de começar, durante a investigação e antes de abrir o pull request.
Versões deste artigo: inglês e espanhol. Para contexto de autoria, consulte a página sobre. Para pauta, correção ou parceria editorial, use a página de contato.
TL;DR prático
- Com 84% de adoção ou intenção de uso de IA, contexto virou gargalo de engenharia.
- O agente deve começar com spec, arquivos prováveis, contratos e comandos, não com dump do repo.
- Subagentes, MCP e RAG ajudam quando atrasam a leitura até ela ser necessária.
O que é context engineering para agentes de código?
Em 2025, 51% dos desenvolvedores profissionais disseram usar ferramentas de IA diariamente (Stack Overflow, Developer Survey 2025 AI, acesso em 2026-07-01). Context engineering é a resposta operacional a esse uso frequente: preparar uma janela de trabalho que ajude o agente a decidir, editar e verificar sem afogar a conversa.
O erro comum é confundir contexto com volume. Mais arquivo não significa mais entendimento. Um agente pode ler muitos trechos e ainda perder o contrato que importava: a rota que não pode quebrar, a fila que exige idempotência, a migração que precisa de rollback ou o teste que representa o comportamento real.
Contexto bom tem função. Ele reduz incerteza antes da primeira edição, mostra onde procurar quando surge dúvida e preserva evidência para revisão. Se um trecho não muda nenhuma dessas decisões, ele provavelmente não deveria entrar no começo do loop.
Em síntese, context engineering para agentes de código é a disciplina de transformar um repositório grande em um caminho navegável. O Stack Overflow registrou 51% de uso diário de IA entre desenvolvedores profissionais em 2025 (Stack Overflow, acesso em 2026-07-01), então a diferença não está apenas no modelo. Ela está no que o agente recebe, no que ele pode buscar e no que precisa provar antes de entregar.
Por que contexto demais piora o agentic coding?
A Anthropic descreve uma mudança para estratégias de contexto "just in time", em que agentes mantêm identificadores leves, como caminhos de arquivo e consultas salvas, e carregam dados em tempo de execução por ferramentas (Anthropic, Effective context engineering for AI agents, acesso em 2026-07-01). O ponto é simples: contexto útil pode ser buscado quando vira necessário.
Quando você empilha arquivos logo no prompt, três coisas acontecem. O agente gasta atenção em trechos que talvez nunca use. A conversa fica mais difícil de auditar. E a próxima iteração carrega decisões antigas, logs e hipóteses que deveriam ter sido descartadas.
A melhor pergunta não é "quanto cabe na janela?". É "qual informação muda a próxima decisão?". Para uma correção de API, isso costuma incluir contrato, handler, teste próximo, middleware e comando de validação. Não costuma incluir documentação antiga, logs completos, changelog inteiro ou arquivos gerados.
Em fluxos longos, a economia real vem de atravessar mais trabalho com menos repetição de contexto. Quando o agente precisa investigar codebases grandes ou manter loops agentic sem reler tudo, uma ferramenta do próprio autor como RemoteCode para fazer Claude Code e Codex avançarem mais com menos desperdício de contexto pode ser útil, desde que a decisão final continue no harness e no CI.
Como montar o contexto inicial antes da primeira edição?
Em 2025, 47,1% de todos os respondentes do Stack Overflow disseram usar IA diariamente, e 17,7% disseram usar semanalmente (Stack Overflow, Developer Survey 2025 AI, acesso em 2026-07-01). Com esse ritmo, contexto inicial precisa virar rotina curta, não cerimônia pesada.
Comece pela spec. Ela deve dizer o comportamento esperado, o que está fora do escopo e o critério de aceite. Depois liste os arquivos prováveis e por que eles importam. Em seguida, registre contratos externos: endpoint, schema, evento de fila, feature flag, permissão ou variável de ambiente.
Inclua os comandos que provam a mudança. Para backend, isso pode ser teste de unidade, teste de integração, typecheck, lint e comando local que sobe dependências. Para DevOps, pode ser plan de IaC, validação de policy, teste de workflow e comando que simula o job no ambiente mais próximo possível.
| Entrada de contexto | Por que entra | Sinal de descarte |
|---|---|---|
| Spec curta | Define o contrato do trabalho | Se virar discussão de produto, volta para refinamento. |
| Arquivos prováveis | Dá ponto de partida para navegação | Se o agente não justificar a leitura, sai do início. |
| Testes próximos | Mostra comportamento esperado | Se não cobrem a mudança, viram tarefa antes do patch. |
| Comandos de verificação | Impedem entrega por aparência | Se não rodam localmente, o PR precisa explicar o bloqueio. |
| Contratos externos | Evitam quebrar consumidores | Se a fonte não existe, a claim sai do texto do PR. |
Em síntese, o contexto inicial deve caber em uma revisão humana rápida. A adoção diária de IA por 47,1% dos respondentes em 2025 (Stack Overflow, acesso em 2026-07-01) torna esse preparo repetitivo o bastante para merecer padrão. Se o agente não consegue dizer qual contrato, teste e arquivo justificam a primeira edição, ele ainda está explorando.
Quando usar subagentes para preservar contexto?
A documentação de Claude Code afirma que cada subagente roda em janela própria, com prompt, acesso a ferramentas e permissões independentes, retornando resultados para a conversa principal (Anthropic, Create custom subagents, acesso em 2026-07-01). Use isso quando a exploração lateral geraria muito ruído.
Subagente não é convite para delegar tudo. Ele é bom para tarefas estreitas: localizar arquivos relevantes, resumir logs, revisar um diff, comparar contratos ou investigar uma falha de teste. O retorno deve ser curto, com evidência e próximos passos. Se ele devolve um bloco enorme, o problema de contexto só mudou de lugar.
Use fan-out quando as perguntas são independentes. Por exemplo: um subagente lê logs de produção, outro revisa migração, outro procura testes relacionados. O agente principal decide com base nas sínteses. Não deixe vários subagentes editarem os mesmos módulos sem uma spec comum.
Em síntese, subagentes preservam contexto quando isolam exploração e devolvem decisão. A própria documentação alerta que muitos subagentes retornando resultados detalhados podem consumir contexto significativo (Anthropic, Create custom subagents, acesso em 2026-07-01). Portanto, o formato de resposta importa tanto quanto a delegação.
Onde MCP e RAG entram sem virar despejo?
O Model Context Protocol define MCP como um padrão aberto para conectar aplicações de IA a sistemas externos, incluindo fontes de dados, ferramentas e fluxos de trabalho (Model Context Protocol, What is MCP?, acesso em 2026-07-01). No contexto de código, isso deve ser porta de acesso, não aterro de informação.
MCP é útil quando o agente precisa consultar issue, banco de teste, Sentry, documentação interna, Figma, GitHub ou outro sistema fora do repositório. O contexto inicial deve dizer quando usar a ferramenta e qual evidência trazer de volta. Ele não deve colar toda a issue, todo o log e todo o schema se a decisão ainda não exige isso.
A documentação de Claude Code também recomenda conectar MCP quando você se vê copiando dados de outra ferramenta para o chat, como issue tracker ou dashboard de monitoramento (Anthropic, Connect Claude Code to tools via MCP, acesso em 2026-07-01). Essa é uma régua prática: se você cola sempre, talvez vire ferramenta.
RAG sobre codebase segue a mesma lógica. Ele ajuda quando encontra trechos candidatos, mas não substitui leitura dirigida. O agente ainda precisa explicar por que aquele arquivo é relevante, qual contrato foi identificado e qual teste protege a mudança.
Em síntese, MCP e RAG devem atrasar o carregamento de contexto até haver uma pergunta. A especificação pública do MCP fala em conexão com dados, ferramentas e workflows (Model Context Protocol, acesso em 2026-07-01). O harness precisa limitar permissão, registrar fonte e exigir evidência no PR.
Como Codex e Claude Code leem instruções de projeto?
A documentação de Codex informa que arquivos AGENTS.md são concatenados do diretório raiz até o diretório atual, e que o limite padrão para instruções de projeto é 32 KiB (OpenAI, Custom instructions with AGENTS.md, acesso em 2026-07-01). Isso mostra um ponto importante: instrução também consome orçamento.
Não transforme AGENTS.md em enciclopédia. Coloque regras estáveis: comandos de teste, padrões de PR, limites de permissão, arquivos proibidos, estilo de migração e critérios de revisão. Conteúdo específico da tarefa deve ficar na spec, porque muda a cada loop.
Claude Code segue outra superfície de configuração, mas a ideia de camadas continua útil. Instruções duráveis ficam no projeto. Contexto efêmero fica na tarefa. Dados externos entram por ferramenta. Resultado de investigação vira síntese curta.
Em síntese, instrução de projeto é contexto de alto impacto e baixa rotatividade. O limite padrão de 32 KiB em Codex (OpenAI, acesso em 2026-07-01) não é meta para preencher. É aviso para escrever regras menores, mais estáveis e mais fáceis de auditar.
Como verificar se o contexto funcionou antes do PR?
Em 2025, 58,7% dos respondentes do Stack Overflow disseram não planejar usar IA para commit e revisão de código, enquanto 44,1% disseram não planejar usar IA para testes (Stack Overflow, Developer Survey 2025 AI, acesso em 2026-07-01). Esse ceticismo é útil: contexto só funciona quando melhora verificação, não quando aumenta confiança textual.
Peça ao agente um relatório final curto. Ele deve listar quais arquivos leu, quais fontes externas consultou, quais comandos executou, quais testes falharam antes, quais passaram depois e quais riscos sobraram. Se algo não foi verificado, deve aparecer como limitação, não como promessa.
Codex Code Review pode ser configurado para revisar pull requests no GitHub, seguir orientação do repositório e focar em problemas sérios; a documentação informa que ele sinaliza P0 e P1 para manter comentários concentrados em riscos prioritários (OpenAI, Codex code review in GitHub, acesso em 2026-07-01). Essa é uma boa comparação: revisão útil corta ruído.
O critério final é simples: o contexto funcionou se o diff ficou menor, a justificativa ficou mais auditável e o CI conseguiu confirmar comportamento. Se o agente editou demais, leu pouco do contrato ou não sabe explicar a origem de uma decisão, volte ao mapa de contexto antes de pedir outro patch.
Checklist de contexto para o próximo loop agentic
Em 2025, 75,8% dos respondentes do Stack Overflow disseram não planejar usar IA para deployment e monitoramento (Stack Overflow, Developer Survey 2025 AI, acesso em 2026-07-01). Para sistemas reais, essa cautela faz sentido: quanto mais perto de produção, mais duro deve ser o checklist.
- A spec diz comportamento esperado e fora de escopo.
- Os arquivos iniciais têm motivo explícito para entrar.
- Contratos de API, filas, permissões e variáveis críticas estão citados.
- Testes e comandos de validação aparecem antes da edição.
- Logs e documentos longos ficam para busca sob demanda.
- Subagentes têm pergunta estreita e formato de resposta curto.
- MCP entra com permissão limitada e evidência exigida.
- O PR registra comandos, riscos e limitações sem esconder falhas.
Na prática, o melhor contexto raramente é o mais bonito. É o que impede o agente de trabalhar em volta do problema. Quando a spec, os testes e os contratos certos entram cedo, o modelo erra menos por desvio de escopo e a revisão humana fica menos cansativa.
FAQ sobre context engineering para agentes de código
O que é context engineering para agentes de código?
É a prática de escolher e organizar o contexto que guia um agente de código. Em vez de carregar tudo no prompt, você dá spec, arquivos prováveis, contratos e comandos, enquanto deixa buscas maiores para ferramentas, subagentes ou MCP.
Como economizar tokens sem deixar o agente cego?
Use contexto inicial pequeno e navegação sob demanda. A Anthropic descreve estratégias "just in time" em que agentes mantêm referências leves e carregam dados no runtime (Anthropic, acesso em 2026-07-01). Isso reduz ruído sem impedir investigação.
Quando subagentes ajudam no contexto?
Eles ajudam quando uma tarefa lateral poluiria a conversa principal com logs, buscas ou arquivos longos. A documentação de Claude Code diz que subagentes rodam em janelas próprias e retornam resultados (Anthropic, acesso em 2026-07-01). O retorno deve ser síntese.
MCP deve entrar no contexto inicial?
Normalmente, não. MCP deve ficar disponível como ferramenta quando o agente precisa consultar sistemas externos. A especificação define MCP como padrão aberto para conectar IA a dados, ferramentas e workflows (Model Context Protocol, acesso em 2026-07-01).
Qual é o sinal de que o contexto inicial foi bom?
O agente edita menos arquivos, cita contratos corretos, executa comandos de validação e explica riscos sem inventar certeza. Se o PR exige que o revisor reconstrua a intenção, o contexto inicial provavelmente estava grande, vago ou incompleto.
Fontes consultadas
- Stack Overflow, Developer Survey 2025 AI, acesso em 2026-07-01, https://survey.stackoverflow.co/2025/ai
- Anthropic, Effective context engineering for AI agents, acesso em 2026-07-01, https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents
- Anthropic, Create custom subagents, acesso em 2026-07-01, https://code.claude.com/docs/en/sub-agents
- Anthropic, Connect Claude Code to tools via MCP, acesso em 2026-07-01, https://code.claude.com/docs/en/mcp
- Model Context Protocol, What is MCP?, acesso em 2026-07-01, https://modelcontextprotocol.io/docs/getting-started/intro
- OpenAI, Custom instructions with AGENTS.md, acesso em 2026-07-01, https://developers.openai.com/codex/guides/agents-md
- OpenAI, Codex code review in GitHub, acesso em 2026-07-01, https://developers.openai.com/codex/integrations/github
Créditos das imagens: infográficos raster gerados localmente em SVG e convertidos para WebP para este post. O arquivo de créditos fica em /files/posts/context-engineering-agentes-codigo-sem-estourar-tokens/image-credits.txt.
