Governança de indexação do Cursor em projetos grandes: do diagnóstico à reconstrução

Na semana passada, ajudei uma equipe a fazer uma auditoria de engenharia no Cursor. O Monorepo deles tinha mais de 200 pacotes. Toda vez que o projeto era aberto, a dica ao passar o cursor levava 4 segundos para aparecer, e o autocompletar respondia em média em 6 segundos: você digitava uma linha de código, tomava um gole de café e esperava ele terminar de pensar. A equipe passou dois dias tentando de tudo: upgrade de hardware, troca de modelo, reinstalação do Cursor. No fim, o problema não estava no modelo nem na rede. O Cursor simplesmente tratava toda a árvore packages/ como contexto por padrão. Este guia traz um fluxo de diagnóstico, modelos de configuração e um plano de reconstrução para deixar o Cursor fluido de novo em 10 minutos.

Como a indexação do Cursor funciona: entenda em 5 minutos por que ela fica lenta

A Merkle Tree é a peça principal nos bastidores. O Cursor usa essa estrutura para rastrear mudanças em arquivos: cada arquivo recebe um hash, cada pasta recebe outro hash com base nos hashes dos arquivos dentro dela, e assim por diante até chegar a um hash raiz. Alterou um arquivo? O hash dele muda, o hash da pasta onde ele está também muda, e essa alteração sobe até o nó raiz. Com isso, o Cursor só precisa reindexar os arquivos alterados, não o repositório inteiro.

O problema aparece logo depois. Seu node_modules pode ter 50.000 arquivos. Cada um entra no cálculo de hash, e só esses dados de hash já podem chegar a 3,2 MB. Pior: o Cursor ainda calcula embeddings para esses arquivos. O código dentro dos pacotes npm não tem quase nada a ver com a lógica de negócio que você está escrevendo, mas o indexador não sabe disso. Ele coloca tudo no contexto, com disciplina demais e critério de menos.

Segundo dados do blog oficial do Cursor, uma consulta inicial em um repositório grande no 99º percentil leva 4,03 horas. Mas trabalho em equipe tem uma vantagem escondida: em clones do mesmo repositório, em média 92% dos arquivos são semelhantes. O Cursor reutiliza esses dados de índice e reduz a primeira consulta para 21 segundos. Se o seu índice está limpo, quando alguém da equipe abre o projeto pode aproveitar diretamente o cache que você já calculou.

Em uma frase: a indexação fica lenta não porque o Cursor calcula devagar, mas porque ele indexa coisas demais, e muitas delas nem deveriam estar no índice.

Fluxo de diagnóstico: 3 passos para encontrar o verdadeiro culpado

Não mude a configuração na pressa. Primeiro diagnostique.

Passo 1: veja o estado da indexação. Abra o projeto e observe o pequeno ícone no canto inferior direito da barra de status. Se ele fica mostrando “Indexing…” o tempo todo, ou se a barra de progresso trava em alguma porcentagem, há um problema de indexação. Pressione Cmd+Shift+P (no Windows, use Ctrl+Shift+P), digite “Show Cursor Logs” e vá até as últimas linhas do log. Você verá algo como “Indexing 1,342 files…”. Passou de 5000? Esse provavelmente é o foco do problema.

Passo 2: liste as pastas suspeitas. Abra o terminal na raiz do projeto e rode find . -type d -name "node_modules" -o -name "dist" -o -name "build" -o -name ".git" | wc -l. Estes são os assassinos de indexação mais comuns:

Vultr - Servidor cloud NVMe de alto desempenho, 32 locais globais, deploy Docker com um clique

Ver preços →Anúncio

Passo 3: fique de olho em CPU e memória. Abra o Activity Monitor no macOS ou o Task Manager no Windows e observe o processo do Cursor. CPU acima de 80% e memória acima de 4 GB? Isso é a indexação calculando hashes e embeddings sem parar.

A árvore de decisão abaixo ajuda a localizar o problema rapidamente:

Segundo o Troubleshooting Guide da Zest, 90% dos problemas de instabilidade no Cursor vêm de conflito entre extensões e configuração de indexação inadequada. Na maioria dos casos, você está no segundo grupo.

Configuração de .cursorignore: 3 modelos para cenários comuns

