Eficiência de contexto: como reduzir o custo real de agentes de código

Um agente de código recebe uma tarefa simples: alterar uma regra de validação em um serviço. Em vez de ler o módulo responsável, suas dependências diretas e os testes relacionados, a ferramenta despeja no contexto arquivos inteiros, configurações, documentação antiga e trechos de módulos que não participam daquela decisão.

O resultado pode até funcionar. Mas há uma conta escondida: o modelo processou informação que não precisava, o time pagou por ela e a resposta ficou mais difícil de revisar. Quando o preço acompanha o consumo, contexto mal selecionado deixa de ser apenas uma ineficiência técnica. Ele vira uma decisão de orçamento.

Relatos publicados após a adoção de cobrança baseada em uso do GitHub Copilot descreveram aumentos expressivos em fluxos agentivos, incluindo casos que teriam saído de cerca de US$ 29 para US$ 750 ou de US$ 50 para US$ 3.000 mensais conforme a reportagem. Os valores relatados não formam uma métrica universal de custo, mas expõem o problema: quando a unidade de cobrança muda, desperdício de contexto aparece no extrato.

O problema não é só o modelo escolhido

A reação mais imediata costuma ser trocar o modelo. Um modelo menor pode custar menos por token; um modelo maior pode resolver tarefas difíceis com menos tentativas. Em alguns ambientes, equipes também adotam roteamento: tarefas simples vão para modelos menores e casos ambíguos são escalados.

Essas estratégias são úteis, mas não corrigem a causa principal quando o agente recebe informação demais. Um modelo caro, alimentado por um repositório inteiro para modificar uma função, continua sendo uma solução cara. Um modelo barato, submetido a contexto irrelevante, pode gastar tokens em hipóteses que nunca precisaria considerar.

O ponto central é outro: o agente precisa receber o contexto necessário para tomar a decisão, não o máximo de contexto disponível.

Essa diferença parece óbvia, mas muda a forma de construir ferramentas de desenvolvimento assistido por IA. O repositório não é um prompt. É um sistema com fronteiras, dependências, contratos, convenções e histórico. O trabalho da ferramenta não deveria ser simplesmente copiar arquivos; deveria ser selecionar evidências.

Contexto bruto não é contexto útil

Considere uma solicitação para adicionar uma política de retry a um cliente HTTP. O arquivo do cliente é necessário, mas provavelmente não é suficiente. Também podem importar:

• o contrato da interface usada pelo cliente;
• os adapters que implementam esse contrato;
• os testes de timeout e tratamento de erro;
• a configuração de observabilidade;
• as regras existentes para circuit breaker;
• os consumidores que dependem da semântica atual.

Ao mesmo tempo, não é necessariamente útil enviar todos os handlers da aplicação, o histórico completo do repositório ou cada arquivo de configuração. Esses itens podem aumentar a superfície de busca sem melhorar a decisão.

Contexto relevante tem pelo menos três dimensões:

1. Dados: quais entidades, endpoints, tabelas ou eventos participam da mudança.
2. Dependências: quais módulos chamam, implementam ou são afetados pelo componente alterado.
3. Intenção: qual comportamento deve mudar, quais invariantes precisam permanecer e como o resultado será verificado.

A terceira dimensão é frequentemente esquecida. Um agente pode encontrar o código correto e ainda produzir uma alteração errada se não souber o motivo da mudança. “Adicionar cache” é uma instrução incompleta. Cache de quê? Com qual validade? O que acontece depois de uma atualização? Qual dado não pode ser servido fora da fronteira do usuário?

Sem intenção, a ferramenta tende a inferir. E inferência é uma fonte de retrabalho, especialmente em sistemas legados onde o comportamento real está distribuído entre código, configuração e operação.

Menos tokens não significa menos rigor

Reduzir contexto não é cortar informação de forma cega. É aumentar a densidade de informação útil.

Uma solicitação eficiente pode incluir o arquivo-alvo, as interfaces relacionadas, dois testes representativos e uma regra explícita de aceitação. Uma solicitação ineficiente pode incluir cinquenta arquivos e nenhuma descrição do comportamento esperado. A primeira é menor e, ao mesmo tempo, mais rigorosa.

O ganho aparece em quatro pontos:

• Custo: menos tokens de entrada reduzem o consumo por tarefa, dependendo do modelo e do mecanismo de cobrança.
• Foco: o agente passa menos tempo distinguindo sinal de ruído.
• Previsibilidade: prompts e resultados ficam mais comparáveis entre execuções.
• Revisão: o desenvolvedor consegue entender quais evidências sustentaram a alteração.

Isso também ajuda a evitar uma confusão comum: uma resposta curta não é necessariamente uma resposta eficiente. Se o agente omite uma dependência importante e precisa refazer a tarefa três vezes, o contexto economizado na primeira execução pode custar mais no total.

A métrica útil não é apenas tokens por chamada. É o custo para chegar a uma alteração correta, verificável e pronta para revisão. Esse custo inclui tentativas, correções manuais, execução de testes e tempo humano gasto investigando uma mudança que não tinha premissas claras.

