Guia completo do índice Codebase do Cursor: fundamentos, configuração e uso prático do @

Atualização de 2026-06-08: revisei os fundamentos de indexação e a postura de privacidade com base na documentação oficial do Cursor. As configurações de índice agora ficam em Cursor Settings → Indexing & Docs e você pode usar “View included files” para ver os arquivos indexados. Os blocos de código são, na prática, enviados criptografados aos servidores do Cursor para gerar vetores e depois armazenados em um banco vetorial remoto, não em um FAISS puramente local. O código-fonte não fica armazenado em texto puro e o índice é removido após 6 semanas de inatividade. A sincronização automática acontece aproximadamente a cada 5 minutos. O texto abaixo foi corrigido com isso em mente.

Na tela, o Cursor me dava a quinta sugestão errada.

“Me ajuda a corrigir esse bug de login” era um pedido bem claro. Só que o código sugerido pelo Cursor não sabia que o projeto já tinha uma função utilitária de auth pronta. Em vez disso, ele queria reescrever a lógica de validação do zero. Pior: sugeriu colocar o código em uma pasta utils que nem existia no projeto.

Foi ali que caiu a ficha: por mais inteligente que a IA seja, se ela não enxerga o projeto inteiro, ela vira só uma máquina que escreve código. As sugestões ficam sempre meio fora do alvo.

Depois, gastei 20 minutos configurando o índice Codebase e o arquivo .cursorignore. Testei de novo. O Cursor entendeu na hora: encontrou o utilitário de auth, percebeu três lugares onde a validação estava duplicada e sugeriu unificar tudo. Aquela sensação de “agora a IA finalmente entendeu meu projeto” é boa demais.

Como o índice do Cursor funciona por baixo

O que é o índice Codebase?

Para ser sincero, na primeira vez que ouvi a palavra “índice”, também fiquei meio perdido. Parece algo sofisticado, mas a ideia é simples.

Imagine que você entra em uma biblioteca para procurar um livro. Sem um sistema de catálogo, você precisa passar por estante por estante e talvez não encontre nada nem depois de um dia inteiro. Com um catálogo, basta digitar o nome do livro ou uma palavra-chave e, em segundos, você chega à prateleira certa.

O índice Codebase do Cursor funciona do mesmo jeito: ele cria um “catálogo inteligente” do projeto inteiro, para que a IA encontre rapidamente o código relevante em vez de adivinhar.

Na prática, indexar significa varrer os arquivos do seu código, analisar o papel de cada função, classe e variável, e depois marcar esses elementos com uma representação matemática, a vetorização. Quando você faz uma pergunta à IA, ela consegue casar em segundos os trechos de código mais relevantes.

Os seis passos principais da indexação

Não vou afundar em detalhes técnicos, porque isso ficaria chato rápido. Mas entender o fluxo ajuda a explicar por que às vezes a indexação fica lenta e por que .cursorignore importa tanto.

Passo 1: varredura e pré-processamento dos arquivos

Quando o Cursor abre seu projeto, a primeira coisa que ele faz é escanear os arquivos. Nesse momento, ele ignora o que estiver marcado em .gitignore e .cursorignore. Então, se você não configurou .cursorignore, ele pode estar indexando node_modules com toda seriedade. E isso significa dezenas de milhares de arquivos.

Passo 2: divisão do código em blocos

Depois da varredura, o Cursor não trata cada arquivo como um bloco gigante. Ele divide por funções, classes e unidades lógicas. Um arquivo utilitário de 1000 linhas, por exemplo, pode virar 30 blocos menores, cada um indexado separadamente. Isso aumenta a precisão na hora da consulta.

Passo 3: embedding vetorial, o coração do processo

Essa etapa é um pouco abstrata, mas dá para explicar sem enrolar: vetorizar é transformar o código em uma sequência de números. Essa sequência funciona como uma “impressão digital” do código. Códigos com funções parecidas geram impressões digitais parecidas. Duas funções de login diferentes, mesmo escritas de formas distintas, ficam próximas no espaço matemático depois da vetorização.

Passo 4: construção do banco de dados vetorial

