Desenvolvedor passou um mês observando agentes no próprio código: árvore de arquivos custa mais que JSON

Há um ano, o autor do texto no Habr copiava os arquivos para a janela do chat um por um. Hoje, os agentes leem o projeto dele sozinhos por meio de um servidor MCP, e ele passou um mês observando o que exatamente eles colocam no contexto. As conclusões são práticas. A árvore de arquivos em texto custa mais que JSON, a pasta build não pode ser excluída pelo nome, é possível esconder senhas de um jeito que o código deixe de funcionar, e o agente sem supervisão administra o contexto de forma bem mais perdulária do que se espera.

O artigo original está disponível apenas como anúncio, por isso abaixo analisamos as teses declaradas e a lógica de engenharia por trás delas. As medições exatas do autor devem ser consultadas na fonte original.

Por que a árvore custa mais que JSON

Intuitivamente, parece o contrário. A árvore com indentação e caracteres gráficos é fácil de ler a olho nu, enquanto o JSON, com aspas, chaves e campos repetidos, parece redundante. Mas o modelo conta tokens, não caracteres. Os símbolos especiais de ramificação, as longas sequências de espaços e os prefixos de caminho repetidos são tokenizados de forma ineficiente. Essa é a nossa suposição sobre o mecanismo; o autor pode ter explicado de outra maneira. A conclusão em si vale ser testada no seu próprio repositório: em um projeto grande, a diferença de custo cresce junto com o número de arquivos.

O MCP tem um papel especial aqui. O protocolo transforma a leitura do projeto em um conjunto de chamadas de ferramentas: listar arquivos, ler conteúdo, buscar. O formato da resposta de cada chamada entra inteiro no contexto, e cada requisição do agente paga esse preço.

Pasta build e senhas

A segunda lição diz respeito à filtragem. A regra "ignorar pastas chamadas build" parece razoável até surgir no projeto um diretório com o mesmo nome que guarda código-fonte, e não artefatos de compilação. É mais seguro observar o que a pasta faz: se ela está no .gitignore, se é gerada pela compilação, há quanto tempo foi modificada.

Com os segredos, a situação é mais complicada. Se você simplesmente remover a linha com a senha, a configuração deixa de ser interpretada, e o agente passa a consertar o que ele mesmo quebrou. A solução que funciona é outra: colocar um valor substituto no lugar, preservando a estrutura do arquivo, a chave e o tipo de dado. Assim o código continua legível, e o segredo real fica fora do contexto.

Agente sem supervisão

O ponto mais curioso, que o autor descreve de forma breve, é o que o agente faz com o contexto quando ninguém o acompanha. Os sintomas típicos são conhecidos de quem já rodou sessões longas: releitura dos mesmos arquivos, carregamento de diretórios desnecessários, janela inflada por resultados antigos de ferramentas. Cada um desses passos custa tokens e piora a qualidade das respostas, porque o sinal útil se perde no ruído.

• Formato de descrição do projeto: a árvore em texto custa mais que JSON.
• Filtros: o nome da pasta não serve como critério único.
• Segredos: mascarar os valores em vez de apagar linhas.
• Transporte: o servidor MCP como ponto único de controle sobre o que o agente vê.
• Risco: crescimento descontrolado do contexto em sessões longas.

Por onde começar a verificar o seu projeto

Primeiro, veja o que realmente vai para o contexto. Se o seu servidor MCP ou a camada de orquestração do agente não registra o volume das respostas, adicione um contador de tokens a cada chamada. Sem ele, não há o que otimizar.

Depois, compare os formatos. Rode o mesmo repositório como árvore e como JSON compacto e compare o número de tokens. Em seguida, revise as regras de exclusão: baseie-se no .gitignore e em sinais de arquivos gerados, e não em uma lista de nomes.

Por fim, aplique a mascaragem de segredos antes de enviar os dados ao agente, e não depois. Verifique se a configuração mascarada continua passando pelo parser. E defina um orçamento para o agente: um limite para o tamanho do contexto e para o número de releituras do mesmo arquivo. Assim, um mês de observação vira um conjunto de regras, e não uma surpresa isolada.