Migré mi blog de WordPress a Astro en unas horas usando Claude

Mi blog llevaba en WordPress desde 2017. Funcionaba. Tenía sus posts, su tema Vantage, su sidebar con widgets que nadie miraba. Pero con el tiempo fui acumulando deuda: sin control de versiones para el contenido, sin tiempo de lectura en las tarjetas, sin modo oscuro, con el código resaltado por un plugin que rompía en posts antiguos y cada vez más lento por falta de actualizaciones. Sin soporte multiidioma.

Lo que me hizo decidirme fue algo más simple: quería editar un post y no tenía forma de hacerlo desde el editor de texto donde trabajo. Abrir el admin de WordPress para cambiar tres frases es la gota que va sumando hasta que un día dices basta.

Decidí reconstruirlo con Astro.

Lo que cambié en la forma de trabajar

Normalmente cuando construyo algo empiezo a escribir código y voy tomando decisiones sobre la marcha. Con este proyecto fui a la inversa: primero documentar, luego construir.

El resultado es que el docs/ del repositorio tiene tres brainstorms y tres planes que explican exactamente por qué el proyecto tomó las decisiones que tomó. Por qué columna única en vez de sidebar. Por qué prefixDefaultLocale: false para el i18n. Por qué los posts en español viven en / y los ingleses en /en/ en vez de al revés.

Esa documentación no es solo para referencia futura. Fue la entrada del proceso de construcción: Claude leyó esos documentos para entender el contexto antes de escribir código.

El proceso: brainstorm → plan → build

Usé Claude Code con el plugin VGV Wingspan, que estructura el trabajo en tres fases:

1. /brainstorm — explorar el problema, tomar decisiones de diseño, documentar razonamientos
2. /plan — convertir el brainstorm en un plan de implementación concreto con fases, criterios de aceptación y riesgos
3. /build — construir ejecutando el plan paso a paso

El brainstorm es el paso más importante. Con un prompt simple — “quiero migrar mi WordPress a Astro y Tailwind manteniendo mis posts” — Claude no empezó a generar código. Empezó a hacer preguntas.

¿Quería sidebar o columna única? ¿El idioma por defecto debería ser español o inglés? ¿Los posts antiguos tenían imágenes que valía la pena migrar?

Una que me hizo pensar: ¿quieres que el español esté en / y el inglés en /en/, o al revés? No lo había considerado. Pero la respuesta define la URL canónica del sitio, la configuración de i18n y cómo indexan los buscadores. Tener que responderla antes de escribir una línea de código fue exactamente lo correcto.

Al final tenía la idea clara: Astro v5, Tailwind CSS v4, columna única, modo oscuro con prefers-color-scheme, posts como archivos Markdown en el repositorio, español por defecto e inglés en /en/.

El plan fue más extenso — seis fases desde la configuración inicial hasta el despliegue, con gotchas documentados de Astro v5 y de Tailwind v4. Esos gotchas los encontré después en la práctica. El plan los tenía anotados de antemano.

Lo que se construyó

El /build ejecutó el plan fase a fase. En unas pocas horas desde el primer brainstorm: site estático completo, 19 posts migrados de WordPress a Markdown y traducidos al inglés, todas las páginas en ambos idiomas, modo oscuro, tiempo de lectura, Shiki para el código, RSS, sitemap y Open Graph por post.

Hubo un momento donde tuve que intervenir: la migración de contenido. Los 19 posts venían de un export de WordPress y había que limpiar el HTML, convertirlo a Markdown, añadir frontmatter, revisar imágenes. Claude ayudó con la estructura (básicamente hizo todo el trabajo), pero la revisión de cada post fue manual. El /build no te quita el trabajo de conocer tu propio contenido.

Las partes que me sorprendieron

Lo que más me sorprendió no fue el stack. Fue que Wingspan identificó los requisitos antes de que yo supiera que eran requisitos.

Al decirle que quería Astro v5 y Tailwind CSS v4, el brainstorm no asumió que yo conocía los cambios de las versiones más recientes. Investigó, documentó los puntos de ruptura y los convirtió en criterios de aceptación del plan:

• En Astro v5, entry.slug desapareció. El identificador ahora es entry.id. Un detalle que rompe todo el sistema de rutas si no lo sabes de antemano.
• Tailwind CSS v4 eliminó tailwind.config.js. La configuración es CSS-first, con @theme y @custom-variant. Si vienes de v3, el instinto es buscar un archivo que ya no existe.
• Al hacer git add con [slug] en el path, zsh interpreta los corchetes como un glob y falla. El plan decía: añade por directorio, no por archivo.

Ninguno de estos puntos formaba parte de mi prompt inicial. Yo pedí un blog con Astro y Tailwind. Wingspan preguntó las versiones, investigó las implicaciones y los convirtió en parte del plan antes de escribir una línea de código.

Eso es lo que diferencia un plan bien hecho de una lista de tareas.

Próximos pasos

De momento solo faltan los comentarios (probablemente Giscus) y la búsqueda (Pagefind como post-build step). Ninguno de los dos bloqueaba el lanzamiento, así que se quedaron fuera del alcance inicial.

Lo que sí funciona desde ya: abrir el editor de texto, crear un archivo .md con el frontmatter correcto, hacer commit, y el post aparece en el sitio en el siguiente deploy. Sin admin de WordPress. Sin plugins. Sin configuración. Y carga a la velocidad del viento.

Eso era lo que quería desde el principio.