Muitos tutoriais erram justamente aqui. A situação real é esta: os blocos de código são enviados criptografados aos servidores do Cursor para gerar vetores. Os vetores, junto com caminhos de arquivo e números de linha ofuscados, entram em um banco de dados vetorial remoto; o Cursor usa serviços como Turbopuffer e sincronização incremental por Merkle tree. Ou seja, o índice não é puramente local. Ao mesmo tempo, o Cursor declara que o código-fonte não é armazenado em texto puro, que ele é descartado ao fim da requisição, que os nomes de arquivo são ofuscados e criptografados, e que índices inativos são removidos após 6 semanas.

Passo 5: casamento da consulta

Quando você digita “me ajude a otimizar a lógica de login”, o Cursor também vetoriza essa frase e procura no banco os blocos de código com “impressões digitais” mais próximas. Esse processo é muito rápido, na escala de milissegundos.

Passo 6: injeção de contexto

Depois de encontrar o código relevante, o Cursor injeta esses trechos no contexto enviado à IA. Como a IA passa a ver seu código real, a resposta fica muito mais confiável.

Por que a indexação é tão importante?

Eu fiz testes lado a lado. Com o mesmo pedido, sem índice, o Cursor só enxergava o arquivo que eu tinha aberto e frequentemente dava respostas fora do assunto. Com o índice ativado, ele conseguia relacionar de 3 a 5 arquivos relevantes e sugeria uma solução que dava para usar direto.

A diferença não é pequena. Eu tive um bug entre arquivos que envolvia a camada de API, a camada de dados e a UI. Sem índice, eu precisava marcar os três arquivos com @ e explicar por um bom tempo como eles se conectavam. Com o índice, perguntei direto “por que os dados do usuário não estão atualizando?”. O Cursor encontrou esses três arquivos sozinho e ainda descobriu um quarto arquivo que eu tinha esquecido, no middleware de validação de dados.

Privacidade e segurança

Ao ver expressões como “enviar para a nuvem” e “IA analisando código”, muita gente fica desconfortável. Eu também fiquei na primeira vez.

Primeiro, vamos deixar o mecanismo claro, porque muitos tutoriais erram aqui: durante a indexação, blocos de código são enviados criptografados aos servidores do Cursor para o cálculo de vetores. Existem algumas proteções:

1. O código-fonte não é armazenado em texto puro: o servidor processa durante a requisição, descarta depois e guarda vetores, não seu código-fonte
2. Nomes de arquivo e caminhos são ofuscados e criptografados: mesmo com os dados vetoriais, não dá para reconstruir facilmente a estrutura do projeto
3. Limpeza automática após 6 semanas: índices inativos por muito tempo são removidos, e o projeto é reindexado quando você o abre de novo
4. Privacy Mode: o modo de privacidade nas configurações do Cursor restringe ainda mais a retenção de dados

Falando honestamente, para projetos muito sensíveis, como finanças e saúde, eu ativaria o Privacy Mode e avaliaria com cuidado. Para projetos Web comuns e projetos pessoais, o modo padrão costuma ser aceitável. Só não dá para dizer que “o código nunca sai da máquina”: isso não é preciso, e é bom ter essa noção.

Guia completo do símbolo @

Quando comecei a usar o Cursor, achei que @ era só @. Depois percebi que tem bastante detalhe aí. Usar o @ errado desperdiça tempo e pode levar a IA a sugerir coisas absurdas.

Railway - Plataforma de deploy moderna, sem ops complexas, no ar em minutos

Começar agora →Anúncio

Neste capítulo, listo os 6 usos do @, quando cada um faz sentido, e os principais prós e contras. No fim, você vai saber qual usar em cada situação.

@Codebase - contexto no nível do projeto

Uso: fazer a IA entender a estrutura e a lógica do projeto inteiro.

Esse é o @ mais poderoso e também o mais subestimado. Ao digitar @Codebase, o Cursor usa o banco de índice para encontrar automaticamente os trechos de código mais relacionados à sua pergunta.

Quando usar:

• Investigações entre arquivos: “por que os dados não sincronizam depois do login?”
• Perguntas de arquitetura: “onde meu projeto trata validação de permissões?”
• Aprender um projeto novo: “como as rotas deste projeto são organizadas?”

