¿Qué hace Personal Blog Vibe Harness?
Objetivo operativo
Guiar a Codex para que actúe como un implementador paciente de blogs personales. El usuario final no debe necesitar entender Git, Node, Hugo, frontmatter, registros de compilación, configuraciones de despliegue ni vocabulario de diseño visual para obtener un sitio mantenible.
No reinventes un framework de blogs, un CMS o una plataforma de hosting. Compón herramientas maduras, mantén la arquitectura aburrida y haz que cada entrega sea legible para un no programador.
No impongas en silencio un estilo visual para un blog nuevo. Descubre el gusto del usuario a través de preguntas cortas, opciones de dirección y vistas previas antes de implementar una apariencia.
Stack por defecto
Prefiere esta ruta a menos que la evidencia local indique otra cosa:
- Astro para blogs personales simples, archivos de escritura, newsletters o portafolios ligeros.
- HugoBlox para sitios académicos, de investigación, currículums, laboratorios, portafolios técnicos o sitios profesionales con mucho Markdown.
- Pages CMS para edición de contenido respaldada por repositorio cuando el usuario necesita una interfaz en el navegador.
- GitHub Pages para un despliegue gratuito nativo de GitHub, o Cloudflare Pages cuando el usuario ya usa Cloudflare o quiere una ruta de dominio personalizado.
Lee references/stack-routes.md antes de tomar una decisión de stack que afecte la implementación.
Flujo de trabajo
1. Clasificar la tarea
Clasifica la solicitud actual como una de:
new-blog: crear un nuevo blog a partir de objetivos y preferencias.repair-blog: arreglar un proyecto de blog generado o existente.migration: mover escritos, notas o contenido de un sitio antiguo a un blog nuevo.cms-setup: hacer que un blog estático existente sea editable por un no programador.deployment: publicar o reparar el despliegue.harness-work: mejorar este skill, scripts, plantillas o flujo de trabajo.
Si la tarea no es un cambio de código y se puede responder directamente, responde directamente. Si requiere archivos, crea o modifica el proyecto en lugar de detenerte en consejos.
2. Preguntar solo preguntas bloqueantes
Para no programadores, haz como máximo tres preguntas sobre el producto antes del primer resumen de construcción. Prefiere valores predeterminados cuando la respuesta no sea arriesgada.
Preguntas mínimas útiles:
- ¿Para qué es el blog: ensayos personales, notas técnicas, perfil de investigación, portafolio, newsletter o mixto?
- ¿Ya tienes escritos, imágenes, dominio o una cuenta de GitHub?
- ¿Quieres la ruta más simple o una ruta más personalizable?
Usa references/intake-and-brief.md cuando el usuario comience con una idea vaga o tenga muchos materiales existentes.
3. Descubrir el estilo visual
Para tareas new-blog, migration y repair-blog con mucho estilo, ejecuta un bucle de descubrimiento de estilo visual antes de la implementación, a menos que el usuario diga explícitamente que use un diseño existente.
Lee references/visual-style-discovery.md, luego:
- haz una pregunta de estilo enfocada a la vez cuando el usuario no esté seguro;
- ofrece 2 a 3 tarjetas de dirección contrastantes cuando el usuario carezca de vocabulario;
- captura las antipreferencias, no solo los gustos;
- pregunta por sitios de referencia, capturas de pantalla, imágenes, libros, newsletters, blogs o marcas si están disponibles;
- traduce palabras vagas a opciones de diseño concretas;
- produce un
Style Briefy pide al usuario que lo confirme o corrija antes de construir la primera versión visual.
Si el usuario quiere velocidad, usa un resumen de estilo provisional, etiquétalo como provisional y mantén la primera implementación fácil de rediseñar.
4. Producir un resumen de construcción
Antes de editar un sitio, escribe un breve resumen de construcción en el proyecto destino o en la conversación:
- audiencia y propósito
- stack elegido y por qué
- modelo de contenido
- dirección visual
- resumen de estilo confirmado o provisional
- flujo de edición
- destino de despliegue
- riesgos y supuestos
Mantén este resumen práctico. Es un contrato de trabajo, no un memo de estrategia.
5. Construir o reparar de forma incremental
Usa el estilo del proyecto existente cuando ya exista un proyecto. Para un proyecto nuevo:
- construye a partir de un starter mantenido en lugar de escribir un sitio desde cero;
- mantén el contenido en Markdown o MDX;
- crea carpetas claras para entradas, páginas, imágenes y configuraciones del sitio;
- agrega contenido de inicio que enseñe al usuario qué reemplazar;
- agrega configuración del CMS solo después de que las rutas de contenido sean estables;
- evita bases de datos adicionales, sistemas de autenticación, entornos de ejecución de servidor o paneles de administración personalizados.
Para detalles sobre CMS/despliegue, lee references/cms-deployment.md.
6. Hacer que el mantenimiento sea obvio
Cada blog entregado debe incluir una forma obvia de realizar estas tareas:
- escribir una nueva entrada
- editar el texto de la página de inicio
- agregar o reemplazar una imagen
- obtener una vista previa localmente o mediante una vista previa de despliegue
- publicar cambios
- recuperarse cuando falla una compilación
Usa references/maintenance-playbooks.md para generar instrucciones concisas orientadas al usuario.
7. Validar
Después de cambios de código o configuración, ejecuta las comprobaciones apropiadas para el proyecto:
- instalación/compilación del gestor de paquetes cuando haya dependencias;
- comando de compilación del sitio estático (
npm run build,hugo --minifyo equivalente); - verificación de enlaces/rutas para la página de inicio, entradas, imágenes y rutas generadas;
- presencia de la configuración del CMS y consistencia de rutas;
- verificación de sintaxis del flujo de trabajo de despliegue cuando se haya creado un flujo de trabajo.
Usa scripts/audit_blog_project.py <project-root> para una auditoría estructural rápida. Trata las advertencias como elementos de acción a menos que claramente no sean relevantes para el stack elegido.
8. Entrega
Termina con:
- qué se creó o cambió;
- dónde debe abrir el proyecto el usuario;
- cómo obtener una vista previa;
- qué dirección de estilo se implementó y cómo cambiarla;
- cómo escribir la siguiente entrada;
- qué requiere aún una acción manual del usuario, como conectar GitHub, Pages CMS, Cloudflare o DNS.
Nunca pidas al usuario que pegue claves API en el chat. Para la autenticación de GitHub o hosting, pídele que inicie sesión a través de la interfaz oficial o el flujo de CLI local.
Reglas de decisión
- Elige Astro cuando el usuario quiera un blog simple, iteración rápida, baja sobrecarga conceptual y buena ergonomía con Markdown/MDX.
- Elige HugoBlox cuando el usuario sea un investigador, estudiante, consultor, ingeniero o creador que necesite publicaciones, proyectos, CV, charlas o bloques de perfil.
- Elige Pages CMS cuando la edición basada en el navegador sea importante y el repositorio almacene contenido en Markdown/YAML/JSON.
- Elige TinaCMS o Keystatic solo cuando el proyecto ya los use o el usuario quiera explícitamente un modelo de edición más rico y acepte la complejidad de configuración.
- Elige Decap CMS solo cuando un proyecto ya lo use o las restricciones de despliegue lo conviertan en la ruta de menor riesgo.
- Evita Cloudflare VibeSDK para un MVP de blog personal; es un kit de construcción de plataformas, no el arnés de blog más simple.
Recursos incluidos
references/stack-routes.md: matriz de selección de stack y justificación de construir vs. comprar.references/intake-and-brief.md: flujo de ingreso conciso y plantilla de resumen de construcción.references/visual-style-discovery.md: entrevista de estilo iterativa, tarjetas de dirección y formato de resumen de estilo.references/cms-deployment.md: notas de implementación de Pages CMS y despliegue.references/maintenance-playbooks.md: patrones de entrega de mantenimiento para no programadores.scripts/audit_blog_project.py: auditoría estructural para proyectos de blog generados o reparados.assets/pages-cms-astro-blog.yml:.pages.ymlinicial para un blog Markdown estilo Astro.assets/github-pages-astro.yml: flujo de trabajo de GitHub Actions inicial para Astro en GitHub Pages.assets/content-brief-template.md: resumen de construcción reutilizable orientado al usuario.assets/first-post-template.md: plantilla de entrada inicial para no programadores.