Guía completa de .cursorignore en Cursor: 3 estrategias clave para optimizar la indexación en proyectos grandes

Actualización 2026-06-08: revisado con la documentación oficial de Cursor (junio de 2026). Cursor ya respeta tu .gitignore más una lista de exclusión por defecto integrada (node_modules, lockfiles, artefactos de build y binarios/medios ya quedan fuera de la indexación en su mayoría), así que .cursorignore sirve sobre todo como bloqueo de acceso duro más exclusiones extra; .cursorindexingignore solo bloquea la indexación (con @ aún puedes leer el archivo). Además, el archivo único .cursorrules en la raíz ahora es legacy (se ignora en modo Agent) — pon las reglas de proyecto en .cursor/rules/*.mdc.

El martes por la tarde abrí en Cursor el monorepo de la empresa, con más de 500.000 líneas de código. El icono de Syncing en la esquina inferior derecha empezó a girar. Pasaron 5 minutos y seguía girando. Pasaron 10 minutos y aún indexaba. Me fui a tomar un café y, al volver, seguía ahí, girando con calma.

Lo peor llegó después. Cuando por fin terminó la indexación, pedí a la IA que me ayudara a optimizar un componente React y me sugirió: «Puedes modificar directamente el archivo node_modules/react-dom/cjs/react-dom.development.js». Me quedé mirando la pantalla en silencio tres segundos: la IA había confundido el código de una dependencia con el de mi proyecto.

En ese momento empecé a dudar de si Cursor servía para proyectos grandes. Hasta que descubrí un archivo de configuración llamado .cursorignore y todo cambió. El tiempo de indexación bajó de 12 minutos a 3, y la IA dejó de recomendar cambios absurdos dentro de node_modules.

Si tú también has sufrido indexación lenta o respuestas imprecisas de la IA en Cursor, este artículo te ayudará a resolverlo. Comparto 3 estrategias de optimización con efecto inmediato y una plantilla de configuración que puedes copiar y usar al momento.

Por qué la indexación de Cursor es tan lenta

Primero, hablemos del mecanismo de indexación de Cursor. Cada vez que abres un proyecto, Cursor convierte los archivos de código en vectores de embedding: en términos simples, transforma el código en una representación numérica que la IA puede entender. Ese proceso recorre cada archivo, calcula vectores y los almacena. Cuantos más archivos tenga el proyecto, más lento será.

La pregunta es: ¿realmente necesitas que la IA entienda todos los archivos de tu proyecto?

La mayoría de los proyectos tienen varios tipos de archivos que ocupan mucho espacio, son numerosos y aportan poco a la programación asistida por IA:

node_modules: el agujero negro de dependencias
En un proyecto frontend de tamaño medio, node_modules puede contener decenas de miles de archivos. En un proyecto React con unas decenas de dependencias, el número de archivos supera fácilmente los diez mil. Cursor indexa todo ese código de terceros en cada apertura, pero ¿de verdad necesitas que la IA entienda la implementación interna de lodash?

dist/build: basura de compilación
Son código comprimido y ofuscado generado por herramientas de build. Pedirle a la IA que indexe un archivo JavaScript comprimido en una sola línea es como pedirle que lea jeroglíficos: no tiene sentido.

.git: el peso del historial
Un repositorio Git guarda todo el historial del proyecto. En proyectos grandes, la carpeta .git puede pesar cientos de MB o incluso más de 1 GB. Indexar ese historial es perder el tiempo.

Recursos estáticos grandes
Vídeos, imágenes, fuentes… la IA no puede leerlos, así que indexarlos no aporta nada.

Hice una prueba: un proyecto Next.js de 100.000 líneas, con node_modules y el directorio de build .next completos, tardaba 8 minutos en indexarse. Tras configurar .cursorignore para excluir esos directorios, el tiempo bajó a 2 minutos. Cuatro veces más rápido.

Lo más importante es la precisión. Cuando el contexto de la IA se llena de código de node_modules, confunde qué es tuyo y qué pertenece a una dependencia. El resultado: te sugiere modificar paquetes instalados o trata APIs de librerías de terceros como si fueran funciones escritas por ti.

Guía completa de configuración de .cursorignore

La buena noticia es que la sintaxis de .cursorignore es exactamente la misma que la de .gitignore. Si ya sabes escribir .gitignore, este archivo te resultará muy familiar.

Vultr - Servidor cloud NVMe de alto rendimiento, 32 ubicaciones globales, despliegue Docker con un clic

Ver precios →Anuncio

Resumen de sintaxis básica

Crea un archivo .cursorignore en la raíz del proyecto (fíjate en el punto inicial) y escribe según estas reglas:

# Esto es un comentario; empieza con #

# Excluir un archivo concreto
config.json

# Excluir un directorio completo (termina con barra)
node_modules/
dist/

# Coincidencia con comodines
*.log          # todos los archivos de registro
**/*.test.js   # archivos de prueba en cualquier nivel

