Guía completa del índice Codebase de Cursor: principios, configuración y uso práctico del símbolo @

Actualizado el 2026-06-08: revisado con la documentación oficial de Cursor — los ajustes de indexación están ahora en Cursor Settings → Indexing & Docs (compruébalo con «View included files»); en realidad los fragmentos de código se cifran y se envían a los servidores de Cursor para generar embeddings que se guardan en una base vectorial remota (no es un índice FAISS puramente local) — aunque el código fuente nunca se almacena en texto plano y los índices se borran tras 6 semanas de inactividad; la sincronización corre cada ~5 minutos. El texto siguiente está actualizado.

La quinta sugerencia errónea de Cursor en pantalla.

«Ayúdame a arreglar este bug de login» — el requisito era claro. Pero Cursor propuso código sin saber que el proyecto ya tenía una utilidad de auth, y me hizo reescribir la lógica de validación. Peor aún: sugirió meter el código en utils, y el proyecto ni siquiera tiene esa carpeta.

Ahí entendí: por muy listo que sea la IA, si no ve el proyecto completo, solo es un robot que escribe código; las sugerencias siempre quedan a medias.

Luego invertí 20 minutos en configurar el índice Codebase y .cursorignore. Al probar de nuevo, Cursor lo pilló al instante: encontró la utilidad de auth, detectó tres sitios con validación duplicada y propuso unificarla. Esa sensación de «por fin entiende mi proyecto» compensa todo.

Principios del índice de Cursor

¿Qué es el índice Codebase?

La primera vez que oí «índice» también me sonó a jerga. Suena técnico, pero en cuanto lo entiendes, es sencillo.

Imagina buscar un libro en una biblioteca. Sin catálogo, recorres estantería tras estantería y puedes tardar un día. Con fichas de catálogo, escribes título o palabra clave y localizas el sitio en segundos.

El índice Codebase de Cursor hace lo mismo: crea un «catálogo inteligente» de todo el proyecto para que la IA encuentre código relevante en lugar de adivinar.

En concreto, escanea tus archivos, analiza qué hace cada función, clase y variable, y les asigna «etiquetas» mediante vectorización. Cuando preguntas, empareja al instante los fragmentos más relevantes.

Seis pasos clave de la indexación

No voy a aburrirte con detalles técnicos, pero entender el flujo explica por qué a veces va lento y por qué importa .cursorignore.

Paso 1: escaneo y preprocesado

Al abrir el proyecto, Cursor escanea todos los archivos. Omite lo marcado en .gitignore y .cursorignore — si no configuras .cursorignore, puede estar indexando node_modules en serio: decenas de miles de archivos.

Paso 2: fragmentación del código

Tras el escaneo, no trata cada archivo como un bloque único. Lo divide por funciones, clases y bloques lógicos. Un archivo de utilidades de 1000 líneas puede partirse en 30 trozos indexados por separado, con mayor precisión en las consultas.

Paso 3: embeddings vectoriales (el núcleo)

En palabras simples: vectorizar convierte el código en una secuencia numérica, como una «huella». Código con función similar tiene huellas parecidas. Dos funciones de login distintas pueden quedar muy cerca en el espacio matemático.

Paso 4: base de datos vectorial

Aquí muchas guías se equivocan. En realidad, los fragmentos de código se cifran y se suben a los servidores de Cursor para generar los embeddings; esos vectores —junto con rutas de archivo ofuscadas y números de línea— se guardan en una base vectorial remota (Cursor usa un servicio como Turbopuffer), con sincronización incremental mediante un árbol de Merkle. Así que el índice no es puramente local — pero Cursor afirma que el código fuente nunca se almacena en texto plano (se descarta tras la petición), los nombres de archivo se ofuscan/cifran y los índices se borran tras 6 semanas de inactividad.

Paso 5: emparejamiento en consulta

Cuando escribes «ayúdame a optimizar el login», Cursor vectoriza la frase y busca en la base los bloques con huellas más cercanas. Es muy rápido: milisegundos.

Paso 6: inyección de contexto

Los fragmentos encontrados se inyectan en el contexto de la IA. Al ver tu código real, las respuestas encajan mucho mejor.

¿Por qué importa tanto el índice?

Hice una prueba comparativa. Con la misma petición, sin índice Cursor solo veía el archivo abierto y a menudo respondía al lado. Con índice, enlaza 3-5 archivos relacionados y las propuestas suelen ser aplicables directamente.

