Gobernanza del índice en proyectos grandes con Cursor: del diagnóstico a la reconstrucción

La semana pasada hice una auditoría de ingeniería con Cursor para un equipo cuyo monorepo tiene más de 200 paquetes. Cada vez que abrían el proyecto, los tooltips al pasar el cursor tardaban 4 segundos y las sugerencias de autocompletado un promedio de 6 segundos: escribes una línea, bebes un sorbo de café y esperas a que termine de pensar. El equipo estuvo dos días probando cosas: mejorar hardware, cambiar de modelo, reinstalar Cursor. Al final, el problema no estaba en el modelo ni en la red: Cursor indexaba por defecto todo el árbol de packages/ como contexto. Este artículo te da un flujo de diagnóstico, plantillas de configuración y un plan de reconstrucción para que Cursor vuelva a sentirse fluido en unos 10 minutos.

Mecanismo del índice en Cursor — 5 minutos para entender por qué va lento

El Merkle Tree es el protagonista. Cursor lo usa para rastrear cambios en archivos: cada archivo tiene un hash, cada carpeta otro hash basado en los de sus archivos, y así hacia arriba hasta una raíz. ¿Cambias un archivo? Su hash cambia, el de su carpeta también, y el cambio sube hasta la raíz. Cursor solo reindexa lo que cambió, no todo el repositorio.

El problema aparece cuando entran en juego carpetas como node_modules, que pueden tener 50.000 archivos: solo los hashes ya ocupan unos 3,2 MB. Peor aún, Cursor calcula embeddings para esos archivos — código de paquetes npm que no tiene relación con tu lógica de negocio, pero el indexador no lo sabe e indexa todo igual.

Según el blog oficial de Cursor, en el percentil 99 los repositorios grandes tardan 4,03 horas en la primera consulta. Pero hay una ventaja en equipos: entre clones del mismo código, un 92% de archivos son similares de media. Cursor reutiliza esos índices y baja la primera consulta a unos 21 segundos. Si tu índice está limpio, un compañero puede abrir el proyecto y usar la caché que ya calculaste.

En resumen: el índice va lento no porque Cursor calcule mal, sino porque indexa demasiado — y mucho de eso no debería indexarse.

Flujo de diagnóstico — 3 pasos para localizar al culpable

No toques la configuración todavía; diagnostica primero.

Paso 1: revisa el estado del índice. Abre el proyecto y mira el icono de la esquina inferior derecha. Si se queda en «Indexing…» o la barra de progreso no avanza, hay un problema. Pulsa Cmd+Shift+P (en Windows Ctrl+Shift+P), escribe «Show Cursor Logs» y mira las últimas líneas. Verás algo como «Indexing 1,342 files…» — ¿más de 5000? Casi seguro ahí está la causa.

Paso 2: lista las carpetas sospechosas. En la terminal, en la raíz del proyecto, ejecuta find . -type d -name "node_modules" -o -name "dist" -o -name "build" -o -name ".git" | wc -l. Los «asesinos del índice» habituales:

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

Ver precios →Anuncio

Paso 3: vigila CPU y memoria. Abre Activity Monitor (macOS) o el Administrador de tareas (Windows) y mira el proceso de Cursor. ¿CPU por encima del 80% y más de 4 GB de RAM? El índice está calculando hashes y embeddings a toda máquina.

Este árbol de decisión ayuda a acotar rápido:

Según la guía de troubleshooting de Zest, el 90% de los problemas de inestabilidad en Cursor vienen de conflictos de extensiones o mala configuración del índice. Lo más probable es que estés en el segundo caso.

Configuración de .cursorignore — 3 plantillas para escenarios habituales

La sintaxis de .cursorignore es la misma que .gitignore; colócalo en la raíz del proyecto. Cursor no indexará lo que quede dentro.

Plantilla 1: proyecto JavaScript/TypeScript

# Dependencias
node_modules/
.npm/
.yarn/

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

# Tests y cobertura
coverage/
.nyc_output/

# Logs y temporales
*.log
*.tmp
.DS_Store

En monorepos (por ejemplo pnpm workspace) puedes indexar por fases: excluye todos los paquetes y abre solo el que estás tocando.