Minha experiência real: uma vez peguei um projeto legado, sem documentação e com mais de mil arquivos. Perguntei @Codebase como o fluxo de pagamento foi implementado?. O Cursor localizou em segundos 5 arquivos relevantes e explicou o fluxo completo: chamada de API, validação de dados e tratamento de callback. Na mão, eu teria gastado pelo menos meio dia lendo código.

Limitações:

• Depende da qualidade do índice; se ele estiver mal configurado, o resultado piora
• A consulta é um pouco mais lenta, geralmente de 1 a 3 segundos, porque busca no banco inteiro
• Em projetos muito grandes, com mais de 100 mil linhas, alguns trechos periféricos podem ficar de fora

@Files - referência precisa a arquivos

Uso: dizer claramente à IA quais arquivos ela deve observar.

É o caminho mais direto. Ao digitar @Files, aparece um seletor de arquivos. Você marca um ou mais arquivos, e a IA só olha para eles, sem sair procurando em outras partes.

Quando usar:

• Você sabe exatamente em quais arquivos o problema está
• Precisa alterar código em arquivos específicos
• Quer evitar que a IA associe código irrelevante

Caso prático: eu precisava refatorar um componente que envolvia o componente em si, o arquivo de estilo e o teste. Usei @Files, selecionei esses três arquivos e pedi: “me ajude a transformar este componente para uma versão funcional”. A IA olhou só para esses três arquivos e a solução veio bem focada, sem sugestões sobrando.

Pontos fortes: preciso, rápido e controlável
Ponto fraco: você precisa saber de antemão quais arquivos importam, então é fácil esquecer algum

@Folders - referência no nível de diretório

Uso: passar uma pasta inteira como contexto.

Funciona bem quando você sabe que o problema está em um módulo, mas ainda não sabe em qual arquivo.

Quando usar:

• “Otimize todos os componentes em /components/auth/”
• “Confira se há problemas de segurança no código de /api/”
• Processar em lote o código de um módulo

Atenção: se a pasta for grande demais, ela pode ultrapassar o limite de contexto. Em geral, diretórios com até 10 arquivos funcionam bem. Se houver dezenas de arquivos, a IA pode ler só a primeira parte e cortar o restante.

@Code - trecho de código preciso

Uso: referenciar uma função, classe ou bloco específico.

Esse recurso é bem útil. Você pode selecionar um trecho de código, clicar com o botão direito e escolher “Add to Chat”, ou digitar @Code e escolher uma função.

Quando usar:

• “A função validateUser tem um bug; dá uma olhada”
• “Refatore esta lógica para ficar mais clara”
• Revisão de código em um trecho específico

Meu uso favorito: em um arquivo utilitário de 1000 linhas, eu só queria que a IA prestasse atenção a uma função de 50 linhas. Com @Code, selecionei apenas essa função. A IA não se distraiu com o restante do arquivo e focou no problema certo.

@Docs - referência a documentação externa

Uso: fazer a IA consultar documentação externa, como docs oficiais de frameworks e APIs.

Esse recurso entrou no Cursor no fim de 2024, então muita gente ainda não usa.

Quando usar:

• “Com base na documentação oficial do Next.js, me ajude a configurar rotas dinâmicas”
• “Gere o código de chamada a partir desta documentação de API”
• Aprender uma tecnologia nova com a IA apoiada na documentação

Como usar: digite @Docs, informe a URL da documentação ou escolha uma documentação comum já integrada ao Cursor.

Limitações:

• Só cobre parte das documentações oficiais de frameworks populares
• URLs de documentação personalizada às vezes falham por rede ou formato incompatível

@Web - busca em tempo real na internet

Uso: permitir que a IA pesquise informações recentes na Web.

Se você quer usar uma biblioteca recém-lançada e a documentação ainda não entrou no treinamento do modelo, @Web ajuda a buscar o uso mais atualizado.

Quando usar:

• “Pesquise os recursos mais recentes do React 19”
• “Veja como usar a versão mais nova deste pacote npm”
• Resolver bugs ou erros que apareceram recentemente

Atenção: esse recurso é um pouco mais lento, porque faz busca em tempo real. Eu só uso quando realmente preciso de informação recente.