La diferencia no es pequeña. Tuve un bug entre archivos que cruzaba API, datos e interfaz. Sin índice tuve que @ manualmente tres archivos y explicar cómo se relacionaban. Con índice pregunté «¿por qué no se actualizan los datos del usuario?» y Cursor encontró esos tres archivos más uno que me faltaba (validación en middleware).

Privacidad y seguridad

«Subir a la nube» y «IA analizando código» asustan a muchos. A mí también la primera vez.

Primero el mecanismo (que muchas guías cuentan mal): al indexar, los fragmentos de código se cifran y se envían a los servidores de Cursor para calcular los embeddings. Pero hay protecciones reales:

1. El código fuente no se almacena en texto plano — el servidor solo lo procesa durante la petición y luego lo descarta; la base guarda vectores, no tu fuente
2. Nombres de archivo/rutas ofuscados y cifrados — ni con los datos vectoriales se reconstruye la estructura del proyecto
3. Borrado automático a las 6 semanas — los índices inactivos mucho tiempo se eliminan; al reabrir el proyecto se reindexa
4. Privacy Mode — el modo privacidad de Ajustes limita aún más la retención de datos

Para proyectos muy sensibles (finanzas, salud) activo Privacy Mode y lo evalúo con cuidado; para webs normales o proyectos personales, el modo por defecto va bien. Pero la idea de que «tu código nunca sale de tu equipo» no es exacta — tenlo presente.

Guía completa del símbolo @

Al empezar con Cursor pensé que @ era solo @. Hay más matices: usarlos mal pierde tiempo y empuja respuestas absurdas.

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

Empezar →Anuncio

Aquí van los 6 símbolos @, escenarios, pros y contras. Después sabrás cuál elegir.

@Codebase — contexto a nivel de proyecto

Uso: que la IA entienda la estructura y la lógica de todo el proyecto.

Es el @ más potente y el más infravalorado. Tras escribir @Codebase, Cursor usa el índice para sacar automáticamente los fragmentos más relevantes a tu pregunta.

Escenarios:

• Depuración entre archivos: «¿por qué no se sincronizan los datos tras el login?»
• Arquitectura: «¿dónde se valida permisos en mi proyecto?»
• Proyecto nuevo: «¿cómo está organizado el enrutado?»

Experiencia real: heredé un proyecto legacy sin documentación, miles de archivos. Pregunté @Codebase ¿cómo está implementado el flujo de pago? y en segundos localizó cinco archivos: API, validación y callback, de punta a punta. Manualmente habría sido medio día.

Limitaciones:

• Depende de la calidad del índice; mal configurado, peor resultado
• Consulta más lenta (1-3 s) porque busca en toda la base
• En proyectos enormes (100k+ líneas) puede perder código periférico

@Files — referencia precisa a archivos

Uso: decirle a la IA exactamente qué archivos mirar.

Lo más directo. Escribes @Files, eliges uno o varios archivos, y la IA solo ve esos; no se va por las ramas.

Escenarios:

• Sabes en qué archivos está el problema
• Quieres modificar archivos concretos
• Evitar ruido de código irrelevante

Caso práctico: refactoricé un componente (componente, estilos, tests). Seleccioné los tres con @Files y pedí «pásalo a componente funcional». La respuesta fue muy focalizada, sin ruido.

Ventajas: preciso, rápido, controlable
Inconvenientes: hay que saber qué archivos; fácil omitir alguno

@Folders — referencia a directorio

Uso: usar todo un directorio como contexto.

Útil cuando sabes el módulo pero no el archivo exacto.

Escenarios:

• «Optimiza todos los componentes en /components/auth/»
• «Revisa /api/ por problemas de seguridad»
• Procesar en lote un módulo

Nota: carpetas muy grandes superan el límite de contexto. Suele ir bien hasta ~10 archivos; con decenas, la IA puede truncar lo final.

@Code — fragmento concreto

Uso: referenciar una función, clase o bloque.

Muy útil: selecciona código, «Add to Chat», o @Code y el nombre de la función.

Escenarios:

• «Esta función validateUser tiene un bug, revísala»
• «Refactoriza este bloque para que sea más claro»
• Code review de un trozo concreto

