Indexar Tudo ou Ler Tudo? O Dilema de Alimentar Especificações para IA em Desenvolvimento Multi-Repo

As especificações existem. A IA simplesmente não consegue vê-las.

Eu sempre fui o tipo de pessoa que constrói projetos de hobby, fica satisfeito na metade do caminho e nunca realmente termina. Por muito tempo, eu quis mudar isso — construir algo até o fim e realmente entregá-lo. Então, há pouco mais de um ano, comecei a construir pequenas peças no estilo microserviço: se cada peça for pequena, eu realmente posso terminá-la, reutilizá-la depois e não vai consumir meses da minha vida. Pode parecer exagero para um projeto solo, mas para mim foi um truque para "reduzir as coisas a um tamanho que possa ser finalizado".

Então, o desenvolvimento assistido por IA se tornou a norma. Para dar contexto à IA, comecei a escrever documentos de especificação adequados mesmo para projetos pessoais. Até agora, tudo bem.

O problema: com microserviços, meus repositórios são separados. O repositório que tenho aberto no Cursor agora é o Serviço A. A especificação que quero referenciar está no repositório do Serviço B. A especificação existe. Está escrita. A IA simplesmente não consegue vê-la.

"Como eu entrego à IA uma especificação que vive fora do espaço de trabalho que estou atualmente aberto?" Este artigo é um registro de eu virando esse problema repetidamente (e repetidamente) na minha cabeça.

O verdadeiro dilema: duas opções, ambas com um custo

Quando você reduz, há realmente apenas duas opções (provavelmente).

Opção A: Adicione ao espaço de trabalho (indexe tudo)

Use os espaços de trabalho de múltiplas raízes do Cursor e adicione todo o repositório de especificações ao seu espaço de trabalho. Eu realmente tentei isso.

Não foi terrível, mas também não foi exatamente agradável. Arquivos irrelevantes são puxados para o contexto. Arquivos de um repositório no qual eu nem estou trabalhando aparecem na busca. Os sintomas que me lembro: edições caindo em lugares que eu não pedi para mudar e o uso de tokens aumentando. Tudo o que eu queria era ler alguns arquivos de especificação e, em vez disso, eu estava pagando o preço de colocar um repositório inteiro no campo de visão da IA.
(Os modelos de IA continuam melhorando, então talvez isso seja menos um problema hoje.)

Para ser justo, os próprios espaços de trabalho de múltiplas raízes evoluíram. Na sua versão de abril de 2026, o Cursor fez com que uma única sessão de agente pudesse direcionar um espaço de trabalho de múltiplas pastas e fazer alterações entre repositórios (changelog). Para fluxos de trabalho de "corrigir algo entre o frontend e o backend", agora é genuinamente melhor. Mas a estrutura não mudou: cada pasta que você abre se torna parte do índice. Para "eu só quero ler alguns arquivos de especificação", ainda é exagerado.

Opção B: Não adicione — busque sob demanda (leia tudo)

Mantenha o repositório fora do seu espaço de trabalho e faça a IA buscar arquivos quando necessário. Por exemplo, escrevendo os caminhos no seu arquivo de regras.

Se você conhece o caminho do arquivo, isso funciona bem. O problema é o caso de "espera, eu sei que escrevi isso em algum lugar". Como a IA não conhece o caminho, ela tem que ler os arquivos candidatos para encontrá-lo. O que significa carregar o conteúdo completo do arquivo no contexto apenas para executar uma busca. Isso consome muitos tokens.

Então, o dilema é:

Pague em ruído para indexar tudo, ou pague em tokens para ler tudo.

As opções que considerei — e minha falsa suposição

"Se não existe, construa" é um espírito bom, mas se há um ombro de gigante para se apoiar, você deve se apoiar nele. Antes de pular para construir minha própria coisa, eu olhei para soluções existentes.

Ferramentas de documentação auto-hospedadas: Eu descobri que havia ferramentas que permitiam que você executasse uma configuração semelhante ao GitBook localmente com Docker. Mas elas precisavam de personalização para se adequar ao meu fluxo de trabalho, pareciam inflexíveis e não ofereciam a experiência polida das ferramentas pagas. O que me levou ao pensamento clássico: "Se não é tão difícil de construir, talvez eu apenas construa eu mesmo?" (Ah sim, a pessoa que ia construir de qualquer maneira.)