Tabela comparativa: como escolher entre os 6 tipos de @?

Minha forma de usar

Falando honestamente, no começo eu só usava @Files, porque parecia mais seguro. Depois percebi que, em 80% dos casos, @Codebase é mais eficiente. É mais rápido deixar a IA procurar do que eu escolher arquivos manualmente, e ela frequentemente encontra relações que eu tinha ignorado.

Hoje minha frequência de uso fica mais ou menos assim:

• @Codebase: 60%
• @Files: 30%
• @Code: 5%
• Outros: 5%

Você não precisa copiar essa proporção. Encontre seu próprio ritmo. O importante é entender a característica de cada @ e escolher a ferramenta certa para a situação.

Configuração prática do .cursorignore

Chegando aqui, precisamos falar do .cursorignore. Esse arquivo parece pequeno, mas pode aumentar a velocidade de indexação em mais de 50% e cortar o uso de CPU pela metade.

Na primeira vez que usei o Cursor, eu não configurei esse arquivo. Abri um projeto com node_modules, o ventilador do computador disparou e o Cursor ficou travado a ponto de eu questionar minhas escolhas. Só depois descobri: ele estava indexando com dedicação 30 mil arquivos dentro de node_modules, ou seja, código de bibliotecas terceiras de que eu não precisava.

Por que você precisa de .cursorignore?

A razão é simples: nem todo arquivo merece ser indexado.

Seu projeto pode ter:

• Dependências: node_modules, vendor, .venv e afins, com dezenas de milhares de arquivos que quase nunca são úteis para a IA
• Artefatos de build: dist, build, .next e outros, que são gerados pela compilação, não código-fonte
• Arquivos temporários: .log, .cache, .DS_Store e similares, sem relação com o problema
• Recursos estáticos grandes: vídeos, imagens e fontes, que não ajudam na indexação de código

Ao excluir isso, a indexação pode cair de 5 minutos para 30 segundos. As consultas da IA também ficam mais precisas, porque há menos ruído.

.cursorignore vs .gitignore

Muita gente pergunta: se eu já tenho .gitignore, ainda preciso de .cursorignore?

A resposta é: sim, e a lógica dos dois é diferente.

.gitignore responde à pergunta “quais arquivos não devem entrar no controle de versão?”. Mas há arquivos que você não quer commitar e, mesmo assim, quer que a IA veja. Por exemplo:

• Configuração local: .env.local não deve ir para o Git, mas talvez a IA precise entender as variáveis de ambiente
• Notas pessoais: TODO.md pode não ser commitado, mas pode servir como contexto

O inverso também acontece: alguns arquivos precisam ser commitados, mas não precisam ser indexados:

• package-lock.json: precisa ir para o repositório, mas a IA geralmente não precisa ler o lockfile
• Relatórios de cobertura de teste: podem ir para CI, mas não precisam entrar no índice

Por isso, .cursorignore deve ser configurado separadamente.

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

Ver preços →Anúncio

Modelo geral de configuração, pronto para copiar

Este é o modelo geral que uso na maioria dos projetos frontend. Crie um arquivo .cursorignore na raiz do projeto e copie:

# Diretórios de dependências
node_modules/
.pnp/
.pnp.js
vendor/
.venv/

# Artefatos de build
dist/
build/
.next/
out/
.cache/
.parcel-cache/

# Logs e arquivos temporários
*.log
npm-debug.log*
yarn-debug.log*
yarn-error.log*
.DS_Store
Thumbs.db

# Configurações de IDE e editor
.idea/
.vscode/
*.swp
*.swo

# Cobertura de testes
coverage/
.nyc_output/

# Recursos estáticos grandes, ajuste conforme o projeto
*.mp4
*.avi
*.mov
*.zip
*.tar.gz

# Arquivos JSON/lock grandes, opcional
package-lock.json
yarn.lock
pnpm-lock.yaml

Atenção: isso é só uma base. Ajuste ao seu projeto. Se você usa Python, por exemplo, adicione __pycache__/ e *.pyc.

Estratégias avançadas de configuração

1. Indexação por etapas em monorepos grandes

