Guia completo do .cursorignore no Cursor: 3 estratégias essenciais para otimizar a indexação em projetos grandes

Atualizado em 8 de junho de 2026: revisei o conteúdo com base na documentação oficial do Cursor de junho de 2026. Por padrão, o Cursor já respeita o .gitignore e uma lista interna de exclusões, portanto node_modules, arquivos de lock, artefatos de build e a maioria dos arquivos binários ou de mídia já ficam fora do índice. Assim, o .cursorignore serve principalmente para bloquear o acesso e acrescentar exclusões. O .cursorindexingignore só impede a indexação, e os arquivos ainda podem ser lidos por referências com @. Além disso, o arquivo único .cursorrules na raiz foi marcado oficialmente como legacy e é ignorado no modo Agent; use arquivos .mdc dentro de .cursor/rules/ para regras do projeto.

Na tarde da última terça-feira, abri o monorepo da empresa, com mais de 500 mil linhas de código. O ícone Syncing no canto inferior direito do Cursor começou a girar. Cinco minutos depois, ainda estava girando. Dez minutos depois, a indexação continuava. Fui preparar um café e, quando voltei, o processo ainda avançava devagar.

O pior veio depois. Quando a indexação finalmente terminou, pedi à IA para otimizar um componente React. Ela sugeriu: “Você pode editar diretamente o arquivo node_modules/react-dom/cjs/react-dom.development.js”. Fiquei olhando para a tela por três segundos — a IA tinha confundido o código de uma dependência com o código do meu projeto.

Naquele momento, comecei a pensar que o Cursor talvez não fosse adequado para projetos grandes. Até descobrir um arquivo de configuração chamado .cursorignore. Tudo mudou: a indexação caiu de 12 para 3 minutos, e a IA parou de sugerir alterações dentro de node_modules.

Se você também enfrenta indexação lenta ou interpretações incorretas da IA no Cursor, as três estratégias abaixo, além de um modelo de configuração pronto para copiar, podem ajudar a resolver o problema.

Por que a indexação do Cursor fica tão lenta

Primeiro, vale entender como funciona a indexação do Cursor. Sempre que você abre um projeto, o Cursor converte os arquivos de código em vetores de embedding — em termos simples, transforma o código em uma representação numérica que a IA consegue interpretar. Esse processo percorre cada arquivo, calcula os vetores e os armazena. Quanto mais arquivos houver, mais demorado será.

Mas será que a IA realmente precisa entender todos os arquivos do seu projeto?

A maioria dos projetos contém alguns tipos de arquivo que ocupam muito espaço e aparecem em grande quantidade, mas quase não ajudam na programação assistida por IA:

node_modules — um buraco negro de dependências
Em um projeto frontend de porte médio, node_modules pode conter dezenas de milhares de arquivos. Basta instalar algumas dezenas de dependências em um projeto React para ultrapassar facilmente 10 mil arquivos. O Cursor indexaria todo esse código de terceiros, mas você realmente precisa que a IA entenda a implementação interna do lodash?

dist/build — lixo de compilação
Esses diretórios contêm código minificado e ofuscado gerado pelas ferramentas de build. Pedir à IA para indexar um arquivo JavaScript inteiro comprimido em uma única linha é tão inútil quanto fazê-la decifrar um texto ilegível.

.git — o peso do histórico
Um repositório Git guarda todo o histórico do projeto. Em projetos grandes, o diretório .git pode ocupar centenas de MB ou até vários GB. Indexar esses dados históricos é puro desperdício de tempo.

Recursos estáticos grandes
Vídeos, imagens e fontes não podem ser interpretados dessa maneira pela IA. Indexá-los não traz benefício algum.

Fiz um teste com um projeto Next.js de 100 mil linhas, incluindo node_modules e o diretório de build .next. A indexação levou 8 minutos. Depois de excluir esses diretórios com o .cursorignore, caiu para 2 minutos — uma diferença de quatro vezes.

Mais importante ainda é a precisão. Quando o contexto da IA fica cheio de código de node_modules, ela pode confundir o que pertence ao projeto com o que vem de bibliotecas. O resultado são sugestões para editar dependências ou a interpretação de APIs externas como se fossem funções escritas por você.

Guia completo de configuração do .cursorignore

A boa notícia é que a sintaxe do .cursorignore é exatamente igual à do .gitignore. Se você sabe criar um .gitignore, esse arquivo será bem simples.

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

Ver preços →Anúncio

Visão rápida da sintaxe básica

Crie um arquivo .cursorignore na raiz do projeto — observe o ponto no início — e use regras como estas:

# Isto é um comentário, iniciado por #

# Excluir um arquivo específico
config.json

# Excluir diretórios inteiros (com barra no final)
node_modules/
dist/

