Para empezar, si querés ponerlo en práctica, descarga en https://cursor.com/, create una cuenta en https://github.com/ para hacer tu primer proyecto.
Si querés ordenar y trabajar mejor pre-desarrollo, usá from021.io para definir las funcionalidades y obtener las prompts (código: 02126 para probar un mes gratis).
¿Qué es Cursor?
Cursor es un editor de código (fork de VS Code) integrado con IA. Permite:
Editar archivos.
Organizar proyectos.
Escribir o modificar código con asistencia de agente IA.
Ejecutar terminal integrada.
Interactuar con un agente con contexto del proyecto.
Estructura principal de Cursor
Cuando abrís Cursor, verás:
El panel principal donde ves y editás código.
1. Barra lateral izquierda
Cursor se organiza en cuatro secciones clave:
Explorer: archivos y carpetas del proyecto (crear, abrir, renombrar, borrar).
Search: buscador interno en todo el código.
Source Control / Timeline: historial de cambios y acciones de Git. Desde donde se hace el push al repositorio.
Integraciones: accesos a extensiones o herramientas conectadas.
2. Editor
El panel principal donde podes ver y editar código.
3. Agente - Chat lateral derecho
Podés pedirle cosas a la IA con contexto directo del código, por ejemplo:
"Explicame este archivo" o “Explicame cómo está hecha X feature”
"Creá un componente nuevo llamado Header"
"Arreglá este error en la función X"
Modos principales:
Ask: consultas directas, explicaciones, diagnósticos.
Agent: ejecuta cambios en el código (crear, editar, refactorizar, arreglar).
Planning: propone planes, pasos y estrategias antes de actuar.
4. Terminal
Sirve para ejecutar comandos del proyecto (por ejemplo: correr el proyecto, instalar dependencias, ver logs).
Primeros Pasos: Setup Inicial del Proyecto
Cómo abrir un proyecto por primera vez en Cursor
Opción A: Proyecto ya descargado en tu computadora
Abrir Cursor
File → Open Folder (o Cmd/Ctrl + O)
Navegar a la carpeta del proyecto y seleccionarla
Cursor cargará toda la estructura del proyecto en el Explorer
Opción B: Clonar un proyecto desde GitHub
Si alguien te comparte un link de GitHub (ejemplo: https://github.com/empresa/proyecto) o bien tenés el repositorio en tu cuenta de Github.
Abrir Cursor
Presionar Cmd/Ctrl + Shift + P para abrir Command Palette
Escribir "Git: Clone" y seleccionar / o pegar la URL del repositorio (si no tenés vinculada tu cuenta de Github te lo va a requerir).
Elegir dónde guardar el proyecto en tu computadora
Cursor clonará el proyecto y lo abrirá automáticamente
Ambientes: Development, Staging y Production
Los proyectos de software modernos funcionan en diferentes "ambientes" o entornos. Cada uno tiene un propósito específico.
1. Development (Desarrollo Local)
¿Qué es?
Tu proyecto corriendo en tu computadora
Solo vos podes podes verlo
Debería estar conectado a bases de datos de prueba (no reales)
¿Cuándo se usa?
Mientras desarrollás nuevas features
Para hacer pruebas rápidas
Para experimentar sin miedo a romper nada
Características:
URL típica: http://localhost:3000
Se actualiza instantáneamente cuando guardás cambios
Errores detallados visibles en consola
Usa datos de prueba (mock data o test database)
Comando típico: npm run dev
Variables de entorno: Archivo: .env.local o .env.development
2. Staging (Pre-Producción)
¿Qué es?
Copia casi idéntica a producción
Publicada en internet, pero privada
Ambiente para testing final antes de lanzar a usuarios
¿Cuándo se usa?
Para QA testing con el equipo
Para demos con stakeholders
Para validar que todo funciona antes de production
Para probar integraciones con servicios externos
Características:
URL típica: https://staging.miapp.com o https://miapp-staging.vercel.app
Puede tener autenticación para limitar acceso
Usa una base de datos separada (staging database)
Los datos son similares a producción pero no reales
¿Cómo llega código acá? Generalmente al hacer merge a una branch especial (ej: staging o develop), o al crear un PR hacia main.
3. Production (Producción)
¿Qué es?
El ambiente real, donde están los usuarios finales
Todo debe funcionar perfectamente acá
Cambios en producción deben ser cuidadosos y probados
¿Cuándo se usa?
Es el producto final que los clientes usan
Solo se actualiza con código aprobado y testeado
Características:
URL típica: https://miapp.com o https://app.miapp.com
Público (o accesible para usuarios registrados)
Usa la base de datos real con datos de clientes
Performance optimizada
Monitoreo de errores activo
¿Cómo llega código acá? Al hacer merge a main y aprobar el deploy, o mediante un release manual.
Variables de entorno: configurado en plataforma de deploy
Uso de la terminal
La terminal integrada permite ejecutar comandos, ver logs en tiempo real y copiar errores para analizarlos con el agente.
Para qué sirve
Correr el proyecto.
Ver logs y errores.
Instalar dependencias.
Ejecutar scripts del proyecto.
Copiar partes del output y pegarlas en el chat para que la IA las explique o solucione.
Comandos típicos
npm install → instala dependencias (Node/JavaScript).
npm run dev → inicia el proyecto en modo desarrollo.
npm run build → prepara una versión final, revisa que no haya errores.
Nota: No todos los proyectos usan npm, pero sí una herramienta similar. Ejemplos análogos:
Localhost (qué significa)
Cuando corrés un proyecto localmente, suele abrirse una dirección tipo:
Esto significa que el proyecto está corriendo en tu computadora, no en internet.
Conceptos básicos de Git
Git es la herramienta que permite versionar código y sincronizarlo con repositorios como GitHub. Siempre que trabajes en el código, vas a estar trabajando en local (en tu computadora).
Al trabajar en equipo, es importante siempre tener actualizado tu repositorio local en comparación con lo que puede estar online por un cambio hecho por otra persona. Para esto hay que hacer Pull.
De forma análoga, cuando realizas un cambio en tu repositorio local, nadie lo verá a menos que hagas un commit de tu cambio y lo pushees.
a. Commit
Un commit es un “guardar” los cambios realizados del proyecto.
Debe tener un mensaje corto:
"Arreglo del botón de login"
"Creación del componente Header"
b. Push
Sube tus commits a un repositorio remoto (GitHub, GitLab).
c. Pull
Descarga la última versión del código que otros subieron.
d. Branches
Son líneas de trabajo separadas.
main: la rama principal y más estable.
Otras ramas: sirven para crear nuevas features sin afectar main.
Ejemplo:
Crear rama nueva: feature/nuevo-header
git checkout main desde main
git checkout -b feature/nuevo-header crear y moverse a la rama
git checkout main volver a main
Uso del agente con contexto
El agente puede entender el proyecto completo y ayudarte a:
Explicar código existente.
Generar archivos nuevos.
Proponer implementaciones.
Buscar errores.
Resumir una carpeta específica.
Es muy importante siempre darle el mayor contexto posible. Sin necesidad de leer código, un buen hack es buscar un copy (texto) que sea parte de la funcionalidad, buscarla en la sección del Explorer y marcar esa parte del código y command/control+I para llevar ese contexto al chat.
De forma análoga se puede escribir @ y el nombre del archivo que la contiene para darle ese marco de trabajo.
Ejemplos de prompts útiles
"Necesito mejorar @Header que muestre un título Y y un botón X. Crealo y agregalo a la carpeta components."
"Explicame cómo funciona @authService.js en detalle."
"Detectá qué está rompiendo el flujo de onboarding y proponé soluciones."
"Convertí este archivo a TypeScript." (pegando el contenido)
Nota: El agente siempre responde mejor cuando le das contexto claro.
API Keys, .env.local y configuración segura
Qué es una API Key
Una API Key es un código privado que te da acceso a un servicio externo (por ejemplo: OpenAI, Stripe, Supabase, Firebase).
Funciona como una contraseña que autoriza tu proyecto a usar ese servicio.
Puntos clave:
Son secretas (NO deben publicarse).
Identifican quién hace las solicitudes.
Tienen permisos y límites asociados.
Qué es un archivo .env.local
Es un archivo donde se guardan todas las claves privadas y configuraciones sensibles del proyecto.
Ejemplo típico:
OPENAI_API_KEY=sk-1234...
SUPABASE_URL=https://xyz.supabase.co
SUPABASE_KEY=abcd1234
Para qué sirve
Mantener secretos fuera del código.
Evitar que las claves aparezcan en GitHub.
Permitir que cada persona tenga su propia configuración local sin romper nada.
⚠️Regla de oro
El archivo .env.local NUNCA se sube a Git.
Tiene que estar en el .gitignore del proyecto.
Cómo usar .env.local en Cursor
Crear un archivo llamado .env.local en el directorio de archivos del proyecto.
Pegar las variables necesarias.
Reiniciar el servidor (npm run dev) para que tome los cambios.
Cómo se acceden las variables en el código
Depende del framework, pero la lógica típica es:
Backend (Node, Next.js):
const apiKey = process.env.OPENAI_API_KEY;
Frontend (Next.js requiere prefijo NEXT_PUBLIC_):
const publicKey = process.env.NEXT_PUBLIC_ANALYTICS_ID;
⚠️ Si no tiene NEXT_PUBLIC_, NO debe usarse en frontend. Significa que es privada.
Errores comunes y cómo resolverlos
No funciona npm run dev → suele faltar una dependencia → correr npm install.
No carga el proyecto en localhost → verificar el puerto que aparece en la terminal.
Errores sin explicación después de abrir el proyecto → muchas veces es porque no hiciste git pull antes de empezar.
Conflictos de Git → copiar el conflicto y pedirle al agente una explicación y sugerencia.
Archivo no encontrado → revisar ubicación en el Explorer.
Testing QA y reporte de errores probando en local
console.log() es una herramienta muy simple para “ver” qué está pasando dentro del código mientras el proyecto corre. Esta bueno cuando desarrollan una funcionalidad y sucede lo que se espera, pedirle al Agent que agregue logs.
Es un comando que imprime información en la terminal o consola del navegador mientras el proyecto corre.
Ejemplo: console.log("Valor del usuario:", user);
Dónde lo ves
En la terminal de Cursor si corre en backend.
En la consola del navegador si es frontend (Chrome → Inspect → Console).
Sirve para confirmar hipótesis:
“¿Está llegando este dato?”
“¿Este botón realmente dispara la función?”
“¿Por qué no se actualiza este valor?”
Cómo reportar de manera sólida cuando algo “no me gusta” o no funciona
Usar logs ayuda a reportar problemas con mucha más precisión.
Estructura recomendada para reportes:
Qué esperabas que pase.
Qué pasó realmente.
Cómo lo reprodujiste (pasos).
Qué info viste en consola (si agregaste logs).
Adjuntar el fragmento del log o screenshot.
Ejemplo:
“Al hacer clic en Guardar, esperaba ver el modal, pero no aparece.
Agregué un log en handleSave() y vi que la función sí se ejecuta pero la variable isOpen viene en false.”
Auditoría básica de seguridad
Esta sección te da un checklist simple para evitar errores comunes de seguridad, especialmente cuando pedís cambios al agente o editás código.
1. Claves privadas nunca en el código
Si ves algo así: const OPENAI_API_KEY = "sk-123...";
Alertar: eso es un error grave.
Moverlo a .env.local.
Pedir al agente: "Auditá el proyecto para asegurar que no haya claves expuestas."
2. Revisión de endpoints públicos
Todo lo que se expone en /api/... debe evitar:
Enviar claves privadas al frontend.
Responder más datos de los necesarios.
Permitir acciones sin autenticación si no corresponde.
Pedir al agente: "Revisá estos endpoints y decime si hay riesgos de exponer datos sensibles."3. Revisar permisos de usuario
Especialmente si el proyecto tiene login, admin, roles, etc.
Checklist rápido:
¿El backend valida permisos?
¿Hay datos que solo deberían ver usuarios autenticados?
¿Hay endpoints sin protección?
4. Evitar logs sensibles
console.log() NO debe imprimir:
Tokens
Passwords
API keys
Datos personales de usuarios
Ejemplo incorrecto: console.log("JWT:", token);
Solución: pedir al agente "Auditá el uso de console.log y decime si hay datos sensibles expuestos."
5. Uso de dependencias
Correr: npm audit
Sirve para revisar vulnerabilidades conocidas.
Pedir al agente: "Explicame los riesgos reportados por npm audit y si debemos actualizar algo."
Flujo de trabajo recomendado (paso a paso real)
Actualizar el proyecto: git pull.
Instalar dependencias si corresponde: npm install.
Levantar entorno local: npm run dev.
Escribir una buena prompt y pedirle a Cursor agent que haga un Plan de mejora (Plan mode).
Hacer cambios
Revisar en localhost.
Preguntarle al agente si todo está consistente y seguro.
Generar build final: npm run build.
Stage de cambios en Source Control.
Commit con mensaje claro.
Push.
Cómo se ve todo esto en GitHub
GitHub es la “vista web” del proyecto: todo lo que hacés en Cursor (commits, ramas, cambios) termina representado ahí. No hace falta operar GitHub a diario, pero sí conviene entender qué se ve y por qué.
1. Commits
Cuando hacés un commit en Cursor:
GitHub muestra ese commit como un registro en el historial.
Incluye un mensaje, la fecha y los archivos modificados.
Podés abrirlo y ver exactamente qué cambió (línea por línea, con verde y rojo).
Para qué sirve:
Te permite revisar qué pasó en cada cambio y entender la evolución del proyecto.
2. Ramas (Branches)
Si creás una rama nueva en Cursor (ej. feature/nuevo-header), GitHub la muestra como una línea separada del trabajo principal (main).
Es útil para seguir el progreso aislado sin afectar el código productivo.
Buenas prácticas:
Crear ramas por feature.
Mantener main limpio y funcional.
3. Pull Requests (PRs)
Un Pull Request (PR) es una solicitud para unir tu rama con main.
En GitHub podés:
Ver el resumen del cambio.
Ver el detalle de archivos modificados.
Leer y hacer comentarios.
Aceptar o pedir ajustes.
Es ideal para revisar cambios con el equipo y validar algo antes de integrarlo.
4. Merge
Cuando el PR se aprueba:
Se hace merge: se combinan los cambios en main.
La rama queda integrada y, si querés, puede eliminarse.