Indexación y Docs

Indexación del código base y @Docs

Cursor AI implementa un sistema de indexación inteligente que permite al asistente comprender y navegar por tu código base de manera eficiente. Esta funcionalidad va más allá de la simple búsqueda de texto, creando un mapa semántico de tu proyecto que facilita respuestas más precisas y contextualmente relevantes.

Funcionamiento de la indexación automática

El motor de indexación de Cursor analiza automáticamente la estructura de tu proyecto Python, identificando patrones, dependencias y relaciones entre archivos. Este proceso ocurre en segundo plano y se actualiza dinámicamente conforme modificas tu código.

La indexación reconoce elementos específicos del ecosistema Python como:

• Definiciones de funciones y clases con sus respectivas docstrings
• Importaciones y dependencias entre módulos
• Estructura de paquetes y jerarquías de directorios
• Patrones de uso de bibliotecas y frameworks

# Cursor indexa automáticamente esta estructura
class DataProcessor:
    """Procesador de datos para análisis de IA."""
    
    def __init__(self, config_path: str):
        self.config = self._load_config(config_path)
    
    def process_dataset(self, data: list) -> dict:
        """Procesa un conjunto de datos y retorna métricas."""
        return {"processed": len(data), "status": "complete"}

Configuración de la indexación local

Para optimizar la indexación de tu proyecto específico, accede a Cursor Settings > Features > Codebase Indexing para ver el estado y configurar opciones básicas, o Cursor Settings > Indexing & Docs para opciones más avanzadas.

Las opciones principales incluyen:

• Exclusión de directorios: Evita indexar carpetas como __pycache__, .git, o node_modules
• Priorización de archivos: Enfoca la indexación en archivos .py, .md, y documentación relevante
• Límites de tamaño: Configura el tamaño máximo de archivos a indexar

# Ejemplo de estructura que Cursor indexa eficientemente
proyecto_ia/
├── src/
│   ├── models/
│   │   ├── __init__.py
│   │   └── neural_network.py
│   ├── data/
│   │   └── preprocessor.py
│   └── utils/
│       └── helpers.py
├── tests/
│   └── test_models.py
└── requirements.txt

Utilización del comando @Docs

El comando @Docs representa una funcionalidad avanzada que permite integrar documentación externa directamente en el contexto de Cursor. Esta característica es muy útil cuando trabajas con bibliotecas de IA como TensorFlow, PyTorch, o scikit-learn.

Para utilizar @Docs, simplemente escribe el comando seguido de la URL de la documentación que quieres referenciar:

@docs https://pytorch.org/docs/stable/nn.html

¿Cómo implemento una red neuronal convolucional básica?

Cursor procesará la documentación especificada y la utilizará como contexto adicional para generar respuestas más precisas y actualizadas. Esto es particularmente útil cuando necesitas:

• Implementar funcionalidades específicas de bibliotecas complejas
• Seguir patrones recomendados por la documentación oficial
• Acceder a ejemplos actualizados de uso de APIs

Integración con documentación de proyectos

Cuando trabajas en proyectos de IA generativa, puedes configurar @Docs para que referencie automáticamente documentación relevante. Por ejemplo, si tu proyecto utiliza Hugging Face Transformers:

# Cursor puede referenciar docs de Transformers automáticamente
from transformers import AutoTokenizer, AutoModel

# @docs https://huggingface.co/docs/transformers/
tokenizer = AutoTokenizer.from_pretrained('bert-base-uncased')
model = AutoModel.from_pretrained('bert-base-uncased')

def encode_text(text: str) -> dict:
    """Codifica texto usando BERT con documentación integrada."""
    inputs = tokenizer(text, return_tensors='pt', padding=True)
    outputs = model(**inputs)
    return {"embeddings": outputs.last_hidden_state}

Optimización del rendimiento de indexación

Para maximizar la eficiencia de la indexación en proyectos grandes de IA, considera estas estrategias:

• Segmenta tu código base en módulos lógicos que Cursor pueda indexar independientemente
• Mantén docstrings actualizadas ya que Cursor las utiliza para comprender la funcionalidad
• Organiza imports de manera consistente para facilitar el análisis de dependencias

La indexación inteligente de Cursor, combinada con @Docs, crea un entorno de desarrollo contextual donde el asistente comprende tanto tu código específico como las mejores prácticas de las bibliotecas que utilizas, llevando a sugerencias más relevantes y código de mayor calidad.

Cómo construye Cursor el índice vectorial

