Como economizar tokens de agentes de IA ao trabalhar com bases de código grandes: 5 padrões

O problema: os tokens se esgotam na exploração

Os agentes de IA estão se integrando cada vez mais ao processo de desenvolvimento — já não geram apenas funções, mas também exploram projetos, buscam arquivos, analisam a arquitetura e executam testes. Em bases de código grandes, surge um problema sério: uma parte significativa dos tokens é gasta antes mesmo de a primeira linha de código ser escrita. Antes de uma pequena alteração, o agente pode precisar estudar a estrutura do repositório, encontrar o serviço correto, ler a documentação, entender as convenções e verificar como os testes estão organizados. Na tarefa seguinte, parte dessa exploração se repete novamente. Em um projeto pequeno isso passa desapercebido, mas quanto maior o repositório, mais cara fica a exploração do sistema.

Tentar alimentar o agente com toda a documentação de uma vez, ou usar um modelo mais barato, traz pouco efeito ou apenas transfere o gasto de tokens para outro lugar. A abordagem correta é tratar o gerenciamento de tokens como um problema de gerenciamento de contexto, aplicando os princípios de lazy loading, localidade de dados, cache e separação de responsabilidades ao fluxo de informações do agente de IA.

Cinco padrões de otimização de contexto

1. Minimize Permanent Context

A armadilha de acumular conhecimento sempre segue o mesmo caminho: cria-se um AGENTS.md ou CLAUDE.md e começa-se a colocar cada vez mais informações ali. Primeiro a arquitetura e a estrutura do repositório, depois as regras de escrita de código, as convenções dos serviços, as particularidades do banco de dados, dos testes, do CI/CD e das integrações.

O problema é que todo esse conjunto se torna contexto permanente. Ao modificar o serviço de billing, é improvável que o agente precise das regras de desenvolvimento do aplicativo mobile, mas se elas estiverem no contexto global, o modelo as recebe repetidamente. As instruções globais devem ser um mapa do projeto (onde está a informação?), não uma enciclopédia (o que contar sobre tudo?). O AGENTS.md raiz deve indicar onde estão as instruções detalhadas de auth, billing, database e infrastructure — todo o resto é carregado sob demanda.

2. Progressive Context

O conhecimento é organizado em camadas: contexto global → contexto de domínio/serviço → instruções específicas da tarefa → implementação de referência → código-fonte relevante. Para a tarefa de adicionar um novo payment provider, o agente percorre o caminho: AGENTS.md → services/payments/AGENTS.md → skills/add-payment-provider.md → implementação existente do provedor → arquivos de código relevantes. Para um aplicativo mobile, o caminho é completamente diferente; para infraestrutura, há um terceiro. Em vez de 20.000 tokens sobre "tudo do projeto", obtém-se: contexto global (500) + contexto de serviço (700) + instruções da tarefa (600) + referência (800) + arquivos de código (2500). A maior parte do conhecimento do projeto existe separadamente e só entra no contexto quando se torna relevante.

3. Reduce Exploration

Mesmo com um contexto permanente pequeno, resta uma grande fonte de gasto: a exploração da base de código. O agente precisa descobrir onde estão os handlers de pagamento, qual serviço publica eventos, qual message broker é usado, onde estão os consumers, como as notificações são criadas, onde estão os templates e como tudo isso é testado. Um repositório bem organizado oferece pontos de entrada: um mapa do projeto com seções (HTTP handlers: services//handlers/, business logic: services//domain/ etc.)

, golden examples (para um novo message consumer, um link para services/orders/consumers/order-created/ mostra a estrutura, a nomenclatura, o tratamento de erros, o logging, a interação entre camadas e os testes) e search before read (primeiro buscar com rg, git grep ou ferramentas LSP, depois ler).

4. Reuse Knowledge

Quando um agente investiga o pagamento de um pedido, ele revela a cadeia: requisição HTTP → serviço de pedidos → serviço de billing → payment provider → evento de pagamento → message broker → consumer de pedidos. Para isso, lê centenas de arquivos. Em seguida, a sessão termina, uma nova tarefa chega uma semana depois, e um novo agente começa a exploração do zero.

Essa duplicação de conhecimento precisa ser eliminada. Se a exploração revelou uma característica importante e estável do sistema, vale a pena salvar o resultado em docs/payment-flow.md com uma breve descrição, uma lista de arquivos e um link para uma implementação de referência.

A próxima sessão de IA começará com algumas centenas de tokens de descrição estruturada em vez de reler os arquivos. Conhecimentos úteis podem ser armazenados em AGENTS.md, instruções de serviço, documentação, skills específicas da tarefa, notas de arquitetura, golden examples ou comentários no código, dependendo do escopo.

O resultado é um ciclo: descoberta cara → conhecimento estruturado → recuperação futura barata.

5. Keep Context Clean

O lado inverso dessa abordagem: se cada descoberta útil for salva, a documentação cresce continuamente e surge a poluição de contexto — instruções desatualizadas, exemplos obsoletos e convenções esquecidas convivem com as novas. O contexto precisa ser limpo regularmente: removendo informações obsoletas, atualizando exemplos e eliminando duplicações. Assim como no código, é melhor excluir documentação obsoleta do que deixá-la com um comentário explicando que está desatualizada.

Os cinco padrões funcionam juntos: minimizamos o contexto permanente, carregamos o conhecimento em camadas conforme a necessidade, ajudamos o agente a explorar menos por meio de pontos de entrada claros, não repetimos uma exploração cara duas vezes e removemos informações obsoletas. O resultado é uma redução no gasto de tokens — não por meio de modelos mais baratos, mas pelo gerenciamento de quais informações o agente vê e quando.