SaaS externo: Serviços de gerenciamento de documentação eram ou chocantemente caros ou muito excessivos para as necessidades de um projeto solo.

Servidor GitHub MCP: Em minhas conversas de pesquisa com uma IA na época, havia uma linha dizendo que "precisa ser executado localmente", e com base nisso eu descartei desde o início. Se eu tiver que executar um contêiner localmente de qualquer maneira, eu pensei, não é diferente da opção auto-hospedada.

— E aqui é onde eu tenho que fazer uma confissão embaraçosa. Essa exclusão foi baseada em uma falsa suposição. O Servidor GitHub MCP tem uma versão hospedada remotamente, e ela se tornou geralmente disponível em setembro de 2025 (GitHub Changelog). O GitHub a hospeda, você autentica uma vez com OAuth, e é isso. Sem Docker, sem gerenciamento de PAT. Eu só aprendi isso enquanto pesquisava para este artigo.

Em outras palavras: se eu tivesse sido um pouco mais cético em relação à pesquisa da IA naquela época e ido às fontes primárias, há uma boa chance de que eu nunca teria começado a construir este produto. Eu sempre digo ao meu sobrinho para não confiar cegamente no que a IA diz, e ainda assim aqui estamos...
A pesquisa da IA pode ser baseada em premissas desatualizadas ou simplesmente erradas — eu reaprendi essa lição apenas depois de construir um produto inteiro em cima disso. Dito isso, ainda acho que foi uma boa experiência (sei como isso soa, mas como explicarei na próxima seção, o que eu construí não acabou sendo inútil também).

O problema que permaneceu: busca que nunca parece exatamente certa

O Servidor GitHub MCP remoto é genuinamente capaz. Ele pode buscar arquivos de repositórios privados sem um clone local. Honestamente, se você conhece o caminho do arquivo, listar seus caminhos de especificação em um arquivo de regras e deixar o GitHub MCP lê-los resolve a maior parte do meu caso de uso, de graça.

E quanto à busca, então? Acontece que isso também funciona. O Servidor GitHub MCP tem uma ferramenta de busca de código, e a busca de código do GitHub indexa os repositórios privados aos quais você tem acesso (documentação oficial). Se eu escrevesse "você não pode fazer busca entre repositórios com GitHub MCP", isso seria simplesmente falso.

Mas quando eu mapeio isso para o uso diário de "onde eu escrevi aquela parte da especificação novamente?", algumas coisas ficam complicadas. Todas essas são comportamentos documentados (documentação oficial):

• Apenas a branch padrão é pesquisada, e apenas arquivos com menos de 384 KB. As especificações geralmente se encaixam, mas se você mantiver variantes de especificações em diferentes branches, essas estão fora do escopo.
• A API de busca de código é limitada a 10 solicitações por minuto, mesmo autenticadas. Esse é um bucket separado, muito mais restrito do que a API regular (5.000/hora). Agentes de IA adoram disparar consultas de busca em loops de tentativa e erro, então você sente esse limite rapidamente.
• Os resultados da busca são principalmente metadados de arquivo. (A API pode devolver pequenos fragmentos em destaque se você pedir, mas é só isso.) Para realmente ler o conteúdo, você precisa de uma busca de acompanhamento. Portanto, é um mínimo de duas idas e voltas: busca, depois busca.

Nenhuma dessas é "não funciona." Elas são todas "nunca parece exatamente certa para uso diário." Mas "eu sei que escrevi isso em algum lugar" acontece várias vezes ao dia. Eu realmente quero pisar nessa fricção toda vez?

Minha resposta foi delegar a busca a um motor de busca (de certa forma). Colocar o conteúdo das especificações no PostgreSQL e fazer a busca em uma única consulta de banco de dados (eventualmente busca vetorial também). Retornar à IA apenas um trecho: as linhas correspondentes mais algumas linhas de contexto. Sem limites de taxa punitivos, sem idas e vindas extras, e a única coisa que cai no contexto da IA é o fragmento que ela realmente precisa. Eu ainda estou em desenvolvimento, então é cedo demais para fazer grandes afirmações sobre os resultados — mas, no mínimo, o "onde eu escrevi isso agora"