Sistema de contexto en Cursor AI

La importancia del contexto en la IA

El contexto es el factor más determinante en la calidad de las respuestas de cualquier modelo de IA. Un modelo sin contexto da respuestas genéricas. Un modelo con el contexto adecuado da respuestas perfectamente adaptadas a tu proyecto, tus convenciones y tus necesidades concretas.

Cursor ha diseñado un sistema completo para gestionar el contexto de forma inteligente: indexación del codebase, selección automática de archivos relevantes y control manual mediante menciones @.

Indexación del codebase

La indexación es el proceso mediante el cual Cursor analiza todos los archivos de tu proyecto y genera embeddings: representaciones vectoriales del código que permiten búsqueda semántica (buscar por significado, no solo por palabras clave).

La indexación ocurre:

• Automáticamente al abrir un proyecto en Cursor por primera vez
• Incrementalmente cuando modificas o añades archivos
• En el fondo, sin interrumpir tu trabajo

Puedes ver el estado de indexación en la barra de estado inferior de Cursor. Un indicador verde significa que el índice está completo y actualizado.

Qué se indexa

Por defecto, Cursor indexa todos los archivos de texto del proyecto excepto:

• Los listados en .gitignore
• Los listados en .cursorignore
• Los listados en .cursorindexingignore
• Archivos binarios (imágenes, compilados, etc.)
• Carpetas típicamente excluidas: node_modules/, __pycache__/, .git/, etc.

Control de indexación con archivos ignore

.cursorignore

El archivo .cursorignore en la raíz del proyecto excluye archivos del acceso de la IA completamente: ni se indexan ni el agente puede leerlos directamente.

# .cursorignore
secrets/
.env
config/production.json
*.key
*.pem

Usa este archivo para archivos sensibles que nunca deberían ser enviados al modelo.

.cursorindexingignore

El archivo .cursorindexingignore excluye archivos de la indexación (no aparecen en búsquedas @codebase) pero el agente puede acceder a ellos si los mencionas directamente con @archivo.

# .cursorindexingignore
dist/
build/
*.min.js
vendor/

Útil para archivos generados que no quieres en el índice pero a los que ocasionalmente necesitas acceder.

Qué incluye el contexto automático

En cada conversación del chat, Cursor incluye automáticamente:

1. El archivo activo en el editor (siempre)
2. Archivos recientemente editados relevantes
3. Archivos importados desde el archivo activo
4. Fragmento de código seleccionado si hay una selección activa
5. Metadatos del proyecto: estructura de directorios, tipo de proyecto detectado

La selección inteligente prioriza los archivos más relevantes para el mensaje específico que estás enviando.

La ventana de contexto

La ventana de contexto determina cuánta información puede procesar el modelo en una sola conversación. Cursor gestiona una ventana de aproximadamente 128k tokens (~10.000 líneas de código promedio).

Cuando la ventana se llena, Cursor:

1. Resume las partes más antiguas de la conversación
2. Mantiene los elementos más recientes y relevantes
3. Advierte al usuario cuando el contexto está cerca del límite

Para tareas que necesitan analizar grandes cantidades de código, usa Max Mode que activa modelos con ventanas de contexto de 200k tokens (Claude) o superiores.

Optimizar el uso del contexto

Principio de menor contexto suficiente: añade solo el contexto realmente relevante para cada pregunta. Un contexto más pequeño y preciso da mejores resultados que un contexto enorme con mucha información irrelevante.

Segmenta las conversaciones: cuando cambias de módulo o de tema, inicia una nueva conversación. Mantener conversaciones enfocadas mejora la calidad de las respuestas.

Usa menciones @ para contexto explícito: cuando necesitas que el modelo considere un archivo concreto, es mejor mencionarlo explícitamente que depender de la selección automática.

Verificar el estado de la indexación

Puedes comprobar el estado de la indexación de tu proyecto en Cursor Settings > Features > Codebase Indexing. Verás:

• Número de archivos indexados: cuántos archivos ha procesado Cursor
• Estado de la indexación: completa, en progreso o con errores
• Última actualización: cuándo se actualizó el índice por última vez
• Botón de reindexar: fuerza una reindexación completa si sospechas que el índice está desactualizado

Para proyectos grandes (más de 10.000 archivos), la indexación inicial puede tardar varios minutos. Una vez completada, las actualizaciones incrementales son casi instantáneas.

Ejemplo práctico: configurar el contexto de un proyecto

Para un proyecto típico con código frontend y backend, una configuración efectiva de los archivos ignore sería:

# .cursorignore — archivos que la IA nunca debe ver
.env
.env.local
secrets/
*.key
*.pem
credentials.json

# .cursorindexingignore — fuera del índice pero accesibles con @
node_modules/
dist/
build/
coverage/
*.min.js
*.min.css
package-lock.json
yarn.lock

Con esta configuración, los archivos sensibles están completamente protegidos, los archivos generados no contaminan la búsqueda semántica, y el índice se mantiene eficiente y relevante.

Estrategias avanzadas de gestión de contexto

Nueva conversación por módulo: cuando cambias de un módulo a otro (de "arreglar el login" a "implementar pagos"), inicia una nueva conversación. El contexto acumulado del módulo anterior puede confundir al modelo.

Menciones explícitas sobre automáticas: para preguntas específicas, @archivo es más preciso que depender de la selección automática. La IA puede no adivinar cuál de tus 50 archivos de servicio es el relevante.

Combina @codebase con @archivo: usa @codebase para encontrar patrones y @archivo para dar el contexto exacto del archivo que quieres modificar. Esta combinación aprovecha lo mejor de ambos enfoques.

Resumen

Cursor indexa el codebase localmente mediante embeddings para búsqueda semántica. El contexto automático incluye el archivo activo y archivos relacionados. Los archivos .cursorignore y .cursorindexingignore controlan qué se indexa y qué puede ver la IA. La ventana de 128k tokens se gestiona automáticamente con resumen de conversaciones largas. Un contexto bien gestionado es la clave para obtener las mejores respuestas posibles del modelo.