Cursor parece VS Code con superpoderes, y lo es — pero para aprovecharlo de verdad necesitas entender cómo funciona cada modo de AI y cuándo usar cada uno. Esta guía te lleva desde la instalación hasta un flujo de trabajo productivo con Composer, Tab, Chat y Rules.
Requisitos Previos
- Descargar Cursor desde cursor.com (Mac, Windows, Linux)
- Un proyecto existente para practicar
- Si vienes de VS Code: tus extensiones y configuración se migran automáticamente
Paso 1: Instalación y Migración
- Descarga e instala Cursor
- Al abrir por primera vez, Cursor ofrece importar tu configuración de VS Code — acepta
- Tus extensiones, temas, keybindings y settings se copian automáticamente
- Abre tu proyecto con
File → Open Folder
Si ya tenías VS Code abierto, ciérralo. Cursor y VS Code pueden coexistir pero comparten algunas extensiones y puede haber conflictos.
Paso 2: Entender los Modos de AI
Cursor tiene cuatro modos principales de interacción con AI. Cada uno tiene su caso de uso:
Tab (Autocomplete Inteligente)
- Se activa automáticamente mientras escribes
- Va más allá del autocomplete típico — predice tu intención, no solo la siguiente línea
- Puede sugerir ediciones en múltiples líneas simultáneamente
- Acepta con
Tab, rechaza conEsc, acepta parcialmente conCtrl+→
Cmd+K / Ctrl+K (Inline Edit)
- Selecciona código → presiona
Ctrl+K→ describe el cambio - Cursor reescribe el código seleccionado en su lugar
- Ideal para cambios puntuales: “convierte esto a async/await”, “agrega manejo de errores”, “optimiza este query”
Chat (Ctrl+L / Cmd+L)
- Panel lateral conversacional
- Usa
@para referenciar archivos, símbolos, documentación - Ideal para preguntas sobre tu codebase, explicaciones, y explorar enfoques
- No edita archivos directamente — te muestra código que puedes aplicar
Composer (Ctrl+I / Cmd+I)
- El modo más poderoso — agente que planifica y aplica cambios en múltiples archivos
- Describe una tarea completa: “agrega autenticación JWT a las rutas de la API”
- Composer analiza tu codebase, planifica los cambios, y los aplica
- Muestra diffs para cada archivo — tú revisas y aceptas o rechazas
Paso 3: Configurar Rules
Las Rules son el equivalente de Cursor a las custom instructions. Crea una carpeta .cursor/rules/ en la raíz de tu proyecto:
.cursor/rules/general.mdc
---
description: Reglas generales del proyecto
globs: "**/*"
---
# Contexto del Proyecto
Este es un proyecto de e-commerce construido con:
- Frontend: Next.js 14 con App Router y TypeScript
- Backend: API Routes en Next.js
- Base de datos: Supabase (PostgreSQL)
- Auth: Supabase Auth
- Styling: Tailwind CSS
- Despliegue: Vercel
# Convenciones
- Código en inglés, comentarios de documentación en español
- Usar Server Components por defecto, Client Components solo cuando sea necesario
- Siempre manejar estados de loading y error
- Validar inputs con Zod en el server side
- Usar las convenciones de naming de Next.js para archivos especiales
.cursor/rules/api.mdc
---
description: Reglas para API routes
globs: "app/api/**/*"
---
# API Routes
- Siempre validar el body del request con Zod
- Usar try/catch con respuestas de error consistentes
- Formato de error: { error: string, code: string, details?: object }
- Autenticar con Supabase Auth middleware
- Rate limiting en endpoints públicos
- Logs estructurados con timestamp y request ID
Las Rules con globs se activan automáticamente cuando trabajas en archivos que coinciden con el patrón. Esto significa que Composer y Chat reciben instrucciones diferentes según el archivo en el que estés.
Paso 4: Flujo de Trabajo con Composer
Composer es donde Cursor realmente se diferencia. Aquí hay un flujo práctico para implementar una feature:
Ejemplo: Agregar un sistema de reviews a productos
- Abre Composer (
Ctrl+I) - Escribe tu prompt con contexto:
Necesito agregar un sistema de reviews para productos. Los usuarios
autenticados pueden dejar una review con rating (1-5 estrellas) y
un comentario opcional.
Necesito:
1. Schema de Supabase para la tabla reviews (migración SQL)
2. API route POST /api/reviews para crear una review
3. API route GET /api/reviews/[productId] para obtener reviews de un producto
4. Componente ReviewForm para enviar una review
5. Componente ReviewList para mostrar reviews con rating promedio
Usa las convenciones existentes del proyecto. Mira cómo están
estructurados los otros API routes y componentes para mantener
consistencia.
- Composer analiza tu proyecto, genera un plan, y empieza a crear/modificar archivos
- Revisa cada diff cuidadosamente — acepta lo que está bien, rechaza lo que no
- Si algo no está correcto, describe el ajuste en el mismo hilo de conversación
Tips para prompts de Composer efectivos:
- Sé específico sobre lo que quieres, pero no sobre cómo implementarlo — deja que Cursor elija el approach basándose en tu codebase existente
- Referencia archivos existentes: “sigue el patrón de
app/api/products/route.ts” - Divide tareas grandes en pasos — es mejor hacer 3 prompts enfocados que uno gigante
Paso 5: Flujo de Trabajo con @ References
El sistema de @ en Chat y Composer es fundamental:
@file— referencia un archivo específico@folder— incluye todos los archivos de una carpeta@codebase— busca en todo tu proyecto (usa el índice)@docs— referencia documentación externa (puedes agregar URLs)@web— busca en la web@git— referencia commits, diffs, y el historial de cambios
Ejemplo práctico en Chat:
@app/lib/supabase.ts @app/api/products/route.ts
¿Cómo puedo agregar paginación al endpoint de productos
manteniendo el patrón existente de manejo de errores?
Esto le da a Cursor exactamente el contexto que necesita sin incluir archivos irrelevantes.
Paso 6: Configurar Docs Externos
Agrega documentación de las librerías que usas para que Cursor las referencie:
- Ve a
Cursor Settings → Features → Docs - Agrega URLs de documentación:
https://nextjs.org/docs— Next.jshttps://supabase.com/docs— Supabasehttps://tailwindcss.com/docs— Tailwind
- Ahora en Chat puedes usar
@docs Next.jsy Cursor busca directamente en la documentación
Esto es especialmente útil para APIs que cambian frecuentemente — Cursor usa la documentación actual en vez de su conocimiento de entrenamiento.
Paso 7: Selección de Modelo
Cursor soporta múltiples modelos. Recomendaciones prácticas:
- Claude Sonnet — mejor relación calidad/velocidad para la mayoría de tareas en Composer
- Claude Opus — para tareas complejas de arquitectura y refactoring grande
- GPT-4o — rápido para edits inline y preguntas simples
- cursor-small — el modelo propio de Cursor, rápido para Tab autocomplete
Puedes cambiar el modelo en cada conversación de Chat o Composer. No estás limitado a uno solo.
Errores Comunes
Aceptar todos los diffs de Composer sin revisar. Composer es poderoso pero no infalible. Revisa cada cambio como revisarías un PR — especialmente en lógica de negocio y seguridad.
No usar Rules. Sin Rules, Cursor genera código genérico. Con Rules bien escritas, genera código que sigue tus convenciones. La diferencia es enorme.
Prompts vagos. “Mejora este código” produce resultados mediocres. “Refactoriza esta función para separar la lógica de validación del procesamiento, y agrega tipos TypeScript específicos en vez de any” produce resultados excelentes.
No indexar el proyecto. Asegúrate de que el indexing esté habilitado en Settings. Sin él, @codebase y las sugerencias de Composer son mucho menos precisas.
Resultado
Con esta configuración tienes un flujo donde:
- Tab maneja el autocomplete inteligente mientras escribes
- Ctrl+K hace edits puntuales sin salir del archivo
- Chat responde preguntas con contexto completo de tu proyecto
- Composer implementa features completas con revisión de diffs
- Rules aseguran que todo el código generado siga tus convenciones
La curva de aprendizaje es de un par de días. El impacto en productividad es inmediato.
¿Ya estás usando Cursor? Comparte tus Rules y flujos de trabajo favoritos. 