Indexação de Base de Código no Cursor: Como Fazer Funcionar Melhor

A indexação de base de código do Cursor é o que o faz parecer "inteligente" sobre seu projeto. Quando funciona, você recebe sugestões relevantes, @-menções precisas e respostas que realmente entendem sua arquitetura. Quando não funciona, o Cursor parece cego.

Este guia explica como a indexação funciona e como otimizá-la.

Como o Cursor Entende Sua Base de Código

O Cursor constrói duas coisas em segundo plano:

1. Embeddings — Representações vetoriais dos seus arquivos de código. Quando você faz uma pergunta ou usa @, o Cursor pesquisa esses vetores para encontrar os arquivos semanticamente mais relevantes.

2. Análise AST (Árvore de Sintaxe Abstrata) — O Cursor analisa seu código para entender imports, definições de funções, hierarquias de classes e relacionamentos entre arquivos.

Esses dois sistemas trabalham juntos. Os embeddings encontram "o que parece relevante", e a análise AST descobre "o que está realmente conectado".

info

A indexação acontece automaticamente quando você abre um projeto. Para bases de código grandes, a varredura inicial pode levar alguns minutos. Você verá um indicador de progresso na barra de status.

@-Símbolos: A Maneira Certa de Usá-los

O símbolo @ é sua linha direta com a indexação do Cursor. Use-o para puxar contexto específico para o chat ou edições inline.

@file — Referenciar um arquivo específico

@src/utils/auth.ts como funciona a validação de token?

Esta é a maneira mais confiável de garantir que o Cursor veja exatamente o arquivo que você se importa. Ela ignora a pesquisa por embeddings e anexa o conteúdo completo do arquivo (até os limites de contexto).

@folder — Referenciar um diretório inteiro

@src/components explique a hierarquia de componentes aqui

Útil para perguntas de arquitetura, mas cuidado — pastas grandes podem consumir sua janela de contexto rapidamente.

@code — Referenciar um símbolo específico

@code:validateUser quais casos extremos isso lida?

Isso usa o índice AST para encontrar a definição exata de função, classe ou variável. É preciso e eficiente em contexto.

dica

Prefira @code: em vez de @file quando você precisar apenas de uma função. Economiza espaço de contexto e reduz ruído.

Otimizando para Projetos Grandes

Se seu projeto tem milhares de arquivos, a indexação padrão pode perder coisas ou parecer lenta.

Verificar o que está realmente indexado

Abra Cursor Settings > General > Codebase Indexing. Você verá:

• Total de arquivos indexados
• Última hora de indexação
• Quaisquer arquivos que falharam ao analisar

Aumentar a relevância do contexto

Para monorepos, o Cursor às vezes pega arquivos irrelevantes. Seja explícito em seus prompts:

Olhe apenas em @packages/api/src para esta pergunta. Ignore o código frontend.

Dividir arquivos gigantes

Arquivos com mais de algumas milhares de linhas podem causar problemas. O Cursor pode indexar apenas o início ou ter dificuldades com embeddings. Se você tem um arquivo utilitário de 5000 linhas, considere dividi-lo.

Ignorando Arquivos com .cursorignore

Nem tudo deve ser indexado. Arquivos gerados, saída de build e código de terceiros desperdiçam espaço de contexto e poluem resultados de pesquisa.

Crie um arquivo .cursorignore na raiz do seu projeto:

# Saída de build
dist/
build/
.out/

# Dependências
node_modules/
vendor/

# Arquivos gerados
*.generated.ts
*.min.js
coverage/

# Arquivos de dados grandes
*.csv
*.json

atenção

.cursorignore usa a mesma sintaxe de .gitignore, mas é um arquivo separado. Não assuma que seu .gitignore é suficiente — o Cursor não o respeita automaticamente.

Após editar o .cursorignore, reinicie o Cursor ou espere um minuto para reindexação.

Quando a Indexação Quebra: Solução de Problemas

Às vezes o Cursor claramente não "vê" seu código. Aqui está a lista de verificação:

1. Verificar se o arquivo está indexado

Abra o arquivo e pergunte:

Qual arquivo estou olhando atualmente?

Se o Cursor não conseguir responder, o arquivo pode não estar no índice.

2. Forçar uma reindexação

Paleta de Comandos (Ctrl+Shift+P) → "Cursor: Reindex Codebase"

Isso reconstrói todo o índice do zero. Leva tempo, mas corrige a maioria dos problemas de corrupção.

3. Procurar erros de análise

Em Settings > General > Codebase Indexing, verifique arquivos com indicadores de erro vermelhos. Esses arquivos não estão sendo analisados para relacionamentos AST.

Causas comuns:

• Erros de sintaxe no arquivo
• Linguagem não suportada (o Cursor suporta bem ~20 linguagens)
• Arquivos binários ou minificados identificados erroneamente como código-fonte

4. Verificar se o .cursorignore não é muito agressivo

Se você ignorou *.config.* e seu vite.config.ts contém aliases de caminho importantes, o Cursor não entenderá seus imports.

Melhorando a Qualidade do Contexto

Colocar os arquivos certos no contexto é apenas metade da batalha. Como você usa esse contexto também importa.

Seja específico em suas perguntas

Ruim:

Como funciona a autenticação?

Bom:

Em @src/auth/middleware.ts, como a verificação JWT lida com tokens expirados?

Encadeie seu contexto

Se o Cursor der uma resposta parcial, faça perguntas de acompanhamento com referências @ mais específicas em vez de repetir a pergunta inteira.

Você mencionou rate limiting. @src/middleware/rateLimit.ts — como o limite é calculado?

Use arquivos recentes

O Cursor pondera arquivos abertos recentemente mais alto na pesquisa por embeddings. Se você acabou de abrir um arquivo, referências @ a arquivos relacionados têm mais chances de funcionar sem menções explícitas.

dica

Para refatorações complexas, abra todos os arquivos que planeja alterar primeiro. Isso "prepara" o índice para tratá-los como relevantes.

Resumo

• O Cursor usa embeddings + AST para entender seu código
• Use @file, @folder e @code: para controlar o contexto explicitamente
• Crie um .cursorignore para excluir ruído
• Reindexe quando as coisas parecerem quebradas
• Seja específico nos prompts — o índice encontra arquivos, mas você guia como eles são usados

O painel de configurações de indexação de base de código mostra o status de indexação do seu projeto e quaisquer erros.