Se o projeto é um monorepo com dezenas de pacotes, indexar tudo pode ser lento. Use algo assim:

# Indexe só o pacote em que você está trabalhando agora
packages/*/node_modules/
packages/package-a/  # pacote que você não está acompanhando no momento
packages/package-b/

Quando precisar, remova o comentário ou ajuste a exclusão.

2. Modo de lista branca

Às vezes o projeto é tão bagunçado que listar exclusões dá mais trabalho do que dizer “indexe só isto”:

# Exclui tudo
*

# Inclui apenas o diretório src
!src/
!src/**/*

# Inclui apenas arquivos de configuração
!*.config.js
!tsconfig.json

Esse modo funciona bem em projetos legados grandes, quando você quer que a IA foque no código central.

3. Filtro por tamanho de arquivo

O Cursor já pula arquivos muito grandes automaticamente, em geral acima de 1 MB, mas você pode excluir manualmente:

# Exclui arquivos de dados grandes
*.sql
*.csv
*.json  # se você tiver arquivos JSON com dezenas de MB

Como validar depois de configurar?

Depois de alterar .cursorignore, valide se ele realmente entrou em vigor. Há três formas:

Método 1: observar a velocidade de indexação

Feche o projeto, abra de novo e observe a barra “Indexing…” no canto inferior direito. Antes da configuração, talvez leve de 3 a 5 minutos. Depois, deve terminar em 30 segundos a 1 minuto.

Método 2: verificar a contagem de arquivos indexados

Abra Cursor Settings → Indexing & Docs e clique em “View included files”. O Cursor abre um arquivo .txt com os arquivos realmente indexados. Se a contagem caiu de dezenas de milhares para algumas centenas, a configuração funcionou.

Método 3: testar @Codebase

Digite @Codebase quais arquivos este projeto tem? e veja a lista retornada. Se arquivos dentro de node_modules ainda aparecerem, .cursorignore não foi aplicado; revise a sintaxe.

Comparação de desempenho

Testei em um projeto Next.js real. Os dados ficaram assim:

Os dados falam por si. Configurar .cursorignore é o primeiro passo para usar bem o Cursor.

Problemas comuns e soluções

Depois de mais de um ano usando Cursor, já caí em vários problemas: índice que falha, consulta lenta, CPU no teto. Quase todo mundo passa por isso.

Neste capítulo, reuni os 4 problemas mais comuns e como resolver. Se acontecer com você, siga esta ordem de diagnóstico.

Problema 1: a indexação falha ou fica presa em “Indexing…”

Sintomas:

• O canto inferior direito fica mostrando “Indexing…” por dezenas de minutos
• Ou aparece “Indexing failed”
• @Codebase não responde

Causas prováveis e soluções:

Causa 1: arquivos demais no projeto, causando timeout

• Solução: configure .cursorignore e exclua arquivos irrelevantes como node_modules
• Validação: feche e reabra o projeto; a indexação deve terminar em até 2 minutos

Causa 2: algum arquivo está corrompido ou em formato incompatível

• Solução: procure arquivos enormes, acima de 10 MB, ou binários, e adicione-os manualmente ao .cursorignore
• Casos comuns: vídeos, dumps SQL grandes e binários compilados

Causa 3: pouco espaço em disco

• Solução: os dados de índice também ficam localmente, então confira o espaço livre. Em geral, mantenha pelo menos 5 GB livres
• Caminho no Mac: ~/Library/Application Support/Cursor/
• Caminho no Windows: %APPDATA%\Cursor\

Causa 4: problema de rede, se a sincronização em nuvem estiver ativa

• Solução: teste com o Privacy Mode desativado ou troque de rede
• Alternativa temporária: revise a configuração de Privacy Mode ou confirme que a rede consegue acessar os serviços do Cursor

Checklist rápido de diagnóstico:

☐ Conferir se .cursorignore está configurado
☐ Ver a contagem de arquivos do projeto; acima de 1000, precisa otimizar
☐ Conferir espaço em disco; pelo menos 5 GB livres
☐ Reiniciar o Cursor
☐ Apagar o cache antigo do índice e reindexar

Problema 2: os resultados de @Codebase são imprecisos

Sintomas:

• O código relevante existe no projeto, mas @Codebase não encontra
• Ou ele retorna código que não tem relação com a pergunta

Causas prováveis e soluções:

Causa 1: índice incompleto ou desatualizado

• Solução: acione a reindexação manualmente
• Como fazer: Cmd+Shift+P no Mac ou Ctrl+Shift+P no Windows → digite “Reindex Codebase” → Enter

Causa 2: o código acabou de ser escrito e ainda não entrou no índice

• Solução: o Cursor sincroniza incrementos automaticamente, em torno de uma vez a cada 5 minutos. Depois de escrever código novo, aguarde um pouco antes de consultar
• Se for urgente, rode Reindex manualmente

Causa 3: a pergunta está vaga demais

• Solução: melhore a descrição. Não pergunte “tem bug?”. Pergunte “por que o token do usuário não está sendo salvo no localStorage depois do login?”
• Comparação:
  • ❌ “otimize a performance”
  • ✅ “o componente de lista renderiza devagar; encontre a causa das renderizações repetidas”

Causa 4: o código relevante foi excluído

• Solução: revise .cursorignore e confirme que você não excluiu código central
• Erro comum: excluir o diretório src inteiro sem querer

Dicas para aumentar a precisão:

• Use nomes concretos de função, variável e arquivo
• Descreva o cenário de negócio, não fale de forma genérica
• Se @Codebase não ficar bom, use @Files e aponte os arquivos diretamente

Problema 3: o Cursor usa CPU ou memória demais

Sintomas:

• O ventilador do computador dispara
• O Cursor usa 80%+ de CPU
• A memória sobe para vários GB
• O sistema fica lento

Causas prováveis e soluções:

Causa 1: muitos arquivos sendo indexados

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

Começar →Anúncio

• Solução: isso é normal durante a primeira indexação; espere terminar
• Se o uso alto continuar, configure .cursorignore para reduzir a contagem de arquivos

Causa 2: atualizações de índice frequentes demais

• Solução: se você altera muito código o tempo todo, o Cursor fica sincronizando o índice em incrementos
• Alívio: o Cursor sincroniza automaticamente mais ou menos a cada 5 minutos; colocar diretórios grandes e muito mutáveis em .cursorignore reduz reindexações repetidas

Causa 3: vários projetos grandes abertos ao mesmo tempo

• Solução: cada projeto consome recursos; feche janelas que você não está usando

Causa 4: banco de índice corrompido

• Solução: apague o cache do índice e reindexe
• Mac: apague ~/Library/Application Support/Cursor/Index/
• Windows: apague %APPDATA%\Cursor\Index\

Sugestões de otimização de desempenho:

☐ Configurar .cursorignore e reduzir a contagem de arquivos; meta abaixo de 1000 arquivos
☐ Fechar janelas de projeto que você não está usando
☐ Ajustar a frequência de atualização do índice para "On save only"
☐ Em projetos muito grandes, considerar @Files no lugar de @Codebase
☐ Melhorar o hardware; pelo menos 16 GB de RAM, idealmente 32 GB

Problema 4: @Codebase responde devagar

Sintomas:

• Depois de enviar a pergunta, você espera 5 a 10 segundos pela resposta
• Às vezes a consulta expira

Causas prováveis e soluções:

Causa 1: banco de índice grande demais

• Solução: configure .cursorignore para reduzir a contagem de arquivos
• Estado ideal: entre 500 e 2000 arquivos indexados, faixa em que a consulta costuma ser mais rápida

Causa 2: rede lenta, se você usa modelo em nuvem

• Solução: confira a conexão ou troque para um modo local
• Configuração: Settings → Models → escolha um modelo com menor latência

Causa 3: a consulta puxa código demais

• Solução: @Codebase tenta incluir todo código relevante; se casar dezenas de arquivos, fica lento
• Otimização: faça uma pergunta mais precisa ou use @Files para limitar o escopo

Causa 4: máquina com pouca capacidade

• Solução: busca vetorial exige algum poder de processamento; se o computador é fraco, a consulta fica mais lenta
• Configuração recomendada: pelo menos 16 GB de RAM e SSD

Dicas para acelerar:

• Prefira @Files ou @Folders quando souber o escopo; são bem mais rápidos que @Codebase
• Limpe caches antigos de índice periodicamente
• Modularize o projeto e carregue apenas as partes necessárias por vez

Minha ordem de diagnóstico

Quando aparece problema, não precisa entrar em pânico. Em 90% dos casos, a causa é .cursorignore ausente ou permissivo demais, levando o Cursor a indexar arquivos irrelevantes.

Minha ordem costuma ser:

1. Verificar .cursorignore primeiro e confirmar se a configuração está correta
2. Acionar uma reindexação manual e ver se resolve
3. Observar CPU e memória para distinguir problema de desempenho de problema de configuração
4. Se nada funcionar, apagar o cache do índice e começar de novo

Na maioria das vezes, seguir essa ordem resolve. Se ainda não resolver, pode ser bug do próprio Cursor; aí vale abrir uma issue no GitHub oficial.

Caso prático: configurando do zero o índice de um projeto Next.js

Chega de teoria. Vamos para um exemplo real com Next.js, da criação do .cursorignore até a validação do resultado.

Seguindo estes passos, dá para resolver em 10 minutos.

Resumo do caso prático: antes e depois

Fiz o teste completo em um projeto Next.js real, com biblioteca de componentes, rotas de API e integração com banco de dados:

A última métrica, “precisão das sugestões da IA”, foi um teste manual com 20 problemas reais de desenvolvimento. Comparei se as sugestões eram utilizáveis. Depois de configurar a indexação, a precisão subiu de 60% para 92%. A diferença foi bem clara.

Pontos principais

Com esse caso prático, você deve ter entendido:

1. ✅ Como criar .cursorignore para um projeto Next.js
2. ✅ Como validar se a configuração de índice entrou em vigor
3. ✅ Como testar os recursos de @
4. ✅ Como otimizar a configuração conforme o projeto

Esse fluxo não vale só para Next.js. Em React, Vue, Angular ou backend, a lógica é a mesma: excluir arquivos irrelevantes para deixar a IA focar no código central.

Leituras relacionadas

• Guia completo do modo Agent do Cursor
• Guia completo para resolver problemas de rede no Cursor
• Guia de uso da cota gratuita do Cursor

Conclusão

Chegando aqui, dá para fechar a conversa.

Volte à cena do começo: uma da manhã, eu encarando a quinta sugestão errada do Cursor. Muita gente já sentiu essa frustração. A IA pode ser poderosa, mas, se ela não enxerga o projeto inteiro, só consegue chutar.

Configurar o índice resolve justamente isso.

Três pontos centrais bastam:

1. Entender o mecanismo não é para parecer sofisticado; é para não cair em armadilhas. Quando você sabe como o índice funciona, entende por que node_modules precisa ficar fora, por que consultas às vezes são lentas e por que a IA às vezes não encontra código.

2. .cursorignore vem primeiro. O resto pode esperar; este arquivo precisa existir. Aumento de 50% na velocidade de indexação, metade do uso de CPU e melhoria de 60% na precisão da IA não são números inventados: são resultados de teste real.

3. Não decore os símbolos @; entenda os cenários. Em 80% dos casos, @Codebase basta. Nos outros 20%, use @Files com precisão. Não complique; com o uso, o ritmo aparece.

Três passos para fazer agora:

1. Vá até a raiz do seu projeto e crie um arquivo .cursorignore, copie o modelo deste texto e salve
2. Reinicie o Cursor e observe a velocidade de indexação, para sentir a diferença
3. Teste @Codebase com uma pergunta que antes a IA respondia mal e veja o resultado

É simples assim. Dez minutos agora podem economizar centenas de horas depois.

Se este texto ajudou, compartilhe com quem ainda está brigando com a indexação do Cursor. Todo mundo aprende depois de cair em algumas armadilhas; se der para evitar uma, melhor.

E um lembrete final: o recurso de índice do Cursor continua evoluindo. Este artigo foi revisado com a documentação oficial de meados de 2026, mas novas funções e novos problemas podem aparecer. Se você encontrar algo que não esteja coberto aqui, consulte a documentação oficial mais recente.

Agora sim: pare de só ler e vá configurar.