Engenharia de Contexto para Agentes de Código: por que a maioria falha

O que é engenharia de contexto para agentes de código

Você já tentou usar um agente de IA para escrever código e ficou frustrado com resultados inconsistentes? O agente repete o mesmo erro, não segue as convenções do projeto ou esquece o que foi dito três mensagens atrás. Isso tem nome: falta de engenharia de contexto.

Engenharia de contexto e a prática de estruturar, selecionar e gerenciar as informações que um agente de IA recebe para executar tarefas de programação. Não basta ter acesso ao modelo mais poderoso - se o contexto for ruim, o resultado será ruim.

O conceito ganhou popularidade em 2025 e 2026, quando times de engenharia começaram a notar que o problema não era o LLM em si, mas como o LLM recebia as instruções. Um post no Hacker News com mais de 300 upvotes em julho de 2026 acendeu o debate: por que as fabricas de software com IA falham não por causa de modelos ruins, mas por pipelines de contexto ruins.

Como funciona

Um agente de código e, na prática, um loop: ele recebe um prompt com contexto, gera uma resposta (código, comando, decisão), executa ou propõe, e então recebe feedback para continuar. O problema e que esse loop depende completamente do que entra no prompt.

O contexto de um agente pode incluir: o código do projeto (ou parte dele), o histórico de mensagens, regras e convenções, arquivos de configuração, saída de comandos anteriores e instruções do sistema. Quando esse conjunto e mal montado, o agente trabalha no escuro.

A engenharia de contexto define o que entra, em que ordem e com qual nível de detalhe. Ela também lida com limitações práticas: todo modelo tem uma janela de contexto finita (medida em tokens), e colocar informação desnecessária desperdiça espaço para o que realmente importa.

Principais recursos e técnicas

Existem diversas técnicas consolidadas de engenharia de contexto. As mais usadas por times de engenharia hoje são:

• Janela deslizante: manter apenas as N mensagens mais recentes no histórico, descartando mensagens antigas para liberar tokens.
• RAG (Retrieval-Augmented Generation): buscar apenas os trechos de código relevantes para a tarefa atual, em vez de jogar o repositório inteiro no prompt.
• Resumo de histórico: ao invés de descartar mensagens antigas, resumir o que foi decidido e incluir o resumo como contexto compacto.
• System prompts estruturados: instruções claras sobre convenções do projeto, linguagem, frameworks usados e regras de negócio.
• Tool calling com contexto mínimo: deixar o agente buscar o que precisa sob demanda (leitura de arquivo, grep, execução) em vez de pre-carregar tudo.

Ferramentas como Claude Code, Cursor e GitHub Copilot Workspace implementam versões dessas técnicas nos bastidores. Mas quando você monta seu próprio agente, precisa pensar em cada uma delas.

Como começar: montando seu primeiro pipeline de contexto

Se você quer experimentar engenharia de contexto na prática, comece pequeno. Escolha uma tarefa específica (ex: o agente corrige bugs em funções Python) e monte o pipeline passo a passo.

Passo 1: Defina um system prompt com as convenções do seu projeto. Linguagem, estilo de código, frameworks proibidos, padrões de nomenclatura.

system_prompt = """
Você e um assistente de código Python.
Convenções deste projeto:
- PEP 8 obrigatório
- Docstrings em português
- Sem dependências externas além do requirements.txt
- Funções com mais de 20 linhas devem ser quebradas
"""

Passo 2: Implemente RAG básico. Use embeddings para indexar seu código e buscar apenas os arquivos relevantes para a tarefa atual. Bibliotecas como chromadb ou faiss facilitam isso em Python.

Passo 3: Limite o histórico. Mantenha no máximo as últimas 10 trocas de mensagem, ou resuma o histórico a cada 5 interações usando o próprio LLM.

pip install chromadb openai
# ou
pip install anthropic chromadb

Passo 4: Adicione feedback estruturado. Após cada execução de código, inclua a saída (stdout/stderr) de volta no contexto para o próximo passo.

Exemplo prático: agente que corrige testes falhando

Imagine um agente que recebe uma suite de testes com falhas e precisa corrigir o código. Um pipeline bem estruturado funcionaria assim:

# 1. Contexto inicial
contexto = [
    system_prompt,  # convenções do projeto
    f"Testes falhando:\n{saida_pytest}",  # output dos testes
    f"Arquivo com bug:\n{conteudo_arquivo}",  # só o arquivo relevante
]

# 2. Agente gera correção
resposta = llm.complete(contexto)

# 3. Executa e captura feedback
resultado = executar_pytest()

# 4. Adiciona feedback e itera
contexto.append(f"Resultado após correção:\n{resultado}")

Perceba que o agente não recebe o repositório inteiro - apenas o arquivo relevante e a saída dos testes. Isso economiza tokens e foca o modelo no problema real.

Comparação com alternativas

Existem diferentes abordagens para agentes de código, e a escolha depende do seu caso de uso:

• Ferramentas prontas (Claude Code, Cursor): fazem a engenharia de contexto automaticamente. Ideais para uso individual e projetos menores. Menos customizaveis.
• Frameworks (LangGraph, CrewAI, AutoGen): oferecem estrutura para pipelines mais complexos. Bom equilíbrio entre produtividade e controle.
• Implementação própria: máximo controle, mas exige conhecimento profundo de engenharia de contexto. Recomendada para casos de uso muito específicos ou em escala.

A diferença principal: ferramentas prontas resolvem 80% dos casos, mas os 20% restantes (projetos grandes, regras de negócio complexas, integração com sistemas internos) geralmente precisam de engenharia de contexto customizada.

Pontos positivos e limitações

A engenharia de contexto resolve problemas reais: agentes mais consistentes, menos alucinações, código que segue as convenções do projeto. Times que investem nisso relatam redução significativa de erros e retrabalho.

As limitações são igualmente reais. Janelas de contexto ainda são finitas - mesmo modelos com 200k tokens tem limites práticos. RAG introduz latência e pode trazer contexto irrelevante se os embeddings forem ruins. E manter um sistema de contexto tem custo operacional.

Outro ponto crítico: não existe solução universal. O pipeline ideal para um monorepo de 500 mil linhas e diferente do ideal para um script Python de 200 linhas. Você vai iterar.

Casos de uso reais

Quatro perfis que se beneficiam diretamente de agentes com boa engenharia de contexto:

• Dev solo em startup: usa agente para gerar CRUDs e testes automatizados, com contexto carregando as convenções do projeto e o schema do banco. Economiza horas por semana.
• Time de QA: agente que recebe bug reports e gera casos de teste automaticamente, com contexto incluindo o código da feature e o histórico de bugs similares.
• Engenheiro de plataforma: agente que monitora logs, identifica padrões de erro e sugere correções, com contexto incluindo runbooks e histórico de incidentes.
• Estudante aprendendo uma nova linguagem: agente com contexto de boas práticas da linguagem alvo e exemplos do estilo que o estudante quer seguir.

Dicas e boas práticas

Vale a pena?

Se você usa agentes de IA esporadicamente para tarefas simples, as ferramentas prontas como Claude Code ou Cursor já fazem um trabalho excelente de gerenciar o contexto. Não ha necessidade de construir nada do zero.

Mas se você esta construindo um produto ou pipeline de automação que depende de agentes de código em produção, engenharia de contexto não e opcional - e o que determina se o sistema vai funcionar ou vai frustrar todos que o usam.

O próximo passo prático: escolha um agente que você já usa, observe onde ele falha, e pergunte qual informação faltou no contexto para ele acertar. Essa e a pergunta central da disciplina - e já e um ótimo lugar para começar.