# Regla de negación (volver a incluir)
!important.log # excluye todos los .log, pero conserva este

Plantilla lista para usar

He preparado una configuración base válida para la mayoría de proyectos. Puedes copiarla directamente en tu .cursorignore:

# Directorios de dependencias
node_modules/
.pnp/
.pnp.js
vendor/
packages/

# Artefactos de compilación
dist/
build/
out/
.next/
.nuxt/
.cache/
.vite/
.turbo/

# Pruebas y cobertura
coverage/
.nyc_output/
*.spec.js
*.test.js
__tests__/

# Registros y archivos temporales
*.log
npm-debug.log*
yarn-debug.log*
yarn-error.log*
.DS_Store
*.swp
*.swo
*~

# Configuración de entorno (por seguridad)
.env
.env.local
.env.*.local
credentials.json
*.key
*.pem

# Control de versiones
.git/
.svn/
.hg/

# Configuración del IDE (opcional)
.vscode/
.idea/
*.sublime-*

# Archivos de recursos grandes (ajusta según necesidad)
*.mp4
*.mov
*.avi
*.zip
*.tar.gz
*.pdf
public/videos/

Esta configuración cubre el 90 % de los escenarios habituales. Después de guardarla, abre Settings > Features > Codebase Indexing en Cursor, pulsa el botón de refresco y deja que la configuración surta efecto.

Configuración avanzada por escenario

Según el tipo de proyecto, puedes ajustar la plantilla base:

Proyectos React/Vue: excluye archivos grandes en public

