Trabajar con Cursor dentro de un contenedor Docker te permite desarrollar en un entorno casi idéntico al de producción, mejorar el contexto que recibe la inteligencia artificial y obtener generación de código más precisa. Esta guía está pensada para desarrolladores que ya tienen un Docker Compose corriendo y quieren llevar su flujo de trabajo al siguiente nivel.

Por qué desarrollar dentro de un contenedor con Cursor

La idea central es simple: si tu servicio se ejecuta en producción dentro de un contenedor, tu entorno de desarrollo debería parecerse lo más posible a ese escenario. Y aquí viene lo interesante, Cursor es un fork de Visual Studio Code, así que todas las extensiones del marketplace de VS Code funcionan sin cambios.

Al conectar el editor al contenedor, le das a la IA acceso al mismo intérprete, dependencias y configuración que correrá tu API. Eso se traduce en sugerencias más alineadas con tu stack real.

¿Por qué importa el contexto en Cursor? Porque la calidad del código generado depende de la información que la IA puede leer: tipos, sintaxis del lenguaje y dependencias instaladas. Más contexto, mejor código.

Cómo conectar Cursor a un contenedor en ejecución

Antes de conectar el editor, conviene levantar el entorno con un solo comando. Un Makefile con make start simplifica el proceso, y con docker ps puedes confirmar que los contenedores del proyecto están corriendo.

Luego sigue estos pasos dentro de Cursor:

1. Abre la sección de extensiones e instala Dev Containers, la extensión que permite adjuntar el editor a un contenedor.
2. Ejecuta Command + Shift + P y busca Attach to Running Container.
3. Selecciona el contenedor que te interesa, en este caso el de la API.
4. Verifica abajo a la izquierda que aparezca el nombre del contenedor, por ejemplo backend API.

Una vez conectado, abre la carpeta del proyecto. Para saber dónde está montado el código, revisa la sección de volumes en tu docker-compose.yml. Si las carpetas se copian a /app/app, ese es el folder que debes abrir con Open Folder.

Qué extensiones instalar para mejorar el contexto de la IA

Una vez Cursor vive dentro del contenedor, la interfaz se ve igual que siempre, pero las extensiones se instalan en ese entorno aislado. Necesitas reinstalar las herramientas que dan contexto al lenguaje.

Python y Pylance como base del tipado

Las dos extensiones imprescindibles para un proyecto Python son:

• Python, la extensión oficial de Microsoft con más de 170 millones de descargas.
• Pylance, que se instala automáticamente con Python y funciona como Language Server Protocol (LSP).

Pylance es quien detecta errores de sintaxis, problemas de tipado y rutas de importación rotas. Si al abrir un archivo ves un error como FastAPI no se puede importar, casi siempre se resuelve eligiendo el intérprete de Python correcto desde la barra inferior derecha.

¿Qué es un LSP? Es un protocolo que conecta el editor con un servicio de lenguaje para reportar errores, sugerir autocompletado y validar tipos en tiempo real.

Cómo arreglar dependencias no encontradas en el contenedor

Si el error persiste después de seleccionar el intérprete, significa que las dependencias del proyecto no están instaladas en el Python global del contenedor. La solución va dentro del Dockerfile: agrega una variable de entorno que indique a uv dónde debe instalar las dependencias del proyecto.

Después de modificar el Dockerfile, ejecuta make build para reconstruir la imagen. Ten en cuenta una diferencia clave:

• Cuando solo reinicias un contenedor, las extensiones instaladas se conservan.
• Cuando reconstruyes la imagen, debes volver a instalar las extensiones dentro del nuevo contenedor.

Cómo configurar correctamente el workspace

Un detalle que suele pasar desapercibido es la carpeta que abres como workspace. Si abres una ruta que no contiene el pyproject.toml o el archivo de dependencias, Pylance no podrá resolver las importaciones aunque todo esté instalado.

Para corregirlo:

1. Usa Add Folder to Workspace y selecciona la carpeta correcta, normalmente /app.
2. Remueve del workspace el folder anterior que generaba conflicto.
3. Espera a que el entorno se reinicie y valida que los errores desaparezcan.

Desde Docker Desktop puedes confirmar que la API sigue corriendo y revisar los logs. Si haces una petición a localhost:8000, el servicio responderá igual que antes, solo que ahora estás editando el código directamente dentro del contenedor.

Qué gana tu flujo al desarrollar dentro del contenedor

La ventaja real no es solo organización: es que Cursor recibe el mismo contexto que tendrá el servicio en producción. Pylance ve los tipos reales, el plugin de Python conoce las versiones exactas y la IA genera código alineado con ese entorno.

Esto reduce los típicos funciona en mi máquina y te acerca a un desarrollo donde la generación con inteligencia artificial entiende tu proyecto a fondo. Con esta base lista, el siguiente paso natural es empezar a construir los endpoints del servicio.

¿Ya estás trabajando con Dev Containers en tus proyectos? Cuéntame en los comentarios qué extensiones consideras imprescindibles dentro del contenedor.