如何為 Claude Code 建立安全的資料庫遷移技能

Pide a cualquier asistente "renombra la columna nombre a nombre_completo" y lo más probable es que genere un ALTER TABLE ... RENAME COLUMN. Funciona en tu máquina. En producción, el código que sigue desplegado busca nombre y empieza a fallar hasta que termine el despliegue.

En este tutorial vas a crear una skill de Claude Code que le enseña a hacer migraciones seguras por defecto.

Qué es una skill

Una skill es una carpeta con un archivo SKILL.md dentro de .claude/skills/ (en tu proyecto) o ~/.claude/skills/ (para todos tus proyectos). El archivo empieza con un frontmatter YAML:

---
name: migraciones-bd
description: "Crea y revisa migraciones de base de datos seguras para producción (sin bloqueos largos, sin pérdida de datos, reversibles y compatibles con el código desplegado). Úsala cuando el usuario pida crear una migración, cambiar el esquema, renombrar o borrar columnas, añadir índices o revisar una migración existente."
---

La description es la parte más importante: Claude Code la usa para decidir cuándo cargar la skill. Escríbela con las frases que de verdad usas ("renombra esta columna", "añade un índice"). Debajo del frontmatter va el método, en Markdown.

El método: expandir y contraer

La idea central es que, durante un despliegue, conviven la versión actual del código y la nueva, así que el esquema debe servir a las dos. En la skill lo expresamos como una tabla que Claude puede consultar:

| Operación | Forma segura |
|---|---|
| Añadir columna | Nullable o con default constante. Luego rellenar en lotes. Luego `NOT NULL` si hace falta |
| Renombrar columna | Añadir nueva → escribir en ambas → rellenar → leer de la nueva → (otro despliegue) borrar la vieja |
| Borrar columna | Primero dejar de usarla en el código y desplegar; después borrarla en otra migración |
| Añadir índice | PostgreSQL: `CREATE INDEX CONCURRENTLY` (fuera de transacción) |

Así, ante "renombra la columna", Claude propone un cambio en fases y el orden de despliegue.

Una checklist que obliga a pensar

Las instrucciones vagas ("ten cuidado con las migraciones") no cambian nada. Las preguntas concretas sí:

- [ ] ¿Bloquea la tabla mucho tiempo (reescritura, índice no concurrente, validación completa)?
- [ ] ¿Puede perder datos (`DROP`, truncar tipo, `NOT NULL` sin rellenar)?
- [ ] ¿El código actualmente en producción sigue funcionando tras aplicarla?
- [ ] ¿Tiene reversión y se ha probado `up` → `down` → `up` en local?

Pide también el SQL real que generará el ORM (alembic upgrade --sql, python manage.py sqlmigrate): muchos problemas solo se ven ahí.

Límites explícitos

Termina la skill con lo que nunca debe hacer sin tu permiso: ejecutar migraciones fuera de local, migrate:fresh, db:reset, prisma migrate reset o cualquier DROP. Una skill orienta a Claude, pero no es una barrera técnica: si quieres bloquear comandos de verdad, combínala con reglas deny en .claude/settings.json.

Pruébala

1. Guarda el archivo en .claude/skills/migraciones-bd/SKILL.md.
2. Abre una sesión nueva de Claude Code.
3. Pide: "Necesito renombrar usuarios.nombre a nombre_completo".

Si la skill se activó, verás un plan en fases, la migración de la primera fase, el SQL generado y el orden de despliegue, en lugar de un RENAME directo.

¿Te sirvió? Este ejemplo es parte del Pack 8 Skills Avanzadas para Claude Code (en español): paga lo que quieras, desde 1 USD. Más recursos gratis en GitHub.