Construir un backend desde cero con Cursor se vuelve mucho más ordenado cuando documentas cada iteración dentro del propio repositorio. Aquí te muestro cómo iniciar el setup de Platzi Flix usando prompts secuenciales, modo Agente y buenas prácticas de contexto, ideal si estás aprendiendo a programar con IA y quieres mantener el control del código.

¿Por qué documentar las iteraciones dentro del proyecto?

La idea es que la documentación viva al lado del código. Para eso creas una carpeta specs y dentro guardas archivos Markdown numerados, como 01-setup.md, que funcionan como prompts reutilizables.

Este archivo no es un README cualquiera. Es un prompt estructurado donde le explicas a la inteligencia artificial el contexto del proyecto y los pasos secuenciales que debe seguir para construirlo. Así, cualquier persona que abra el repo entiende qué se pidió y en qué orden [0:30].

¿Qué es un archivo de specs en un proyecto con IA? Es un Markdown que contiene el prompt y los pasos ordenados que la IA debe ejecutar. Sirve como documentación viva y como instrucción reutilizable.

¿Cómo se usa el chat de Cursor con contexto?

Para abrir el chat en Mac usas Command + Shift + P y escribes chat new. Cursor detecta automáticamente el archivo abierto y lo toma como contexto, pero puedes sumar más archivos con el símbolo arroba (@) [1:40].

Dentro del chat encuentras varios modos de conversación:

• Agente: planifica, busca y construye. Es el recomendado para ejecutar pasos secuenciales.
• Preguntar: ideal para dialogar y resolver dudas sobre el código sin modificarlo.
• Arroba (@): te despliega símbolos para agregar archivos, carpetas o búsquedas web como contexto.

En este flujo conviene mencionar dos veces el mismo archivo si quieres reforzar su importancia. Por ejemplo, agregar el README.md que ya existía y volver a citar setup.md para que la IA priorice esos pasos.

¿Cómo se le indica a Cursor que analice antes de ejecutar?

La clave está en separar tres momentos: analizar, planificar y ejecutar. En el prompt inicial defines reglas explícitas como estas [3:20]:

1. No seguirás con los siguientes pasos hasta que yo te lo indique.
2. Planificarás las acciones antes de ejecutarlas.
3. Solo cuando diga ejecutar, aplicarás los cambios.

Este patrón te da control. Cursor te muestra el plan, tú lo revisas, ajustas si algo no encaja con tu estructura y luego das luz verde.

¿Qué hacer si Cursor propone algo que ya existe?

En el paso uno, Cursor quiso crear una carpeta raíz Platzi Flix, pero el proyecto ya tenía una carpeta backend. Bastó con responder utiliza la carpeta backend para que ajustara el plan sin recrear nada [4:50]. Lo mismo pasó con pyproject.toml: al avisarle que el archivo ya estaba creado, replanificó para editarlo en lugar de generarlo de nuevo.

¿Cómo aceptar o rechazar cambios en archivos?

Cada vez que Cursor edita un archivo te pide confirmación con dos botones: accept o reject. Si das reject, puedes volver a aplicar el cambio desde el historial del chat usando la opción reaplicar. Esta red de seguridad evita que la IA dañe tu base de código sin que puedas revertirlo [6:40].

¿Cómo validar decisiones técnicas con búsquedas web?

En el paso tres, la propuesta de usar Pydantic Settings no convencía. Aquí entra otro símbolo poderoso: @web, que permite a Cursor buscar en Internet y citar fuentes [8:10].

El prompt fue directo: busca cuál es la configuración adecuada para crear settings de un proyecto de FastAPI. Cursor regresó con enlaces a la documentación oficial de FastAPI y confirmó que Pydantic Settings es la práctica recomendada para manejar variables de entorno y configuración centralizada.

¿Para qué sirve el símbolo @web en Cursor? Activa búsquedas en Internet y devuelve fuentes consultables, útil para validar decisiones técnicas con documentación oficial.

¿Cómo se levanta el servidor de FastAPI con uv?

El paso cinco implica crear el entorno virtual y correr la aplicación. Se le pidió explícitamente usar uv python en la versión 3.12 [10:30]. El plan que ejecutó Cursor incluyó:

• Crear el entorno virtual con uv.
• Activar el entorno con source .venv/bin/activate.
• Sincronizar dependencias con uv sync (equivalente a un pip install).
• Ejecutar la aplicación de FastAPI.

¿Qué hace Cursor cuando un comando falla?

En el modo Agente, Cursor detecta errores y los corrige en el siguiente comando. Pasó cuando el pyproject.toml no estaba en la ruta esperada: entró a la carpeta correcta, reactivó el entorno y volvió a sincronizar [11:50].

Al abrir el navegador apareció un error porque faltaba uvicorn, el servidor que corre FastAPI. La solución fue manual y rápida:

bash source .venv/bin/activate uv add uvicorn

Después de eso, el servidor encendió y la API de Platzi Flix respondió en el navegador con su mensaje de bienvenida y el endpoint /health operativo.

Estructura final del backend tras los cinco pasos

Al cerrar esta primera iteración, tu carpeta backend queda con la base lista para escalar:

• pyproject.toml con la sección de dependencias preparada para uv.
• app/main.py con la aplicación de FastAPI, el endpoint raíz y /health.
• app/core/config.py con la clase de settings basada en Pydantic Settings.
• app/db/base.py listo para la capa de base de datos.
• Entorno virtual .venv activo y sincronizado.

¿Cómo modificarías tú el prompt del setup.md para que ya incluya las fases de analizar, planificar y ejecutar sin tener que repetirlas en el chat? Déjame tu versión en los comentarios.