Caso de estudio 4: Un sitio de contenido que no tienes que atender

La idea

Un aficionado quería convertir una carpeta de notas en Markdown —reseñas de restaurantes de años de viajes— en un sitio público con capacidad de búsqueda, sin ningún CMS (Content Management System) en el que iniciar sesión y sin factura mensual. Agregar una nota, hacer push, listo.

La especificación

A static site generated from a folder of Markdown files, one file
per review (title, city, rating, body in frontmatter). Build a
homepage that lists reviews newest-first, a page per review, and
client-side search by city or name. No database, no login, no
build step I have to run by hand. Pushing a new .md file should
publish it.

El requisito oculto está en la última frase. "No build step I have to run by hand" (ningún paso de construcción que tenga que ejecutar a mano) significa que la especificación en realidad trata del flujo de trabajo, no solo del resultado, y los requisitos de flujo de trabajo son de los que las IA se saltan a menos que los nombres, porque no aparecen en la aplicación en funcionamiento.

La pila tecnológica

Un generador de sitios estáticos que lee Markdown en tiempo de construcción, desplegado en un host de CDN con construcciones activadas por Git. Se hace push al repositorio, el host reconstruye, la CDN lo sirve. La búsqueda es del lado del cliente sobre un pequeño índice JSON generado en la construcción, así que no hay servidor ni costo de consulta: un buen intercambio con unos pocos cientos de reseñas, y uno que nombramos deliberadamente en lugar de descubrirlo por accidente.

Todo el flujo de trabajo es una sola flecha: un push activa una construcción que publica. No se ejecuta nada en el momento de la solicitud, salvo el propio navegador del visitante filtrando un índice:

  add review.md          ┌──────────────────┐
  git push  ───────────▶ │  CDN HOST        │
                         │  build step:     │
                         │  read all *.md   │──▶ static HTML pages
                         │  emit search.json│──▶ tiny search index
                         └────────┬─────────┘
                                  │ serves
                                  ▼
                         ┌──────────────────┐
                         │  VISITOR BROWSER │  filters search.json
                         │  (client-side)   │  locally — no server
                         └──────────────────┘
        no database · no login · no build step run by hand

Los prompts clave

Anclamos a la IA a la forma de los datos primero, antes de cualquier interfaz:

Set up a static site that reads every .md file in /reviews. Each
file's frontmatter has title, city, rating (1-5), date. Parse all
of them at build time into a sorted list (newest first) and
generate: a homepage listing them, and one page per review at
/reviews/<slug>. Show me the data-loading code first, before any
styling.

"Before any styling" (antes de cualquier estilo) es una palanca deliberada. Pide todo de una vez y obtienes una página hermosa conectada a datos en los que no puedes confiar; pide primero la capa de datos y puedes verificar los cimientos antes de que un solo píxel te distraiga. Luego la búsqueda, acotada para mantenerla barata:

Generate a search.json at build time with {title, city, slug} for
every review. On the homepage, add a search box that filters the
visible list client-side by matching city or title — no network
calls, just filter the already-loaded index. Keep it under 50
lines of JS.

El obstáculo

La construcción pasaba en local, pero el sitio desplegado devolvía 404 en cada página individual de reseña. La página principal funcionaba; las páginas de reseñas individuales no. Pegamos el síntoma y la configuración en lugar de teorizar:

Homepage works live, but /reviews/<slug> pages all 404 in
production while working in local dev. Here's my build output
directory listing and my host's deploy config: [pasted]. Why does
local dev serve these pages but production doesn't?

The AI traced it to the difference between dev-server routing (which
resolves paths dynamically) and static hosting (which serves only
files that physically exist). The build was generating the review
pages into the wrong output folder, so they never got uploaded —
dev had hidden the bug because its router faked the routes that
production couldn't.

Apuntamos el directorio de salida hacia lo que el host realmente desplegaba, las páginas aparecieron, y añadimos una línea a la lista de verificación de lanzamiento: hacer clic en un enlace profundo en el sitio en vivo, no solo en la página principal. La lección más amplia es que "funciona en desarrollo" y "funciona desplegado" son afirmaciones distintas, y la exportación estática es justo donde divergen: los servidores de desarrollo son indulgentes con las rutas de una forma en que el alojamiento real basado en archivos nunca lo es.

El lanzamiento

Publicamos una reseña real, vimos al host reconstruir, y cargamos un enlace profundo a esa reseña específica en el dominio en vivo, exactamente el caso sobre el que desarrollo había mentido. Luego buscamos su ciudad para confirmar que el índice la había recogido. Añadir la siguiente reseña fue un commit de una sola línea, que era todo el punto: el lanzamiento no fue un momento, fue un flujo de trabajo que sigue funcionando sin nosotros.