Crie uma ferramenta local de grafo de código que agentes de IA possam consultar

## Monte o grafo de código localmente a partir da árvore de sintaxe, não de resumos de IA Mantenha a análise do projeto local e determinística. Extraia símbolos, relações e arquivos de árvores sintáticas, e não de resumos de modelos de linguagem, armazene o estado específico do projeto em um banco de dados local indexado e disponibilize o grafo de conhecimento resultante por meio de uma biblioteca, uma interface de linha de comando ou um protocolo de agentes. Organize o sistema como um encadeamento em camadas: - a extração analisa o código-fonte e emite símbolos canônicos; - a resolução conecta importações, nomes, frameworks e outras relações; - as consultas ao grafo respondem sobre chamadores, chamados, caminhos e impacto; - a formatação de contexto prepara Markdown ou JSON compacto para os sistemas consumidores. Mantenha a análise pesada fora da linha de execução principal. Encaminhe as camadas por um único ponto de entrada público e faça dele a única interface de biblioteca compatível. Se um executável servir intencionalmente como instalador, indexador e servidor de protocolo, teste todas as funções usando esse mesmo artefato. Mantenha uma única fonte normativa para as orientações das ferramentas destinadas aos agentes, de preferência a resposta de inicialização do protocolo. Não duplique as mesmas instruções no arquivo de repositório de cada cliente, pois as cópias divergem e tornam incompletas as atualizações ou a desinstalação. ## Fixe a versão do ambiente de execução e inclua no build os arquivos que não são código Identifique e use os comandos documentados do repositório para compilação, desenvolvimento, limpeza, testes, avaliação e CLI local. Respeite o intervalo fixado do ambiente de execução e produza uma falha clara fora dele; uma versão principal mais recente não é automaticamente compatível, e a execução a partir do código-fonte pode exigir uma versão mínima mais rigorosa do que uma distribuição empacotada. Trate os recursos usados durante a execução como parte do contrato de compilação. Copie esquemas de banco de dados, gramáticas de analisadores, módulos WebAssembly e outros arquivos que não contêm código para a distribuição. Sempre que um novo recurso for adicionado, atualize a etapa de cópia, ou ele não será distribuído. Comece a verificação com um arquivo de teste específico ou um padrão de nome e, em seguida, execute o conjunto diretamente afetado. Mantenha os conjuntos de avaliação separados quando eles criarem estruturas de teste ou pontuarem o comportamento, em vez de executarem testes unitários comuns. Use o comportamento real do armazenamento quando sua semântica for relevante. Crie diretórios temporários isolados, limpe-os após cada teste e verifique o modo real do banco de dados, em vez de ocultá-lo com simulações. ## Unifique os tipos de nós e arestas e mantenha a API pública pequena Defina tipos canônicos de nós e arestas em um único esquema. Extratores e resolvedores devem emitir exatamente essas cadeias de caracteres; não introduza variantes quase idênticas que dividam silenciosamente consultas, percursos ou dados serializados. Mantenha a API pública restrita. Reexporte os tipos compatíveis pelo ponto de entrada público e exija que os adaptadores de linha de comando e de protocolo acionem o mesmo serviço central, em vez de contorná-lo. Torne as afirmações sobre armazenamento explícitas e verificáveis. Se o produto tiver um único mecanismo de banco de dados compatível com registro antecipado de escrita e pesquisa de texto completo, informe esse mecanismo realmente ativo, mantenha qualquer adaptador de compatibilidade enxuto e não sugira a existência de uma alternativa nativa ou WebAssembly que não tenha sido implementada. Ao adicionar uma linguagem, um framework, uma consulta ou um campo de esquema, atualize em conjunto o extrator ou resolvedor responsável, o contrato público, a serialização, os testes e as orientações destinadas aos usuários. ## Instale em vários clientes de IA sem quebrar as configurações e desinstale sem deixar resíduos Modele cada cliente compatível como um destino com seu próprio local de configuração, formato e argumentos de protocolo. Adicione um novo cliente por meio de uma implementação de destino e uma entrada no registro, em vez de espalhar condições pelo instalador. Edite a configuração com precisão. Preserve tabelas e listas TOML não relacionadas, mantenha a formatação e os comentários de JSON com comentários, prefira uma variante de arquivo compatível já existente e crie o padrão documentado somente em uma nova instalação. A instalação deve ser idempotente, a reinstalação deve reparar automaticamente um estado parcial e a desinstalação deve reverter somente as alterações pertencentes ao instalador. Use marcadores estáveis para remover blocos de instruções obsoletos, mas mantenha as orientações atuais para agentes em sua única fonte durante a execução, em vez de gravar outra cópia. Cubra cada destino com testes de contrato parametrizados para preservação de configurações adjacentes, repetições idênticas byte a byte, desinstalação reversível e recuperação de estado parcial. Preserve correções do diretório de trabalho específicas de cada cliente, como a inserção de um caminho explícito do projeto quando o cliente inicia subprocessos do protocolo no diretório errado. ## Melhore as ferramentas de busca que os agentes já usam Antes de criar uma funcionalidade de recuperação, pergunte se ela permite que uma ferramenta já chamada pelo agente faça mais com as informações que ele já fornece. Não dependa de o agente aprender uma nova ferramenta, adotar um estilo de consulta diferente ou notar exemplos e textos de inicialização pouco visíveis. Use entradas precisas para obter respostas precisas. Uma ferramenta principal de exploração deve aceitar um conjunto compacto de nomes de símbolos, inclusive nomes qualificados, e conectar o fluxo entre eles. Uma ferramenta secundária de nós deve retornar o código-fonte completo, além do contexto de chamadores e chamados; quando um nome for ambíguo, deve retornar todas as sobrecargas plausíveis em uma única resposta. Não incorpore respostas precisas sobre fluxos a uma ferramenta imprecisa de linguagem natural que não consiga distinguir os pontos finais. Melhore a cobertura dentro das ferramentas que os agentes já escolhem, incluindo extração estática e relações dinâmicas baseadas em evidências. Otimize tanto a latência real e a quantidade de chamadas de ferramentas quanto o uso de tokens. Meça o uso total em todos os turnos, e não apenas na resposta final, pois a economia vem de menos turnos sobre um contexto acumulado menor. ## Retorne respostas que evitem que o agente volte a ler arquivos diretamente Apresente condições esperadas em formato de sucesso. Um projeto não indexado, um símbolo ausente ou um arquivo fora do índice deve retornar orientações práticas sem um indicador de erro. Reserve erros verdadeiros para recusas de segurança e falhas reais e acrescente uma instrução limitada de nova tentativa somente quando ela for apropriada. Disponibilize a interface de ferramentas mesmo quando a raiz atual não estiver indexada. Explique como selecionar um projeto indexado, mas deixe a indexação como decisão do usuário. Ocultar ferramentas na inicialização pode prejudicar monorrepositórios e sessões iniciadas antes da indexação. Aumente monotonicamente tanto os limites de chamadas de exploração quanto os limites de saída conforme o tamanho do repositório: - menos de 500 arquivos: 1 chamada, cerca de 18.000 caracteres e 3.800 caracteres por arquivo; - 500–4.999 arquivos: 2 chamadas, cerca de 28.000 caracteres e 6.500 caracteres por arquivo; - 5.000–14.999 arquivos: 3 chamadas, cerca de 35.000 caracteres e 7.000 caracteres por arquivo; - 15.000–24.999 arquivos: 4 chamadas, cerca de 38.000 caracteres e 7.000 caracteres por arquivo; - 25.000 arquivos ou mais: no máximo 5 chamadas, cerca de 38.000 caracteres e 7.000 caracteres por arquivo. Uma faixa maior nunca deve receber um limite por arquivo menor do que uma faixa menor. Nunca diga ao agente para voltar à leitura direta de arquivos; encaminhe-o para outra chamada ao grafo e declare que o código-fonte retornado deve ser tratado como já lido. ## Conecte do início ao fim os fluxos de callbacks e eventos A análise estática não detecta funções de retorno de chamada, observadores, emissores de eventos, renderização reativa, descritores e outros encaminhamentos indiretos. Adicione sintetizadores de escopo restrito ou resolvedores de frameworks somente quando eles puderem conectar o fluxo canônico com evidências defensáveis. Marque cada aresta sintetizada como heurística, registre o mecanismo que a produziu e inclua o local de registro ou conexão. Exiba essa proveniência junto ao fluxo, para que os consumidores possam distinguir fatos analisados de relações inferidas. A cobertura parcial é pior do que nenhuma quando expõe uma transição indireta, mas deixa interrompido o limite seguinte. Feche o fluxo desde a ação que o inicia até seu efeito visível, meça novamente o agente e não distribua um caminho ligado apenas pela metade que ainda obrigue a reconstrução manual. Nos limites do ambiente de execução que não possam ser inferidos com segurança, prefira o silêncio a uma aresta incorreta. Verifique se a reindexação não aumenta indevidamente a quantidade de nós e faça verificações por amostragem da precisão das arestas sintetizadas antes de ampliar um resolvedor. ## Teste o comportamento do agente em repositórios reais, no Windows e no Linux Para cada linguagem e framework, teste repositórios reais pequenos, médios e grandes com pelo menos 3 perguntas distintas sobre fluxos. Escolha um fluxo canônico integral para cada framework, em vez de símbolos isolados que evitem seus limites difíceis de encaminhamento. Execute verificações determinísticas no artefato compilado. Confirme que a exploração conecta os pontos finais esperados dentro do limite, que a quantidade de nós permanece estável entre reindexações e que as arestas heurísticas carregam uma proveniência precisa. Execute testes A/B com agentes pelo menos 2 vezes em cada braço experimental, usando o mesmo modelo mínimo escolhido deliberadamente e o mesmo esforço de raciocínio. Registre a duração, o total de chamadas de ferramentas, as leituras diretas de arquivos e as pesquisas de texto; informe intervalos, e não uma única execução favorável. Pré-aqueça um processo de protocolo persistente quando a latência de inicialização puder ocultar a ferramenta e avalie a conexão pelas chamadas reais, e não por um retrato da inicialização. Exija aproximadamente zero leituras diretas e pesquisas dentro do limite de exploração do repositório, conclusão mais rápida do que a do grupo de controle e nenhuma regressão em um repositório de controle. Valide o comportamento específico de cada plataforma na plataforma real. Separe explicitamente as afirmações válidas apenas para Windows das válidas fora do Windows. No Linux, compile com dependências nativas da plataforma recém-instaladas em um contêiner descartável e use um processo init para que os processos filhos encerrados sejam recolhidos. No Windows, use um sistema de arquivos local e dependências recém-instaladas em uma máquina virtual real; compare falhas suspeitas com o ramo padrão antes de atribuir a causa. ## Escreva as notas de versão e deixe a publicação para o fluxo automático de release Registre as próximas alterações em uma seção Unreleased. Não crie antecipadamente o próximo bloco de versão quando o fluxo de publicação promover automaticamente o conteúdo de Unreleased. Torne as notas de publicação úteis para os usuários: - agrupe o conteúdo sob títulos voltados aos usuários para funcionalidades, correções, segurança ou mudanças incompatíveis somente quando se aplicarem; - escreva uma frase em linguagem simples por item, explicando a funcionalidade ou o problema resolvido; - omita caminhos internos, símbolos de implementação, detalhes de medições de desempenho e seções vazias; - preserve referências úteis a ocorrências, nomes de plataformas compatíveis e comandos que os usuários realmente digitam. Permita que o fluxo automatizado de publicação sincronize as versões do arquivo de bloqueio, promova o registro de alterações, compile os pacotes de plataforma, gere somas de verificação, publique a versão e publique os pacotes. Não aumente versões sem solicitação explícita e não publique pacotes manualmente, não envie consolidações de publicação nem crie etiquetas quando essas ações pertencerem ao fluxo. Antes de agir sobre uma ocorrência, um comentário de revisão ou um relatório externo, associe-o a uma data e compare o estado publicado, o estado integrado mas ainda não publicado e o ramo atual. Não atribua uma correção em andamento ao que o autor do relato podia ver anteriormente. Trate os requisitos do produto como decisões dos usuários, e não como fatos inferidos do grafo de código. Atribua uma versão a cada URL de imagem da documentação e incremente seu identificador de consulta sempre que o recurso for alterado, para que os caches não continuem fornecendo bytes desatualizados.