Seu agente está gastando mais tempo encontrando código do que entendendo

Eu continuei observando agentes fazendo a mesma coisa. Dada uma tarefa real em uma base de código real, eles passavam a primeira metade da sessão navegando — greppando, abrindo arquivos, lendo imports, voltando, greppando novamente — e só depois disso chegavam à parte em que realmente são bons: raciocinar, planejar, escrever código.

A janela de contexto não é infinita. Cada token gasto localizando um arquivo é um token não gasto pensando sobre ele.

Então eu construí coldstart. É um servidor MCP que fornece aos agentes um índice estático sobre uma base de código — caminhos de arquivos, nomes de símbolos exportados, segmentos de caminho — construído uma vez com Tree-sitter, consultado instantaneamente. Quatro ferramentas, sem embeddings, sem banco de dados vetorial, sem modelo. O objetivo principal é encontrar o arquivo certo rapidamente e sair do caminho do agente.

Este é um post sobre por que ele acabou sendo tão pequeno, o que eu deliberadamente não construí e o que aprendi com os agentes usando-o em bases de código reais.

O problema não é inteligência, é navegação

Os agentes são mais valiosos quando estão raciocinando sobre o código, não o procurando. Mas a navegação é onde eles silenciosamente queimam contexto. Uma sessão típica em uma grande base de código se parece com:

• Grep para uma palavra-chave provável. Obter 200 linhas de correspondências.
• Abrir três ou quatro arquivos para descobrir qual é realmente relevante.
• Perceber que o arquivo certo tem um nome diferente e grepar novamente.
• Rastrear imports manualmente.
• Finalmente começar a tarefa real — com significativamente menos janela de contexto restante. Janelas de contexto maiores não consertam isso; elas apenas atrasam. Um agente que desperdiça tokens navegando tem menos restante para o trabalho que importa. O custo não é teórico — ele se manifesta como respostas piores perto do final de longas sessões, mais releituras de arquivos que o agente já viu e tarefas que são abandonadas no meio do caminho porque não há espaço suficiente para terminar.

A estrutura que eu cheguei: a janela de contexto é finita independentemente do preço. Um agente que navega de forma eficiente permanece em sua zona de melhor valor por mais tempo.

O que coldstart realmente é

Direto do README:

coldstart é uma camada de navegação leve para agentes de IA. Ele responde a uma pergunta: quais arquivos são relevantes para esta tarefa? Sem embeddings, sem grafo, sem modelo para executar ou manter. Apenas um índice rápido e estático sobre sua base de código — caminhos de arquivos, nomes de símbolos, exportações — construído uma vez, consultado instantaneamente. Os agentes já são bons em ler código, rastrear lógica e raciocinar sobre estrutura. O que eles não precisam é de outro sistema tentando fazer isso por eles. coldstart fica fora do caminho: encontre o arquivo, passe-o adiante, pronto. 4 ferramentas. Sobrecarga de contexto mínima. Sem infraestrutura para cuidar.

O modelo mental é "grep mais inteligente". Grep corresponde a strings; coldstart corresponde a strings e sabe quais são símbolos exportados, quais são segmentos de caminho e quais são raros o suficiente para serem sinais significativos. Uma vez que ele aponta o agente para o arquivo certo, o agente faz o resto. Essa é a ferramenta inteira.

O que eu deliberadamente não construí

A maior parte do esforço de design foi direcionada a coisas que eu escolhi não adicionar. Cada uma era tentadora e cada uma teria tornado a ferramenta pior para o que os agentes realmente precisam.

Sem recomendações ou sugestões de próximos passos. Esse é o trabalho do agente. Uma ferramenta de navegação que tenta também ser uma ferramenta de raciocínio acaba fazendo ambas as coisas mal, e pior, ancla o agente em qualquer heurística que a ferramenta usou. Eu prefiro devolver uma lista limpa de arquivos e deixar o agente decidir.