A sintaxe de .cursorignore é exatamente igual à de .gitignore. Coloque o arquivo na raiz do projeto. Quando o Cursor lê esse arquivo, ele deixa de indexar o conteúdo listado ali.

Modelo 1: projeto JavaScript/TypeScript

# Pacotes de dependência
node_modules/
.npm/
.yarn/

# Artefatos de build
dist/
build/
out/
.next/
.nuxt/

# Testes e cobertura
coverage/
.nyc_output/

# Logs e arquivos temporários
*.log
*.tmp
.DS_Store

Se o seu projeto usa Monorepo, como um pnpm workspace, dá para indexar por etapas: primeiro excluir todos os pacotes, depois liberar só aquele em que você está trabalhando.

# Indexação em etapas no Monorepo
packages/*/
!packages/api/        # Pacote em desenvolvimento no momento, liberado
!packages/shared/     # Biblioteca compartilhada, talvez necessária
node_modules/
dist/

Modelo 2: projeto Python

# Ambiente virtual
venv/
.venv/
env/
.env/

# Cache de compilação
__pycache__/
*.pyc
*.pyo
.pytest_cache/

# Artefatos de empacotamento
*.egg-info/
build/
dist/

# Jupyter Notebook
.ipynb_checkpoints/

Ambientes virtuais de Python costumam ter milhares de arquivos, e a maior parte deles é código-fonte de bibliotecas de terceiros. Depois de excluir venv/, o tamanho do índice pode cair 90%.

Modelo 3: projeto Go

# Cache de dependências
vendor/

# Artefatos de build
bin/
*.exe
*.exe~
*.dll
*.so
*.dylib

# Cache de testes
*.test
*.out
coverage.txt

O diretório vendor/ em Go é parecido com node_modules/: facilmente reúne milhares de arquivos de dependências.

Comparação de efeito: dados do Developer Toolkit mostram que a configuração padrão de indexação, sem .cursorignore, tem apenas 65% de precisão de contexto, porque há ruído demais. Com regras de exclusão adequadas, essa precisão chega a 98%. Resumindo: excluir 20% dos arquivos pode render um ganho de 50% na precisão.

Configuração de workspace para Monorepos

Se o seu Monorepo tem dezenas de serviços e toda abertura exige esperar a indexação terminar, considere usar um arquivo .code-workspace para carregar apenas os pacotes que você vai alterar agora.

Crie um arquivo workspace.code-workspace na raiz do projeto:

KiloClaw - OpenClaw gerenciado para empresas: orquestração de agentes IA e roteamento inteligente

Começar →Anúncio

{
  "folders": [
    {"name": "payments", "path": "./services/payments"},
    {"name": "shared-libs", "path": "./libs"}
  ],
  "settings": {
    "cursor.indexing.maxFileSize": 512000,
    "cursor.chat.scopeSelection": "activeFolder"
  }
}

Depois abra esse arquivo no Cursor, em vez de abrir o repositório inteiro. A barra lateral mostrará apenas as pastas payments e shared-libs; os outros serviços ficam completamente fora da visão. A indexação roda só nesses dois diretórios, e a velocidade pode melhorar 10 vezes.

Explicação das configurações principais:

• maxFileSize: 512000: arquivos acima de 512 KB não são indexados, evitando que JSON/CSV grandes estourem o contexto
• scopeSelection: "activeFolder": no modo Agent, o contexto vem apenas da pasta ativa, sem busca entre pacotes

Essa configuração é especialmente útil para Monorepos grandes. O artigo de iamraghuveer menciona projetos com 10 serviços e 5000 arquivos em cada um, nos quais os dados de indexação podem ocupar de 1 a 5 GB. Se tudo for carregado, CPU e memória sofrem. Ao carregar só o pacote de trabalho atual, o índice pode cair para cerca de 50 MB.

Quando usar configuração de workspace?

• O Monorepo tem mais de 20 pacotes, e cada pacote é relativamente independente
• Você desenvolve dentro de um pacote específico e não precisa referenciar outros pacotes o tempo todo
• A divisão da equipe é clara, com cada pessoa responsável por serviços diferentes

Se as dependências entre pacotes são muito fortes, por exemplo em microserviços que chamam bibliotecas compartilhadas o tempo todo, .cursorignore costuma ser mais estável: você exclui o que não precisa, mantém o que precisa e evita alternar entre arquivos de workspace.

Limpeza de cache e reconstrução do índice: de travado a fluido

Às vezes a configuração muda, mas a indexação continua estranha. Pode haver dados antigos de hash no cache. Nesse caso, é hora de limpar.

Limpeza rápida, tente primeiro

Pressione Cmd+Shift+P, digite “Reindex Codebase” e selecione a opção. O Cursor fará uma nova varredura do projeto e reconstruirá o índice. O processo costuma levar algumas dezenas de segundos; em projetos grandes, talvez 2 a 3 minutos. Quando terminar, o progresso de indexação na barra de status vai de 0% a 100%. Dá para esperar com calma.

Limpeza profunda, se a limpeza rápida não funcionar

Apague o diretório de configuração do Cursor. Os caminhos variam por sistema:

Feche o Cursor, encontre o diretório acima e apague-o, ou mova para outro lugar como backup. Ao abrir o Cursor de novo, ele inicializa a configuração e a indexação do zero.

Atenção: apagar o diretório de configuração também remove suas configurações personalizadas, como settings.json, atalhos de teclado e configuração de extensões. Antes disso, faça backup do arquivo User/settings.json.

Alibaba Cloud - Escolha dos desenvolvedores, 15% de desconto exclusivo em Lighthouse

Ganhar 15% off →Anúncio

Passos para uma redefinição completa

1. Feche o Cursor
2. Faça backup de ~/Library/Application Support/Cursor/User/settings.json, se existir
3. Apague todo o diretório de configuração
4. Reinicie o Cursor
5. Espere ele reindexar o projeto, o que pode levar alguns minutos
6. Copie o settings.json de volta para restaurar suas configurações personalizadas

Segundo o Troubleshooting Guide da Zest, o fluxo reiniciar, limpar cache e verificar estado resolve 80% dos problemas de indexação em até 5 minutos. Na maioria dos casos, a limpeza rápida basta. A limpeza profunda só deve entrar quando você já alterou .cursorignore e a indexação continua anormal.

Quando reconstruir o índice?

• A barra de status fica mostrando “Indexing…” por mais de 10 minutos sem avançar
• O autocompletar sai dos 1 a 2 segundos normais para mais de 5 segundos, e isso dura vários dias
• Você alterou .cursorignore, mas os resultados de @Codebase ainda incluem arquivos excluídos

Conclusão

A principal causa da indexação lenta no Cursor é simples: arquivos demais, muitos deles sem motivo para entrar no índice. O caminho de correção também é direto: diagnosticar, excluir, reconstruir.

Checklist de ação:

1. Abra seu projeto grande, pressione Cmd+Shift+P, digite “Show Cursor Logs” e veja a quantidade de arquivos indexados
2. Se passar de 5000 arquivos, crie imediatamente um .cursorignore usando os modelos deste artigo
3. Exclua diretórios de artefatos gerados, como node_modules/, dist/ e .git/
4. Execute “Reindex Codebase” e espere a indexação terminar
5. Se ainda estiver lento, verifique CPU e memória e considere usar .code-workspace para carregar apenas o pacote em trabalho

Sugestões de manutenção de longo prazo:

• Sempre que adicionar novas dependências ou configurações de build, verifique se .cursorignore precisa ser atualizado
• Em projetos de equipe, inclua .cursorignore na raiz do repositório para garantir uma configuração consistente para todos
• Em Monorepos grandes, limpe periodicamente o índice de serviços antigos e mantenha apenas os pacotes em desenvolvimento ativo

Teste agora. Em 10 minutos, você deve sentir o Cursor voltar ao normal: autocompletar em 1 a 2 segundos, busca @Codebase sem travar e dicas ao passar o cursor aparecendo quase na hora. Sua eficiência de desenvolvimento volta junto.

Referências

Fontes dos dados citados neste artigo:

• Indexação segura de grandes bases de código - Cursor - blog oficial do Cursor, 2026-01-27
• Otimização de desempenho para Cursor - Developer Toolkit - blog técnico, 2026-05-28
• Indexação de codebase do Cursor para workspaces multi-repo - iamraghuveer - blog pessoal, 2026-04-25
• Guia prático de troubleshooting do Cursor - Zest - blog técnico, 2025-12-24
• Como configurar o Cursor para repositórios de grande escala - NOVA AI - blog técnico, 2026-04-07