Migrar una base de datos sin romper el servicio exige método, contexto y pruebas. Con Claude Code puedes orquestar migraciones en Docker, validar con unit tests y avanzar fase por fase de un plan de implementación bien definido, todo desde la terminal y con control humano sobre cada paso.

¿Cómo preparar el entorno local antes de migrar?

Antes de tocar la base de datos, el servicio tiene que estar corriendo. El archivo Makefile dentro de backend concentra los comandos clave para levantar el proyecto.

• make build construye la imagen y descarga los paquetes necesarios.
• make start inicia el servicio de API.
• make logs confirma que el contenedor encendió correctamente.

Una vez arriba, abres el navegador en localhost:8000 y verificas que el API responde. Ese ping inicial te ahorra horas de depuración más adelante.

¿Qué hace el comando make build? Construye la imagen de Docker del backend descargando todas las dependencias declaradas en el proyecto, dejando el contenedor listo para iniciarse con make start.

¿Cómo agregar un comando para ejecutar pruebas?

El Makefile original no traía un comando para correr pruebas dentro del contenedor. En lugar de escribirlo a mano, le pasas el archivo como contexto a Claude Code y le pides que cree un comando nuevo llamado test que ejecute Pytest dentro del contenedor de API [04:18].

Claude propone la edición, tú la apruebas y queda lista. Desde una nueva terminal, dentro de backend, corres make test y validas que el set de pruebas funcione.

¿Cómo resolver errores de dependencias en los tests?

La primera ejecución suele fallar. En esta base de código, los unit tests requerían dos paquetes que no estaban instalados: HTTPX y pytest-asyncio.

La solución fue añadirlos a las dependencias opcionales del proyecto y reconstruir con UV, el gestor de paquetes que usa este backend. Después de eso, los tests corrieron al 100%.

¿Qué es pytest-asyncio? Es un plugin de Pytest que permite ejecutar pruebas sobre funciones asíncronas de Python, indispensable cuando tu API usa async/await.

Este tipo de retos son perfectos para resolver con Claude Code: le das el error como contexto y te sugiere dónde ajustar el archivo de dependencias.

¿Cómo ejecutar la fase de migración con Claude Code?

El plan de implementación define fases con checklists claros. La fase uno es base de datos, y el flujo correcto es activar el plan mode antes de ejecutar nada [09:42].

¿Qué modos de ejecución ofrece Claude Code?

Claude Code tiene tres modos que cambias con Shift+Tab, cada uno con un nivel distinto de autonomía.

• Auto accept: acepta cualquier edición sin preguntar.
• Plan mode: planifica todo el flujo antes de tocar archivos, ideal para tareas críticas.
• Modo por defecto: pide confirmación antes de cada acción.

En una migración, el plan mode te deja revisar la estrategia completa antes de que Claude escriba una sola línea. Verás el contenedor que va a usar, la última migración aplicada y el patrón identificado.

¿Cómo darle el contexto correcto al agente?

Claude Code necesita ubicación y archivos específicos. Si mencionas un archivo que no encuentra, el problema casi siempre es el directorio actual.

Puedes activar el bash mode con el signo de exclamación para ejecutar comandos como pwd y orientarte. Cuando Claude no logra cambiar de carpeta por restricciones, lo más rápido es salir, navegar manualmente y reiniciar la sesión.

Una vez ubicado, le pasas el plan con @01-backend.md y le indicas que use los comandos del Makefile para reconstruir la imagen si hace falta. El agente entonces revisa contenedores activos, consulta el estado de Alembic, identifica la última migración y propone el plan completo.

¿Cómo validar que la migración no rompió el servicio?

Claude Code crea el archivo de migración, ejecuta los constraints, los índices y aplica todo en Postgres. El cierre de la fase llega cuando vuelves a correr los unit tests y todo sigue verde.

El agente además propone una verificación adicional con el endpoint de health y llamadas vía cURL a los endpoints principales. Esto convierte la validación en una mini prueba de integración:

1. Tests unitarios pasando dentro del contenedor.
2. Estado del contenedor activo.
3. Endpoints respondiendo con la estructura esperada.

Para mantener el plan de implementación sincronizado, conectas Claude Code con el editor, seleccionas el bloque del checklist y con Command+Option+K lo mencionas como contexto. Le pides marcar como finalizadas las tareas completadas y el agente actualiza los checks automáticamente.

¿Por qué importa cerrar cada fase con tests?

Una migración silenciosa puede romper consultas, modelos o relaciones sin previo aviso. Volver a ejecutar los unit tests después de cada cambio te garantiza que el contrato del API sigue intacto antes de pasar a la siguiente fase, como la creación de los modelos de SQLAlchemy.

¿Qué retos enfrentaste al implementar la fase dos con Claude Code? Déjalo en los comentarios.