Sem busca semântica ou embeddings. Embeddings adicionam um modo de falha inteiro — versionamento de modelo, reconstruções de índice quando o modelo de embedding muda, custo, latência, dependência de um serviço hospedado ou de um arquivo de modelo enviado — sem ganho proporcional para navegação. Para encontrar arquivos por nome de símbolo, a recuperação lexical é mais rápida, mais previsível e mais fácil de depurar. (Para consultas conceituais — "onde está a lógica de retry" — embeddings realmente ajudam. coldstart não está tentando ser essa ferramenta.)

Sem filtros de prefixo de caminho ou filtros de tipo de arquivo. Esse é o trabalho do grep. O valor do coldstart é o que o grep não pode fazer: encontrar arquivos por nomes de símbolos exportados e sinais estruturais. Se você precisa de um glob, você já tem um.

A classificação é fixa. Eu passei por muitas iterações na classificação — penalidades, filtros de correspondência exata, limites de comprimento, ponderação IDF — e o que foi enviado é o que se manteve em consultas reais em bases de código reais. Eu terminei de ajustar isso. Se eu continuar ajustando, estou apenas superajustando a qualquer coisa que testei na semana passada.

O padrão em todas as quatro: cada recurso que eu não adicionei foi um que teria tornado o coldstart maior sem torná-lo mais útil para o trabalho específico de "encontrar o arquivo rapidamente e desaparecer".

O que eu aprendi com execuções reais de agentes

Duas coisas se destacaram uma vez que eu assisti os agentes realmente usarem isso.

Falhas suaves são recuperáveis; falhas duras não são. Quando o coldstart retorna muitos resultados, o agente restringe a consulta e tenta novamente — isso é uma falha suave, e os agentes lidam bem com isso. O que mata um agente é uma ferramenta que retorna zero resultados sem sinal, ou uma resposta errada confiante. O coldstart é projetado para que seu modo de falha seja "demais" em vez de "nada" — os agentes sempre podem trabalhar com demais.

Os scores de confiança são decoração a menos que signifiquem algo. Eu tentei adicionar scores de confiança no início. Eles eram sem sentido — cada resultado voltava com mais ou menos o mesmo número — e o agente se ancorava demais neles. Eu os removi. Se um score não diferencia resultados, é apenas ruído que o agente tem que interpretar.

Há um benchmark mais detalhado vindo, comparando o coldstart a uma abordagem de análise de base de código baseada em grafo em consultas reais. Eu quero fazer isso corretamente com números em vez de vibrações, então está recebendo seu próprio post.

As limitações honestas

Algumas coisas que o coldstart não faz bem, caso você esteja avaliando:

• A resolução de chamadas entre arquivos é parcial. Chamadas de funções nomeadas entre arquivos são resolvidas. Chamadas de expressão de membro (this.foo(), obj.foo()) não são. Esta é uma limitação do Tree-sitter que eu ainda não resolvi completamente.
• É lexical, não semântico. Se você perguntar "onde lidamos com autenticação" e nenhum arquivo tiver a palavra "auth" em seu caminho ou exportações, o coldstart não encontrará. Use-o para consultas em forma de símbolo, não em forma de conceito.
• Dez linguagens analisadas para símbolos. TypeScript, JavaScript, Java, Ruby, Python, Go, Rust, C#, PHP, Kotlin. Arquivos Swift, Dart e C++ são percorridos e indexados por caminho — então os agentes ainda podem encontrá-los — mas símbolos, imports e bordas de chamada ainda não são extraídos, então trace-deps e trace-impact param nessas fronteiras. Adicionar análise completa é uma configuração de gramática do Tree-sitter por linguagem.

npm install -g coldstart-mcp

GitHub: github.com/AkashGoenka/coldstart
npm: npmjs.com/package/coldstart-mcp

Se você quiser a versão longa de como o design chegou aqui — as iterações de classificação falhadas, as decisões do AST, o que quebrou e o que se manteve — há um post aprofundado cobrindo isso.