Construindo um Agente de Codificação para Contexto de 8k: Divisão Planejador/Executor, Orçamento de Tokens e Execução Paralela

A maioria das ferramentas de codificação com IA assume modelos de 200 mil tokens, mas se você estiver executando LLMs locais via Ollama, LM Studio ou APIs de nível gratuito como Groq ou OpenRouter, você fica preso a ~8 mil tokens. Isso não cabe em um projeto inteiro — mal cabe em um único arquivo grande. Um desenvolvedor passou semanas construindo um agente CLI projetado em torno dessa restrição e compartilhou as lições práticas aprendidas.

Arquitetura principal: separação planejador/executor

O agente nunca mostra o projeto inteiro para o LLM. Em vez disso, ele divide o trabalho em três papéis:

• Planejador: vê apenas um mapa leve do projeto (resumos em Markdown de cada pasta, ~300-500 tokens no total) mais a solicitação do usuário, e gera uma lista de tarefas.
• Executor: vê exatamente um arquivo mais uma tarefa por chamada — nunca dois arquivos juntos.
• Orquestrador: código puro (sem LLM) que constrói um grafo de dependência a partir da lista de tarefas e decide quais tarefas podem ser executadas em paralelo versus sequencialmente.

Isso transforma refatorações de múltiplos arquivos de um problema de janela de contexto em um problema de agendamento. O planejador não precisa ver o código, e o executor só vê uma quantidade limitada de código de cada vez.

Orçamento de tokens imposto no código

Toda chamada ao LLM passa por uma verificação canFit() que mede prompt do sistema + tokens de saída reservados + memória + código atual. Se o código não couber, o agente recorre a um índice por linha do arquivo (gerado uma vez para arquivos com mais de ~150 linhas) e puxa apenas a seção relevante.

Cálculo do orçamento para 8192 tokens:

Prompt do sistema + instruções: ~1000
Reservado para resposta: ~2000
Memória de curto prazo (4 entradas): ~360
Disponível para código atual: ~4800 (cerca de 140-190 linhas)

Quando o orçamento está apertado, o contexto da pasta é descartado primeiro, depois a memória, antes de cortar o código atual.

Execução paralela como multiplicador de velocidade

Como cada executor vê apenas um arquivo, edições independentes em vários arquivos são executadas simultaneamente. Uma refatoração de 5 arquivos é concluída aproximadamente no tempo da edição única mais longa. O grafo de dependência (construído em código a partir da lista de tarefas do planejador) decide a ordenação.

Pontos problemáticos e correções

• Sobrescrita de arquivos por solicitações do tipo pergunta: perguntar "quantas linhas X tem?" fazia o executor escrever a resposta dentro do arquivo. Corrigido adicionando um campo action_type: "query" na saída do planejador, roteado por um caminho de código que nunca toca no disco.
• Mapas de projeto desatualizados causando desvios silenciosos: se o usuário mencionava um arquivo renomeado que não estava no mapa, o planejador direcionava silenciosamente para a correspondência mais próxima. Agora o orquestrador valida que os caminhos de arquivo mencionados existem no disco e lança um erro claro se não existirem.
• Cercas de Markdown na saída do executor: modelos menores envolvem código em três crases mesmo quando instruídos a não fazer. Correção: removê-las no pós-processamento, em vez de lutar contra o prompt.
• Custo de tokens de memória: a memória persistente adiciona ~80-90 tokens por entrada. O contexto da pasta é descartado primeiro quando o orçamento está apertado, depois a memória, antes que o código atual seja cortado.

Perguntas em aberto

Se a separação planejador/executor escala para bases de código com mais de 50 arquivos — o grafo de dependência permanece gerenciável, mas o mapa do projeto começa a custar tokens reais. Atualmente descartando o contexto da pasta primeiro, mas edições mais profundas perdem contexto. A implementação é de código aberto se você quiser se aprofundar.