Mi favorito: en un archivo de 1000 líneas solo quiero que mire una función de 50. Con @Code no se distrae con el resto.

@Docs — documentación externa

Uso: que la IA consulte docs oficiales o de API.

Llegó a Cursor a finales de 2024; mucha gente aún no lo usa.

Escenarios:

• «Según la doc de Next.js, configura rutas dinámicas»
• «Con esta doc de API, genera el código de llamada»
• Aprender algo nuevo con la doc como referencia

Uso: @Docs, URL o docs integradas de frameworks comunes.

Limitaciones:

• Solo parte de frameworks mainstream
• URLs personalizadas a veces fallan (red o formato)

@Web — búsqueda en tiempo real

Uso: que la IA busque información actualizada en la web.

Si acabas de usar una librería nueva que el modelo no conoce bien, @Web ayuda.

Escenarios:

• «Busca las novedades de React 19»
• «Uso actual de este paquete npm»
• Errores o bugs muy recientes

Nota: va más lento por la búsqueda en vivo. Solo cuando necesitas lo último.

Tabla comparativa: ¿qué @ elegir?

Mi experiencia de uso

Al principio solo usaba @Files por seguridad. Luego vi que el 80% de las veces @Codebase es más eficiente: la IA encuentra más rápido que yo manualmente y a menudo enlaza código que yo ignoraba.

Mi reparto habitual:

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

No tienes que copiarlo; encuentra tu ritmo. Lo clave es entender cada @ y cuándo usarlo.

Configuración práctica de .cursorignore

Aquí toca hablar de .cursorignore. Parece menor, pero puede acelerar la indexación más de un 50% y bajar a la mitad el uso de CPU.

La primera vez no lo configuré. Abrí un proyecto con node_modules, el ventilador a tope y Cursor casi inutilizable. Estaba indexando en serio unos 30 000 archivos de dependencias que no aportaban nada.

¿Por qué hace falta .cursorignore?

Simple: no todo merece indexarse.

En tu proyecto puede haber:

• Dependencias: node_modules, vendor, .venv — miles de archivos que casi nunca necesitas
• Artefactos de build: dist, build, .next — generados, no fuente
• Temporales: .log, .cache, .DS_Store
• Recursos estáticos grandes: vídeo, imágenes, fuentes — inútiles para el índice

Excluirlos pasa la indexación de 5 minutos a 30 segundos y las consultas son más precisas al no mezclar ruido.

.cursorignore vs .gitignore

Pregunta frecuente: «Ya tengo .gitignore, ¿hace falta .cursorignore?»

Sí, y la lógica es distinta.

.gitignore decide qué no va al repositorio. Pero hay archivos que no commiteas y sí quieres que la IA vea:

• Config local: .env.local no se commitea, pero la IA puede necesitar saber tus variables
• Notas personales: TODO.md no se commitea, pero la IA puede leerlo

Al revés, hay archivos que sí commiteas pero no indexar:

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

Ver precios →Anuncio

• package-lock.json: en git, pero la IA no necesita el lockfile
• Informes de cobertura: en CI, pero no en el índice

Configura .cursorignore por separado.

Plantilla general (lista para usar)

Plantilla que uso en la mayoría de frontends. Crea .cursorignore en la raíz y pega:

# Dependencias
node_modules/
.pnp/
.pnp.js
vendor/
.venv/

# Build
dist/
build/
.next/
out/
.cache/
.parcel-cache/

# Logs y temporales
*.log
npm-debug.log*
yarn-debug.log*
yarn-error.log*
.DS_Store
Thumbs.db

IDE:
.idea/
.vscode/
*.swp
*.swo

Cobertura:
coverage/
.nyc_output/

# Recursos estáticos (ajusta según proyecto)
*.mp4
*.avi
*.mov
*.zip
*.tar.gz

# JSON grandes (opcional)
package-lock.json
yarn.lock
pnpm-lock.yaml

Nota: base genérica; en Python añade __pycache__/ y *.pyc.

Estrategias avanzadas

1. Monorepo grande: indexación por fases

Con decenas de paquetes, indexar todo tarda:

# Solo el paquete en el que trabajas
packages/*/node_modules/
packages/package-a/  # paquete que no tocas
packages/package-b/

Quita el comentario cuando lo necesites.

2. Lista blanca

A veces es más fácil decir qué sí indexar:

Excluir todo:
*

# Solo src
!src/
!src/**/*