Como curar o contexto de um agente

A curadoria começa antes da chamada ao modelo. Ela deve ser tratada como parte da engenharia do fluxo, não como um detalhe do prompt.

1. Comece pelo comportamento, não pelo arquivo

Descreva a mudança em termos de comportamento observável. Liste o que deve acontecer, o que deve continuar igual e quais casos de erro precisam ser tratados. Só então localize os arquivos que implementam esse comportamento.

Essa ordem evita que o agente confunda o primeiro arquivo encontrado com a fronteira real da mudança.

2. Construa um cone de dependências

Para cada arquivo candidato, examine quem o chama, quais interfaces ele implementa e quais componentes dependem de sua saída. O cone não precisa incluir o repositório inteiro. Deve alcançar as partes que podem invalidar a alteração.

Em mudanças de integração, por exemplo, o cone deve incluir timeout, retry, tratamento de erro e observabilidade. Em mudanças de domínio, pode precisar incluir regras de consistência, eventos publicados e consumidores desses eventos.

3. Envie contratos e invariantes

Uma assinatura de função raramente captura todas as regras de um sistema. Inclua invariantes relevantes: idempotência, autorização, ordenação, compatibilidade de payload, limites de latência ou comportamento diante de falhas.

Quando uma regra não está documentada, isso também é informação. O agente deve poder marcar a lacuna como uma pergunta, em vez de preencher o vazio com uma suposição.

4. Faça o agente provar a mudança

O resultado não deve ser apenas um diff. Peça testes, referências aos arquivos alterados e uma explicação das decisões. Se a ferramenta não encontrou evidência suficiente, o resultado deve registrar essa incerteza.

Esse mecanismo cria uma separação importante entre fato e hipótese. “A interface é usada por três adapters” é uma afirmação verificável. “Este adapter não será afetado” é uma conclusão que precisa de análise. Misturar as duas coisas torna a revisão mais lenta e o risco menos visível.

O que medir no fluxo

A equipe não precisa começar com um painel complexo. Algumas perguntas já revelam desperdício:

• Quantos tokens de contexto entram em tarefas de tamanho semelhante?
• Quantos arquivos foram enviados, e quantos apareceram no diff final?
• Quantas execuções terminam em alteração descartada?
• Quantas tarefas precisam de uma segunda rodada por contexto ausente?
• Quais tipos de mudança geram mais retrabalho?
• O tempo economizado pelo agente supera o tempo de revisão e correção?

Não transforme essas perguntas em metas artificiais. Um contexto pequeno pode ser inadequado para uma migração ampla; um contexto grande pode ser necessário para uma mudança transversal. O objetivo é entender a relação entre contexto, evidência e resultado.

Também vale separar custo de exploração de custo de execução. Uma tarefa agentiva pode gastar tokens para descobrir onde está a regra e depois gastar mais para implementá-la. Um inventário confiável, um grafo de dependências ou um mapa de integração reduzem a necessidade de repetir essa exploração em cada chamada.

Onde uma análise arquitetural ajuda

A eficiência do agente depende da qualidade do mapa que ele usa para navegar. Se o time não sabe quais módulos formam o núcleo, onde estão os hotspots de mudança ou quais integrações possuem tratamento de erro frágil, a ferramenta terá de descobrir isso de maneira repetida e cara.

É nesse ponto que uma análise arquitetural pode somar ao fluxo de desenvolvimento assistido por IA. Um diagnóstico baseado no repositório pode fornecer evidências sobre dependências, fronteiras, seams legados, superfície de API, hotspots e saúde dos testes. Esses artefatos não substituem a decisão do desenvolvedor, mas ajudam a montar um contexto menor e mais confiável para cada tarefa.

O ArchGenerator segue essa lógica: conecta-se ao repositório e apresenta achados com evidência de arquivo e linha; quando não há dado suficiente, declara o resultado inconclusivo. A partir do diagnóstico, também é possível gerar um kit SDD com especificações, contratos, prioridades e sensores de progresso para orientar a execução. O valor, nesse cenário, não está em entregar mais texto ao agente, mas em entregar contexto rastreável.

Eficiência é uma disciplina de engenharia

A cobrança por consumo apenas torna visível um problema que já existia. Contexto excessivo sempre teve custo: respostas menos focadas, revisões mais difíceis, maior chance de alteração fora da fronteira e mais tempo gasto corrigindo interpretações.

A solução não é escolher entre modelos grandes e pequenos como se essa fosse a única variável. É construir um fluxo que saiba localizar a mudança, selecionar dependências, declarar intenção, preservar invariantes e exigir evidência do resultado.

Agentes de código funcionam melhor quando recebem um mapa, não um depósito de arquivos. Para o time, isso significa tratar contexto como um artefato curado: limitado o suficiente para ser eficiente, completo o suficiente para sustentar a decisão e rastreável o suficiente para ser revisado. Quando essa disciplina existe, economizar tokens deixa de ser uma otimização financeira isolada e passa a melhorar a qualidade do próprio desenvolvimento.