# Correspondência com curingas
*.log          # Todos os arquivos de log
**/*.test.js   # Arquivos de teste em qualquer nível

# Regra de negação (reincluir)
!important.log # Excluir todos os .log, exceto este

Modelo de configuração pronto para usar

Preparei uma configuração básica adequada à maioria dos projetos. Você pode copiá-la diretamente para seu .cursorignore:

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

# Artefatos de build
dist/
build/
out/
.next/
.nuxt/
.cache/
.vite/
.turbo/

# Testes e cobertura
coverage/
.nyc_output/
*.spec.js
*.test.js
__tests__/

# Logs e arquivos temporários
*.log
npm-debug.log*
yarn-debug.log*
yarn-error.log*
.DS_Store
*.swp
*.swo
*~

# Configuração de ambiente (por segurança)
.env
.env.local
.env.*.local
credentials.json
*.key
*.pem

# Controle de versão
.git/
.svn/
.hg/

# Configuração do IDE (opcional)
.vscode/
.idea/
*.sublime-*

# Recursos grandes (ajuste conforme necessário)
*.mp4
*.mov
*.avi
*.zip
*.tar.gz
*.pdf
public/videos/

Essa configuração cobre 90% dos cenários comuns. Depois de salvar, abra Settings > Features > Codebase Indexing no Cursor e clique no botão de atualização para aplicar as regras.

Configuração avançada por tipo de projeto

Cada tipo de projeto pode acrescentar alguns ajustes ao modelo básico:

Projetos React/Vue: exclua arquivos grandes dentro do diretório public.

# Adicione ao modelo básico
public/assets/
public/images/*.png
public/fonts/

Monorepos: exclua subpacotes irrelevantes — isso faz bastante diferença.

# Supondo que você esteja na equipe de frontend e só trabalhe em apps/web
apps/mobile/
apps/admin/
packages/backend-utils/

Projetos full stack: separe a indexação de frontend e backend.

# Se você trabalha principalmente no frontend
server/
api/
database/
migrations/

# Ou, se trabalha principalmente no backend
client/
public/
src/components/

Quando houver dúvida sobre a exclusão de um arquivo, execute este comando no terminal:

git check-ignore -v [caminho do arquivo]

Embora seja um comando do Git, ele ajuda a depurar a configuração porque a sintaxe do .cursorignore é a mesma.

.cursorignore vs. .cursorindexingignore — escolha a ferramenta certa

Quando conheci esses dois arquivos de configuração, também fiquei em dúvida. Os nomes parecem muito semelhantes. Qual é a diferença e qual deles usar?

Em resumo, o .cursorignore faz um bloqueio total, enquanto o .cursorindexingignore faz um bloqueio parcial.

Diferença fundamental

.cursorignore: a IA não consegue acessar os arquivos. Ela não os indexa, não os lê nem os consulta. Para o Cursor, é como se não existissem. Isso serve para dois casos: arquivos sensíveis, como .env e chaves, ou conteúdo que a IA não precisa tocar, como node_modules e artefatos de build.

.cursorindexingignore: os arquivos não aparecem nos resultados de busca da base de código, mas a IA ainda pode lê-los quando necessário — por exemplo, se você os referenciar explicitamente com @ ou arrastá-los para a conversa. O Cursor acrescentou esse recurso especificamente para otimização de desempenho.

Imagine um projeto antigo com um diretório legacy/, contendo código de três anos atrás. Você não quer que esse código polua os resultados de busca, mas eventualmente a IA pode precisar consultar a lógica de uma implementação antiga. O .cursorindexingignore é adequado para esse caso.

Tabela de cenários de uso

Ordem de prioridade das configurações

O Cursor processa essas configurações nesta ordem:

1. Primeiro, lê o .gitignore do projeto, que é respeitado automaticamente
2. Depois, lê o .cursorignore, no qual a sintaxe ! pode sobrescrever o gitignore
3. Por fim, aplica o .cursorindexingignore

O que isso significa? Se o .gitignore exclui o diretório logs/, mas você quer permitir que a IA acesse um arquivo de log específico, adicione ao .cursorignore:

!logs/important-debug.log

Há também um recurso chamado “Hierarchical Cursor Ignore”. Quando ele está ativado nas Settings, o Cursor procura arquivos .cursorignore de forma recursiva nos diretórios pai. Isso permite manter uma configuração global na raiz de um monorepo e acrescentar regras específicas em cada subprojeto.

Minha estratégia de uso

Na prática, o .cursorignore é suficiente na maioria dos casos. O .cursorindexingignore funciona mais como uma ferramenta de ajuste fino para projetos com exigências extremas de desempenho ou uma estrutura especialmente complexa.

Ao configurar pela primeira vez, recomendo este processo:

• Primeiro: use apenas o .cursorignore e exclua o que claramente não é necessário
• Segundo: observe durante uma semana como a IA se comporta
• Terceiro: se ainda houver problemas, use o .cursorindexingignore para fazer ajustes mais refinados

Não complique tudo de uma vez. Uma evolução gradual costuma funcionar melhor.

Três estratégias de otimização para monorepos

Monorepos são o tipo de projeto que mais facilmente sobrecarrega o Cursor. Um único repositório pode conter frontend, backend, aplicativo móvel e painel administrativo. Com tanto código, a IA pode interpretar o contexto incorretamente.

Passei por isso em um monorepo com 12 subaplicações. Pedi à IA para otimizar um componente frontend, e ela recomendou importar uma função utilitária do diretório da API de backend. A sugestão parecia razoável, mas o frontend não tinha acesso ao código do backend: os dois pacotes nem sequer rodavam no mesmo ambiente.

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

Começar agora →Anúncio

Depois disso, reuni três estratégias bastante práticas.

Estratégia 1: dividir o índice por área de trabalho

A solução mais simples e direta é excluir os subprojetos que não fazem parte do seu trabalho.

Se você integra a equipe de frontend e trabalha principalmente no diretório apps/web, exclua as outras subaplicações:

# .cursorignore
apps/mobile/
apps/admin/
apps/api/
packages/backend-utils/
packages/database/
services/

Isso traz dois benefícios: a indexação fica mais rápida e a IA deixa de ser distraída pelo código de outros subprojetos. Em um monorepo, mantive apenas os dois pacotes sob minha responsabilidade e o tempo de indexação caiu de 15 para 4 minutos.

Se você é desenvolvedor full stack e alterna frequentemente entre frontend e backend, pode preparar dois arquivos: .cursorignore.frontend e .cursorignore.backend. Depois, copie para .cursorignore a configuração correspondente ao trabalho atual.

Estratégia 2: usar Project Rules para explicar a estrutura à IA

O maior problema de um monorepo é que a IA não entende claramente a relação entre os diretórios. Você pode usar Project Rules para oferecer a ela um mapa do projeto. Atenção: o arquivo único .cursorrules na raiz foi marcado oficialmente como legacy e é ignorado no modo Agent. Em projetos novos, use arquivos .mdc dentro de .cursor/rules/ — não no .cursorignore.

Crie um arquivo de regra dentro de .cursor/rules/, por exemplo project-structure.mdc. Use o frontmatter YAML para controlar sua ativação com description, globs e alwaysApply, e descreva o mapa do projeto no corpo:

---
description: Estrutura do projeto monorepo e regras de importação de código
alwaysApply: true
---

# Estrutura do projeto

Este é um monorepo com as seguintes subaplicações:

- apps/web: aplicação frontend (Next.js), porta 3000
- apps/api: API backend (Node.js + Express), porta 8000
- apps/admin: painel administrativo (React), porta 3001
- packages/ui: biblioteca compartilhada de componentes de UI
- packages/utils: funções utilitárias compartilhadas

## Regras de importação de código

- As aplicações frontend (web/admin) só podem importar packages/ui e packages/utils
- O frontend não pode importar diretamente código de apps/api
- Pacotes compartilhados (packages/*) não podem depender de aplicações específicas (apps/*)

## Foco atual

O trabalho atual está concentrado em apps/web; mantenha as sugestões de otimização focadas no código frontend.

Essas regras são lidas pela IA e ajudam a explicar a estrutura do projeto. O efeito é claro: depois da configuração, a IA raramente volta a recomendar importações que atravessam limites indevidos.

Estratégia 3: trabalhar em janelas separadas

Em monorepos muito grandes, com mais de 20 subaplicações, até uma única janela configurada com .cursorignore pode acabar com contexto demais.

Nesse caso, abro uma janela separada do Cursor para cada subaplicação:

• Janela 1: abre o diretório apps/web
• Janela 2: abre o diretório apps/api
• Janela 3: abre o diretório packages/ui

Cada janela possui índice e contexto próprios, e a interpretação da IA fica mais precisa. A desvantagem é ter que alternar entre janelas, mas, em um projeto grande, o ganho de precisão compensa esse pequeno incômodo.

Se houver dependências entre subaplicações, como o aplicativo web depender da biblioteca de componentes de UI, você pode usar @folder na janela do web para referenciar explicitamente o código:

@folder packages/ui Verifique para mim a definição das props do componente Button

Assim, a janela continua leve, mas ainda consegue acessar o código de uma dependência quando necessário.

A ideia central para monorepos

Em resumo, a ideia central da otimização de monorepos é: deixe a IA ver apenas o que ela precisa ver.

Quanto maior o projeto, mais importante é reduzir o contexto. Não espere que a IA compreenda toda a arquitetura tão bem quanto você. Defina os limites de forma explícita para receber sugestões mais precisas.

Como validar e manter sua configuração

Configurar o .cursorignore não é uma tarefa definitiva. É preciso verificar se ele funciona e fazer manutenção periódica.

Verifique se a configuração entrou em vigor

A forma mais direta é observar o tempo de indexação. Compare a duração do Syncing antes e depois. Se houver uma queda clara, a configuração funcionou.

Também há formas mais precisas de validar:

1. Verifique o status da indexação
   Abra Settings > Features > Codebase Indexing para ver quantos arquivos foram indexados. Depois de configurar o .cursorignore, esse número deve cair bastante.

2. Teste o alcance do contexto da IA
   Faça uma pergunta com @codebase e veja se a resposta ainda cita arquivos excluídos. Por exemplo, depois de excluir node_modules, pergunte “Quais componentes React existem no projeto?”. A IA não deve listar componentes dentro de node_modules/react.

3. Valide com a busca
   Use a busca de código do Cursor, Cmd/Ctrl + P, e procure o nome de um arquivo que esteja em um diretório explicitamente excluído. Se ele não aparecer, a configuração funcionou.

Quando atualizar o índice manualmente

O Cursor detecta alterações nos arquivos e atualiza o índice de forma incremental, mas algumas situações exigem uma atualização manual:

• Você alterou o arquivo .cursorignore
• Mudou para uma branch do Git com muitas alterações
• Excluiu ou adicionou muitos arquivos de uma vez
• A interpretação da IA parece incorreta e o índice pode estar desatualizado

Para atualizar, acesse Settings > Features > Codebase Indexing > Refresh. Clique uma vez e espere o Syncing terminar; o projeto inteiro será reindexado.

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

Ganhar 15% off →Anúncio

Manutenção cotidiana da configuração

O .cursorignore não deve ser escrito uma vez e esquecido. Conforme o projeto evolui, talvez seja preciso ajustá-lo.

Checklist mensal:

• Verifique se novos diretórios de build já foram excluídos, como um diretório .output/ criado após a atualização do framework
• Procure novos diretórios de arquivos grandes que devam ser excluídos
• Confirme se os diretórios excluídos anteriormente ainda existem e remova regras obsoletas

Recomendação para equipes:

O .cursorignore deve ser enviado ao Git em um projeto de equipe? Minha recomendação depende do tipo de regra:

• Regras gerais de exclusão, como node_modules e dist: envie ao Git para beneficiar toda a equipe
• Preferências pessoais, como excluir certos subprojetos: não envie, ou coloque em .git/info/exclude

Você também pode acrescentar esta linha ao .gitignore:

.cursorignore.local

Depois, coloque a configuração pessoal em .cursorignore.local e faça referência a ela no .cursorignore, caso o Cursor ofereça suporte à sintaxe include.

Use comentários para registrar o motivo das exclusões

Esse hábito é muito útil. Acrescente comentários ao .cursorignore explicando por que um diretório foi excluído:

# 2025-01-15: excluir o novo diretório de dados de treinamento de IA; os arquivos são grandes e não precisam ser indexados
data/training/

# 2025-01-10: excluir temporariamente o diretório de testes de desempenho, que contém muitos arquivos de log
perf-tests/

Ao revisar a configuração três meses depois, você agradecerá por ter escrito esses comentários.

Leitura complementar

• Guia completo de indexação de bases de código no Cursor: conceitos, configuração e uso do símbolo @
• Cursor em projetos grandes: como evitar que o Agent se perca em bases de código extensas
• Guia completo dos limites gratuitos do Cursor

Conclusão

Voltando à pergunta do início: se a indexação do Cursor é lenta e a IA interpreta o contexto de forma incorreta, isso significa que a ferramenta não funciona bem?

Não. Na maioria dos casos, nós é que ainda não dissemos à IA em que ela deve prestar atenção e o que pode ignorar.

O .cursorignore é uma ferramenta simples, mas poderosa. Cinco minutos de configuração podem economizar horas de espera nos próximos meses e, mais importante, produzir sugestões de IA mais precisas.

Checklist de três ações:

1. Aja agora: copie o modelo básico deste artigo e crie um arquivo .cursorignore na raiz do projeto
2. Personalize a otimização: acrescente regras específicas ao seu tipo de projeto, seja React, Vue ou um monorepo
3. Melhore continuamente: observe o comportamento da IA durante uma semana, registre problemas e refine a configuração

Não tente chegar à configuração perfeita na primeira vez. Comece pelo modelo básico para resolver 80% dos problemas e ajuste os 20% restantes conforme o uso real.

Se você também usa o Cursor em projetos grandes, vale a pena experimentar essas estratégias. Compartilhe sua configuração ou suas dúvidas nos comentários — elas podem ajudar outras pessoas com o mesmo problema.