# Indexación por fases en monorepos
packages/*/
!packages/api/        # Paquete en desarrollo activo
!packages/shared/     # Biblioteca compartida, puede hacer falta
node_modules/
dist/

Plantilla 2: proyecto Python

# Entornos virtuales
venv/
.venv/
env/
.env/

# Caché de compilación
__pycache__/
*.pyc
*.pyo
.pytest_cache/

# Artefactos de empaquetado
*.egg-info/
build/
dist/

# Jupyter Notebook
.ipynb_checkpoints/

Un venv/ suele tener miles de archivos, casi todo código de terceros. Excluirlo puede reducir el tamaño del índice un 90%.

Plantilla 3: proyecto Go

# Caché de dependencias
vendor/

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

# Caché de tests
*.test
*.out
coverage.txt

El directorio vendor/ en Go es comparable a node_modules/ — miles de archivos de dependencias.

Comparativa: según Developer Toolkit, con la configuración por defecto (sin .cursorignore) la precisión del contexto ronda el 65% por el ruido; con exclusiones razonables sube al 98%. Excluir el 20% de archivos puede mejorar la precisión un 50%.

Workspace multi-repositorio para monorepos

Si tu monorepo tiene decenas de servicios y cada apertura esperas a que termine el índice, un archivo .code-workspace puede cargar solo los paquetes en los que trabajas.

Crea workspace.code-workspace en la raíz:

KiloClaw - OpenClaw gestionado para empresas: orquestación de agentes IA y enrutamiento inteligente

Empezar →Anuncio

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

Abre ese archivo con Cursor (no todo el repositorio). En la barra lateral verás solo payments y shared-libs; el resto queda fuera. El índice corre solo en esos directorios — hasta 10 veces más rápido.

Configuración clave:

• maxFileSize: 512000: no indexa archivos mayores de 512 KB, evita que JSON/CSV enormes saturen el contexto
• scopeSelection: "activeFolder": en modo Agent el contexto sale solo de la carpeta activa, sin búsqueda entre paquetes

En monorepos grandes esto ayuda mucho. En un artículo de iamraghuveer, un proyecto con 10 servicios de ~5000 archivos cada uno puede generar 1-5 GB de datos de índice — cargarlo todo satura CPU y memoria. Cargar solo el paquete activo baja el índice a unos 50 MB.

¿Cuándo usar workspace?

• Monorepo con más de 20 paquetes relativamente independientes
• Desarrollas en un paquete sin referencias frecuentes a otros
• El equipo tiene roles claros por servicio

Si las dependencias entre paquetes son fuertes (microservicios que comparten bibliotecas), .cursorignore suele ser más práctico: excluyes lo innecesario y mantienes lo que sí necesitas, sin cambiar de workspace.

Limpieza de caché y reconstrucción del índice — de atascado a fluido

A veces cambias la configuración y el índice sigue mal — puede quedar caché de hashes antiguos. Entonces toca limpiar.

Limpieza rápida (prueba primero)

Cmd+Shift+P, escribe «Reindex Codebase» y ejecútalo. Cursor vuelve a escanear y reconstruye el índice: decenas de segundos en proyectos normales, 2-3 minutos en los grandes. La barra irá de 0% a 100%; puedes tomar agua mientras tanto.

Limpieza profunda (si la rápida no basta)

Elimina el directorio de configuración de Cursor:

Cierra Cursor, borra o mueve ese directorio (backup opcional) y vuelve a abrir. Cursor reinicializará configuración e índice.

⚠️ Atención: borrar la configuración elimina ajustes personalizados (settings.json), atajos y extensiones. Haz backup de User/settings.json antes.

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

Obtener 15% dto. →Anuncio

Pasos de reset completo

1. Cierra Cursor
2. Copia de seguridad de ~/Library/Application Support/Cursor/User/settings.json (si existe)
3. Elimina todo el directorio de configuración
4. Reinicia Cursor
5. Espera a que reindexe el proyecto (varios minutos)
6. Restaura settings.json si quieres recuperar tus ajustes

Según Zest, reinicio → limpiar caché → comprobar estado resuelve el 80% de problemas de índice en 5 minutos. En la mayoría de casos basta la limpieza rápida; la profunda cuando .cursorignore ya está bien pero el índice sigue raro.

¿Cuándo reconstruir el índice?

• La barra muestra «Indexing…» más de 10 minutos sin moverse
• Las sugerencias pasan de 1-2 s normales a más de 5 s durante días
• Cambiaste .cursorignore pero @Codebase sigue mostrando archivos excluidos

Conclusión

La lentitud del índice en Cursor suele deberse a indexar demasiados archivos que no deberían estar. La solución es directa: diagnosticar, excluir, reconstruir.

Lista de acciones:

1. Abre tu proyecto grande, Cmd+Shift+P → «Show Cursor Logs» y mira cuántos archivos indexa
2. Si supera 5000, crea .cursorignore de inmediato (copia una plantilla de este artículo)
3. Excluye node_modules/, dist/, .git/ y artefactos generados
4. Ejecuta «Reindex Codebase» y espera a que termine
5. Si sigue lento, revisa CPU y memoria; valora .code-workspace solo con el paquete activo

Mantenimiento a largo plazo:

• Al añadir dependencias o cambiar el build, revisa si hace falta actualizar .cursorignore
• En equipo, commitea .cursorignore en la raíz para que todos tengan la misma configuración
• En monorepos grandes, limpia índices de servicios inactivos y mantén solo paquetes en desarrollo activo

Pruébalo ahora. En unos 10 minutos deberías notar que Cursor vuelve a fluir: sugerencias en 1-2 segundos, @Codebase sin tirones y tooltips al instante. Recuperas el ritmo de desarrollo.

Referencias

Fuentes citadas en este artículo:

• Securely indexing large codebases - Cursor — Blog oficial de Cursor, 2026-01-27
• Performance Optimization for Cursor - Developer Toolkit — Blog técnico, 2026-05-28
• Cursor Codebase Indexing for Multi-Repo Workspaces - iamraghuveer — Blog personal, 2026-04-25
• A Practical Guide to Cursor Troubleshooting - Zest — Blog técnico, 2025-12-24
• How to setup Cursor for Large Scale Repositories - NOVA AI — Blog técnico, 2026-04-07