# Añade sobre la configuración base
public/assets/
public/images/*.png
public/fonts/

Proyectos monorepo: excluye subpaquetes irrelevantes (esto es clave)

# Supón que trabajas en frontend y solo te importa apps/web
apps/mobile/
apps/admin/
packages/backend-utils/

Proyectos full stack: separa la indexación de frontend y backend

# Si trabajas sobre todo en frontend
server/
api/
database/
migrations/

# O si trabajas sobre todo en backend
client/
public/
src/components/

Un truco útil: si no estás seguro de si un archivo queda excluido, ejecuta en la terminal:

git check-ignore -v [ruta-del-archivo]

Aunque es un comando de git, la sintaxis coincide con .cursorignore, así que sirve para depurar la configuración.

.cursorignore vs .cursorindexingignore: elegir la herramienta correcta

Al principio yo también me liaba con estos dos archivos. Los nombres se parecen, ¿cuál es la diferencia? ¿Cuál usar?

En resumen: .cursorignore es bloqueo total; .cursorindexingignore es bloqueo parcial.

Diferencia esencial

.cursorignore: la IA no puede acceder en absoluto a esos archivos. No los indexa, no los lee ni los referencia. Para Cursor, es como si no existieran. Se usa en dos casos: archivos sensibles (.env, claves) o cosas que no quieres que la IA toque nunca (node_modules, artefactos de build).

.cursorindexingignore: los archivos no aparecen en las búsquedas del código base, pero la IA puede leerlos cuando haga falta (por ejemplo, al mencionarlos con @ o arrastrarlos al chat). Cursor añadió esta función más tarde, pensada sobre todo para optimizar el rendimiento.

Ejemplo: tienes un directorio legacy/ con código heredado de hace tres años. No quieres que contamine los resultados de búsqueda, pero a veces la IA puede necesitar consultar esa lógica antigua. Ahí encaja .cursorindexingignore.

Tabla de escenarios de uso

Prioridad de configuración

Cursor aplica estas configuraciones en este orden:

1. Lee primero .gitignore del proyecto (se respeta automáticamente)
2. Luego lee .cursorignore (puedes usar la sintaxis ! para sobrescribir gitignore)
3. Por último aplica .cursorindexingignore

¿Qué implica esto? Si tu .gitignore excluye logs/, pero quieres que la IA acceda a un registro concreto, puedes escribir en .cursorignore:

!logs/important-debug.log

También existe una función útil llamada «Hierarchical Cursor Ignore». Al activarla (búscala en Settings), Cursor busca de forma recursiva .cursorignore en directorios padre. Es ideal para poner una configuración global en la raíz de un monorepo grande y añadir reglas complementarias en subproyectos.

Mi estrategia de uso

En la práctica, en la mayoría de casos me basta con .cursorignore. .cursorindexingignore es más una herramienta de ajuste fino, útil cuando el rendimiento es crítico o la estructura del proyecto es especialmente compleja.

Al empezar, te recomiendo:

• Paso 1: usa solo .cursorignore y excluye lo que claramente no necesitas
• Paso 2: observa una semana cómo se comporta la IA
• Paso 3: si aún hay problemas, plantéate .cursorindexingignore para afinar

No intentes montar algo demasiado complejo desde el primer día; ir paso a paso funciona mejor.

3 estrategias de optimización para monorepos

Los monorepos son el tipo de proyecto que más fácilmente «rompe» la experiencia con Cursor. Un solo repositorio puede incluir frontend, backend, móvil, panel de administración… ante tanto código, la IA se confunde con facilidad.

Railway - Plataforma de despliegue moderna, sin ops complejas, en producción en minutos

Empezar ahora →Anuncio

Yo me equivoqué en un monorepo con 12 subaplicaciones. Pedí a la IA que optimizara un componente frontend y me sugirió usar una utilidad del directorio de APIs backend. Sonaba razonable, pero el frontend no podía acceder a ese código: los dos paquetes ni siquiera compartían el mismo entorno de ejecución.

Después resumí 3 estrategias que en la práctica funcionan muy bien:

Estrategia 1: dividir la indexación por zona de trabajo

La forma más directa: excluye los subproyectos que no te interesan.

Supón que eres del equipo frontend y trabajas sobre todo en apps/web. Excluye el resto de subaplicaciones:

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

Tiene dos ventajas: la indexación va más rápido y la IA no se distrae con código de otros subproyectos. En un monorepo donde dejé solo los dos paquetes de mi responsabilidad, el tiempo de indexación bajó de 15 minutos a 4.

Si eres full stack y cambias a menudo entre frontend y backend, prepara dos archivos: .cursorignore.frontend y .cursorignore.backend, y copia el adecuado a .cursorignore según el trabajo del momento.

Estrategia 2: guiar a la IA con Project Rules

El mayor problema de un monorepo es que la IA no entiende bien la relación entre directorios. Ahí entran las Project Rules para darle un mapa del proyecto. Nota: el antiguo archivo único .cursorrules de la raíz ahora es legacy y se ignora en modo Agent; para proyectos nuevos usa archivos .mdc en .cursor/rules/ (no .cursorignore). Crea, por ejemplo, .cursor/rules/project-structure.mdc con frontmatter YAML (description, globs, alwaysApply):

---
description: estructura del monorepo y reglas de referencia de código
alwaysApply: true
---

# Descripción de la estructura del proyecto

Este es un monorepo que incluye las siguientes subaplicaciones:

- apps/web: aplicación frontend (Next.js), puerto 3000
- apps/api: API backend (Node.js + Express), puerto 8000
- apps/admin: panel de administración (React), puerto 3001
- packages/ui: librería compartida de componentes UI
- packages/utils: funciones de utilidad comunes

## Reglas de referencia de código

- Las apps frontend (web/admin) solo pueden importar packages/ui y packages/utils
- El frontend no puede importar código de apps/api directamente
- Los paquetes compartidos (packages/*) no pueden depender de apps concretas (apps/*)

## Enfoque de trabajo actual

Ahora mismo el desarrollo principal está en apps/web; las sugerencias de optimización deben centrarse en código frontend.

La IA lee estas reglas y entiende mejor la estructura. El efecto es claro: después de configurarlo, rara vez vuelve a recomendar referencias entre fronteras.

Estrategia 3: modo de trabajo con ventanas separadas

En monorepos muy grandes (por ejemplo, con más de 20 subaplicaciones), aunque configures .cursorignore, el contexto de una sola ventana sigue siendo enorme.

Mi enfoque: abrir una ventana independiente de Cursor para cada subaplicación.

• Ventana 1: abre el directorio apps/web
• Ventana 2: abre el directorio apps/api
• Ventana 3: abre el directorio packages/ui

Cada ventana tiene su propia indexación y contexto, y la IA entiende mejor. La desventaja es cambiar de ventana, pero en proyectos grandes compensa por la mejora de precisión.

Un truco: si hay dependencias entre subaplicaciones (por ejemplo, web depende de la librería ui), en la ventana de web puedes referenciar explícitamente con @folder:

@folder packages/ui Ayúdame a revisar la definición de props del componente Button

Así mantienes la ventana ligera y accedes al código de dependencias cuando haga falta.

Idea central para monorepos

En resumen, la optimización de un monorepo consiste en esto: hacer que la IA vea solo lo que necesita ver.

Cuanto más grande sea el proyecto, más hay que restar. No esperes que la IA entienda toda la arquitectura como tú; si le marcas límites, sus sugerencias serán más acertadas.

Verificar y mantener tu configuración

Configurar .cursorignore no es algo que haces una vez y olvidas. Tienes que comprobar que funciona y mantenerla con el tiempo.

Comprobar que la configuración funciona

Lo más intuitivo es mirar el tiempo de indexación. Compara la duración de Syncing antes y después; si baja de forma clara, la configuración está haciendo efecto.

Métodos más precisos:

1. Revisar el estado de indexación
   Abre Settings > Features > Codebase Indexing y mira cuántos archivos se han indexado. Tras configurar .cursorignore, ese número debería bajar de forma notable.

2. Probar el alcance del contexto de la IA
   Haz una pregunta con @codebase y comprueba si la respuesta sigue citando archivos excluidos. Por ejemplo, si excluyes node_modules y preguntas «qué componentes React hay en el proyecto», la IA no debería listar componentes dentro de node_modules/react.

3. Verificar la búsqueda
   Usa la búsqueda de código de Cursor (Cmd/Ctrl + P) para buscar un archivo dentro de un directorio que hayas excluido. Si no aparece, la configuración ha funcionado.

Cuándo refrescar la indexación manualmente

Cursor detecta cambios de archivos y actualiza la indexación de forma incremental, pero en estos casos conviene refrescar a mano:

• Has modificado .cursorignore
• Cambias a una rama de Git con cambios grandes
• Borras o añades muchos archivos de golpe
• Sientes que la IA ya no entiende bien el proyecto, posiblemente por indexación desactualizada

Cómo refrescar: Settings > Features > Codebase Indexing > Refresh. Un clic basta. El refresco reindexa todo el proyecto; espera a que termine Syncing.

Alibaba Cloud - Opción preferida para desarrolladores, 15 % de descuento exclusivo en Lighthouse

Obtener 15% dto. →Anuncio

Mantenimiento diario de la configuración

.cursorignore no se escribe una vez y ya está. A medida que el proyecto evoluciona, puede que tengas que ajustarla:

Lista de revisión mensual:

• ¿Se han excluido nuevos directorios de build? (por ejemplo, .output/ tras actualizar el framework)
• ¿Hay nuevos directorios con archivos grandes que convenga excluir?
• ¿Siguen existiendo los directorios que ya excluías? (limpia reglas obsoletas)

Recomendaciones para trabajo en equipo:

Si es un proyecto de equipo, ¿conviene commitear .cursorignore a Git? Mi recomendación depende del caso:

• Reglas generales de exclusión (node_modules, dist, etc.): sí, commítelas para que todo el equipo se beneficie
• Preferencias personales de trabajo (excluir ciertos subproyectos): no las commitees, o añádelas a .git/info/exclude

También puedes añadir en .gitignore:

.cursorignore.local

Y escribir tu configuración personal en .cursorignore.local, referenciándola desde .cursorignore si Cursor admite sintaxis de include.

Documenta el motivo de cada exclusión con comentarios

Es un hábito muy útil. En .cursorignore, añade comentarios explicando por qué excluyes un directorio:

# 2025-01-15: excluir el nuevo directorio de datos de entrenamiento IA; archivos demasiado grandes y sin necesidad de indexación
data/training/

# 2025-01-10: excluir temporalmente el directorio de pruebas de rendimiento; contiene muchos archivos de registro
perf-tests/

Tres meses después, te agradecerás haber dejado esos comentarios.

Lectura relacionada

• Guía completa de indexación del código base de Cursor: principios, configuración y símbolo @
• Cursor en proyectos grandes: que el Agent no se pierda en repos enormes
• Guía completa del cupo gratuito de Cursor

Resumen

Volvamos al problema del inicio: ¿indexación lenta y respuestas imprecisas de la IA en Cursor significan que la herramienta no sirve?

No. En la mayoría de casos, simplemente no le hemos dicho a la IA qué debe mirar y qué debe ignorar.

.cursorignore es una herramienta sencilla pero muy potente. Dedicar 5 minutos a configurarla puede ahorrarte horas de espera en los próximos meses y, sobre todo, hacer que la IA dé sugerencias más acertadas.

Lista de acción en tres pasos:

1. Actúa ya: copia la plantilla base de este artículo y crea .cursorignore en la raíz del proyecto
2. Personaliza: según tu tipo de proyecto (React/Vue/Monorepo), añade reglas de exclusión específicas
3. Mejora de forma continua: observa el comportamiento de la IA durante una semana, anota problemas e itera la configuración

No hace falta buscar la configuración perfecta a la primera. Empieza con la plantilla base para resolver el 80 % del problema y ajusta el 20 % restante sobre la marcha.

Si también usas Cursor en proyectos grandes, prueba estas estrategias. Comparte en los comentarios tu experiencia de configuración o los problemas que encuentres; quizá ayudes a otros desarrolladores en la misma situación.