Caso de estudio
Este sitio: un CV listo para agentes
Sitio estático bilingüe (Astro + Tailwind CSS) que publica los datos del CV como HTML, JSON-LD y resume.json, con búsqueda semántica en el dispositivo, tools WebMCP para agentes de IA y CV en PDF/DOCX generados en el build.
- Empresa
- Oscar Arenas
- Periodo
- 2025 – actualidad
- Mi rol
- Diseño, ingeniería y contenido
El problema
Los reclutadores y sus agentes de IA necesitan datos del CV que puedan leer, verificar y consultar, no solo un PDF.
Enfoque y arquitectura
Un único módulo de datos tipado alimenta todas las superficies (página, JSON-LD, resume.json, archivos del CV y tools para agentes); la búsqueda y las tools corren en el navegador contra los datos publicados.
-
Datos
- resume.ts y projects.ts: contenido tipado y bilingüe
- Validación con un esquema Zod antes de cada build (npm run validate)
-
En el build
- Embeddings de los pasajes calculados con multilingual-e5-small (int8)
- Astro genera las páginas EN/ES con JSON-LD, resume.json, llms.txt y tarjetas sociales
- Archivos del CV: Puppeteer imprime el PDF y html-to-docx genera el Word
-
Hosting
- Firebase Hosting sirve el build estático; el sitio no necesita un servidor de aplicación para funcionar
-
En el navegador
- Las tools WebMCP y los formularios HTML normales trabajan sobre los datos publicados
- Búsqueda semántica en un Web Worker: Transformers.js solo procesa la consulta del visitante
Cada paso es un archivo o un script del repositorio de este sitio.
Arquitectura
- Sitio estático en Astro, en inglés y español; un único módulo de datos tipado (resume.ts) alimenta el HTML, el JSON-LD, resume.json, los generadores de PDF/DOCX y las tools para agentes.
- Búsqueda semántica en el dispositivo: los embeddings de los pasajes (multilingual-e5-small) se calculan en el build y en el navegador solo se procesa la consulta del visitante, con Transformers.js sobre WebAssembly.
- 19 tools WebMCP: 12 tools imperativas registradas con document.modelContext (navigator.modelContext en versiones anteriores de los navegadores; también disponibles como window.oscarResume) y 7 tools declarativas <form toolname> que además funcionan como formularios HTML normales.
- Generación del CV: Puppeteer imprime la ruta /print/ a PDF (una versión general y dos por enfoque) y html-to-docx genera el archivo Word, en ambos idiomas, en cada versión; todos ellos, y el CV en Markdown, salen de un único modelo del CV (scripts/lib/cv-model.ts).
- Controles de calidad: pruebas unitarias con Vitest, pruebas end-to-end y de accesibilidad (axe) con Playwright, presupuestos de Lighthouse CI y una verificación de regresiones del CV, en GitHub Actions.
Decisiones clave y sus compromisos
- Estático primero: todas las capacidades para agentes corren en el navegador contra resume.json, así que el sitio no necesita un servidor para funcionar.
- Los vectores de los pasajes se calculan en el build y el modelo de ~135 MB solo se descarga cuando el visitante activa la búsqueda semántica, así nunca bloquea el renderizado ni consume datos por defecto.
- El JSON-LD se genera con los mismos datos que la página, así buscadores y agentes ven los mismos datos que las personas.
- Un esquema Zod valida los datos del CV antes de cada build, así las fechas rotas o las traducciones faltantes detienen el build en lugar de publicarse.
- Construido con programación y revisión asistidas por IA (Claude Code), con TypeScript estricto y esa validación del contenido antes de cada build.
Resultado
19 tools para agentes y CV en 2 idiomas en PDF (3 versiones por enfoque), Word y Markdown, generados con los mismos datos en cada versión.
Datos clave
- 19 tools para agentes
- 2 idiomas, 10 archivos de CV por versión (6 PDF, 2 Word, 2 Markdown)
Tomados del CV, sin estimaciones.
Mi rol
Diseño, ingeniería y contenido
Stack
- Astro
- TypeScript
- Tailwind CSS
- Transformers.js
- WebMCP
- JSON-LD
- Puppeteer
- Playwright
- Vitest
- GitHub Actions
- Lighthouse CI
- Firebase Hosting
Enlaces
- Sitio en vivo resume-oscarenas.web.app/