# Config
!*.config.js
!tsconfig.json

Útil en proyectos viejos grandes: solo código núcleo.

3. Filtrar por tamaño

Cursor suele saltar archivos muy grandes (>1 MB), pero puedes excluir manualmente:

# Datos grandes
*.sql
*.csv
*.json  # si tienes JSON de decenas de MB

¿Cómo verificar que funciona?

Tras editar .cursorignore, comprueba:

Método 1: velocidad de indexación

Cierra y reabre el proyecto; mira «Indexing…» abajo a la derecha. Antes 3-5 minutos; después 30 s-1 min.

Método 2: número de archivos indexados

Abre Cursor Settings → Indexing & Docs y pulsa «View included files» para listar lo que se indexa realmente. De decenas de miles a cientos = bien.

Método 3: probar @Codebase

@Codebase ¿qué archivos tiene el proyecto? — si siguen saliendo cosas de node_modules, revisa la sintaxis.

Comparativa de rendimiento

En un Next.js real medí:

Los números no mienten. Configurar .cursorignore es el primer paso para usar Cursor bien.

Problemas frecuentes y soluciones

Llevo más de un año con Cursor y he pisado muchos charcos: indexación que falla, consultas lentas, CPU al límite… el 90% lo pasa.

Aquí van cuatro problemas típicos y cómo resolverlos.

Problema 1: la indexación falla o se queda en «Indexing…»

Síntomas:

• «Indexing…» durante decenas de minutos
• O «Indexing failed»
• @Codebase no responde

Causas y soluciones:

Causa 1: demasiados archivos, timeout

• Solución: .cursorignore, excluir node_modules, etc.
• Verificación: cierra y reabre; debería acabar en ~2 minutos

Causa 2: formato no soportado o archivo corrupto

• Solución: busca archivos >10 MB o binarios; añádelos a .cursorignore
• Típico: vídeos, dumps SQL grandes, binarios compilados

Causa 3: poco espacio en disco

• Solución: el índice ocupa disco local; deja al menos 5 GB
• Mac: ~/Library/Application Support/Cursor/
• Windows: %APPDATA%\Cursor\

Causa 4: red (si hay sync en nube)

• Solución: prueba desactivar Privacy Mode o cambia de red
• Temporal: revisa el ajuste Privacy Mode, o que la red pueda alcanzar los servidores de Cursor

Checklist rápido:

☐ ¿Está configurado .cursorignore?
☐ ¿Cuántos archivos tiene el proyecto? (>1000 → optimizar)
☐ ¿Hay al menos 5 GB libres?
☐ Reiniciar Cursor
☐ Borrar caché del índice y reindexar

Problema 2: @Codebase no encuentra o devuelve basura

Síntomas:

• Hay código relevante pero @Codebase no lo ve
• O devuelve fragmentos irrelevantes

Causas y soluciones:

Causa 1: índice incompleto u obsoleto

• Solución: reindexación manual
• Cmd+Shift+P (Mac) / Ctrl+Shift+P (Windows) → «Reindex Codebase»

Causa 2: código nuevo aún no indexado

• Solución: sincroniza automáticamente (~5 min, oficialmente); espera un poco o haz un Reindex

Causa 3: pregunta demasiado vaga

• Solución: sé concreto. No «hay un bug», sino «¿por qué el token no se guarda en localStorage tras el login?»
• Comparación:
  • ❌ «Optimizar rendimiento»
  • ✅ «El listado va lento; encuentra re-renders duplicados»

Causa 4: código excluido por error

• Solución: revisa .cursorignore; no excluyas src entero por accidente

Trucos de precisión:

• Usa nombres de función, variable y archivo
• Describe el escenario de negocio
• Si @Codebase falla, prueba @Files

Problema 3: CPU/RAM altos

Síntomas:

• Ventilador a tope
• Cursor >80% CPU
• Varios GB de RAM
• Sistema lento

Causas y soluciones:

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

Empezar ahora →Anuncio

Causa 1: indexando muchos archivos

• Normal al indexar; espera a que termine
• Si persiste, reduce archivos con .cursorignore

Causa 2: actualización del índice muy frecuente

• Si editas sin parar, Cursor reindexa seguido
• Mitigación: Cursor sincroniza por defecto de forma incremental (~5 min); añade carpetas grandes que cambian a menudo a .cursorignore para reducir la reindexación