A diferencia de una búsqueda textual tradicional (grep), Cursor divide cada archivo en fragmentos (chunks) y genera embeddings que se almacenan en un índice local. Cuando realizas una consulta, el editor recupera los fragmentos cuyo significado es más cercano al de tu pregunta, no solo los que contienen literalmente las mismas palabras. Esto permite, por ejemplo, que una pregunta como «¿dónde se válida el token de usuario?» devuelva código que llame a verify_jwt aunque no aparezca la palabra «token» en la consulta.

El proceso sigue varias fases:

1. Descubrimiento de archivos respetando el .gitignore y el .cursorignore.
2. Particionado en fragmentos de tamaño manejable (normalmente entre 200 y 500 líneas, respetando límites semánticos de funciones y clases).
3. Generación de embeddings con el modelo de Cursor. No se envía el código completo al índice remoto si está activado el modo privacy.
4. Almacenamiento local del índice en la caché del usuario, con refresco incremental cada vez que se guarda un archivo.

El archivo .cursorignore

Igual que .gitignore, puedes crear un .cursorignore en la raíz del repositorio para excluir rutas del índice. Es la forma recomendada de evitar que ficheros generados, datasets, migraciones antiguas o archivos de configuración sensibles contaminen el contexto del asistente.

# .cursorignore
# Datos y artefactos
data/
datasets/
*.csv
*.parquet
notebooks/checkpoints/

# Builds y caches
dist/
build/
.venv/
__pycache__/
.mypy_cache/

# Secretos
.env
.env.*
*.pem

Reducir el tamaño del índice acelera la recuperación de contexto y mejora la precisión: cuanta menos información irrelevante haya, mayor es la probabilidad de que los fragmentos devueltos sean los correctos.

Tabla comparativa: @Codebase vs @Docs vs @Web

| Herramienta | Fuente de contexto | Cuándo usarla | Coste / latencia | |------------|-------------------|---------------|------------------| | @Codebase | Índice vectorial de tu proyecto local | Entender o modificar código existente, buscar implementaciones | Bajo, casi instantáneo | | @Docs | Documentación oficial indexada por Cursor | Usar una API o biblioteca correctamente, seguir patrones oficiales | Medio, requiere consulta al índice remoto | | @Web | Búsqueda en tiempo real en internet | Problemas muy recientes, errores puntuales, releases nuevas | Alto, depende del buscador |

Añadir documentación personalizada a @Docs

Cursor permite registrar sets propios de documentación para que el asistente los trate igual que los oficiales. Esto es clave si usas bibliotecas internas de empresa o forks privados:

1. Abre Cursor Settings > Features > Docs (o Indexing & Docs en versiones recientes).
2. Pulsa «Add new doc» e introduce la URL raíz de la documentación.
3. Asigna un alias corto (por ejemplo @mi-sdk).
4. Espera a que Cursor rastree e indexe las páginas (normalmente entre 1 y 5 minutos).

Una vez añadida, puedes invocarla en cualquier prompt: @mi-sdk ¿cómo autentico una petición?. El asistente limitará el contexto a esa documentación, evitando alucinaciones con API de otras bibliotecas.

Errores comunes al indexar

• Indexación incompleta por .gitignore demasiado agresivo: revisa que los archivos de código no estén excluidos sin querer.
• Respuestas desactualizadas porque el índice de @Docs apunta a una versión antigua de la biblioteca: borra la entrada y vuelve a añadirla con la URL actual.
• Ralentización del editor en monorepos gigantes: activa la opción «Index only opened folders» o divide el repo con un workspace multi-root.
• Fuga de secretos en el contexto: asegúrate de incluir .env, claves y certificados en el .cursorignore.
• Fragmentos truncados en archivos muy largos (>5000 líneas): divide el fichero o refactoriza para que cada módulo tenga una responsabilidad clara.

Mejores prácticas

• Revisa el estado del índice en Settings > Codebase Indexing. Si ves advertencias o porcentajes bajos, fuerza una reindexación manual.
• Combina @Codebase con @Docs en la misma consulta: primero localizas el código a modificar, luego alineas el cambio con la documentación oficial.
• Mantén los docstrings al día: Cursor les da más peso semántico que a los comentarios sueltos.
• Usa nombres descriptivos en funciones, variables y archivos; el embedding aprovecha la semántica de los identificadores.
• Reindexa tras grandes refactors para que los embeddings reflejen la nueva estructura antes de pedir ayuda al agente.

Aplicando estas pautas, el índice deja de ser una caja negra para convertirse en una herramienta que puedes afinar según las necesidades del proyecto, logrando que el asistente trabaje con contexto limpio, actualizado y alineado con tu código real.