Causa 3: varios proyectos grandes abiertos

• Cierra ventanas que no uses

Causa 4: base de índice corrupta

• Borra caché y reindexa
• Mac: ~/Library/Application Support/Cursor/Index/
• Windows: %APPDATA%\Cursor\Index\

Optimización:

☐ .cursorignore (<1000 archivos objetivo)
☐ Cerrar proyectos innecesarios
☐ Excluir carpetas grandes que cambian a menudo en .cursorignore para reducir la reindexación
☐ Proyectos enormes: @Files en lugar de @Codebase
☐ Hardware: mínimo 16 GB RAM; recomendado 32 GB

Problema 4: @Codebase responde lento

Síntomas:

• 5-10 s de espera
• A veces timeout

Causas y soluciones:

Causa 1: base de índice demasiado grande

• Reduce archivos con .cursorignore
• Ideal: 500-2000 archivos

Causa 2: red lenta (modelo en nube)

• Comprueba conexión o modelo más rápido
• Ajustes → Models

Causa 3: demasiado código emparejado

• Preguntas amplias pueden traer decenas de archivos
• Sé más preciso o usa @Files / @Folders

Causa 4: hardware justo

• La búsqueda vectorial pide recursos
• Recomendado: 16 GB RAM + SSD

Acelerar:

• @Files o @Folders suelen ir más rápido que @Codebase
• Limpia caché del índice de vez en cuando
• Modulariza el proyecto

Mi método de diagnóstico

No entres en pánico. El 90% de los problemas de índice vienen de no configurar .cursorignore y indexar basura.

Mi orden:

1. Revisar .cursorignore
2. Reindexar manualmente
3. Mirar CPU/RAM: ¿rendimiento o configuración?
4. Borrar caché y empezar de cero

Con eso suele bastar. Si no, puede ser bug de Cursor; abre issue en GitHub.

Caso práctico: configurar el índice de un proyecto Next.js desde cero

Basta de teoría. En un Next.js real: de crear .cursorignore a verificar, paso a paso.

Sigue la guía: 10 minutos.

Resumen del caso: antes y después

En un Next.js real (componentes, API routes, base de datos):

La última fila la medí a mano con 20 preguntas reales. Tras configurar el índice, de 60% a 92% de respuestas útiles.

Puntos clave

Con este caso deberías saber:

1. ✅ Crear .cursorignore para Next.js
2. ✅ Verificar que el índice funciona
3. ✅ Probar los símbolos @
4. ✅ Optimizar según tu proyecto

El mismo enfoque vale para React, Vue, Angular o backend: excluye ruido, deja que la IA se centre en el código núcleo.

Lecturas relacionadas

• Guía completa del modo Agent de Cursor
• Resolución completa de problemas de red en Cursor
• Guía completa del nivel gratuito de Cursor

Conclusión

Volvamos al inicio: la madrugada, la quinta sugerencia errónea de Cursor. Muchos lo hemos vivido. La IA es potente, pero sin ver el proyecto entero solo adivina.

Configurar el índice es la clave.

Tres ideas para recordar:

1. Entender el principio no es postureo: evita trampas. Saber cómo indexa explica por qué excluir node_modules, por qué a veces va lento y por qué a veces no encuentra código.

2. .cursorignore es lo primero. Lo demás puede esperar; esto no. Indexación ~50% más rápida, CPU ~50% menos, precisión ~60% más — datos de prueba real.

3. No memorices @: entiende el escenario. El 80% del tiempo basta @Codebase; el 20% restante, @Files con precisión. La práctica te da el ritmo.

Tres pasos ahora:

1. Ve a la raíz del proyecto y crea .cursorignore con la plantilla de este artículo
2. Reinicia Cursor y compara la velocidad de indexación
3. Prueba @Codebase con una pregunta que antes fallaba

Diez minutos hoy, cientos de horas después.

Si te ayudó, compártelo con quien siga peleándose con el índice de Cursor. Todos hemos pasado por ahí.

El índice de Cursor sigue evolucionando. Esta guía se revisó con la documentación oficial de mediados de 2026, pero pueden aparecer novedades y nuevos problemas. Si algo no está cubierto, consulta la documentación oficial.

Bueno, deja de leer y ve a configurarlo.