Mejora las respuestas de tu IA: deja de pedir texto, pide HTML

Llevas semanas pidiéndole a tu IA que te explique algo complejo. Te devuelve tres bloques de texto que te obligan a leer, releer y retener en la cabeza qué dijo en el párrafo dos mientras intentas procesar el párrafo cinco. El problema no es el modelo. El problema es el formato que le estás pidiendo.

Thariq Shihipar publicó un experimento que cambió cómo trabajo con herramientas como Claude Code: en lugar de pedir texto o markdown, pide un archivo HTML autocontenido. Los resultados son, en sus propias palabras, “unreasonably effective”.

El problema con el texto plano

Cuando le pides a tu IA una comparativa de dos enfoques técnicos, te devuelve esto:

Enfoque A tiene las siguientes ventajas: X, Y, Z.
Enfoque B, por otro lado, tiene A, B, C.
Para comparar ambos deberías considerar...

Tienes que leer todo, construir la comparativa mental tú mismo y además recordar los detalles del enfoque A mientras lees el enfoque B. Tu cerebro hace el trabajo que el formato debería hacer por ti.

El markdown mejora la cosa un poco: ya tienes cabeceras, listas, tablas. Pero sigue siendo texto estático. No puedes expandir una sección, no puedes hacer clic en un elemento, no puedes ver un diagrama que se actualice.

Y aquí está el giro: los modelos de lenguaje son extremadamente buenos generando HTML. Es uno de los formatos más representados en sus datos de entrenamiento. Si no se lo pides, defecto por defecto: texto plano.

La solución: pide HTML autocontenido

Un archivo HTML autocontenido incluye sus propios estilos y scripts en un único .html. No depende de CDNs, no necesita un servidor, lo abres en el navegador y funciona.

Antes

❌ Prompt habitual:
"Explícame las diferencias entre los enfoques A y B para gestionar estado en React."

La IA te devuelve varios párrafos de texto. Correctos, pero planos.

Ahora

✅ Prompt mejorado:
"Crea un archivo HTML autocontenido (con CSS y JS inline) que compare
lado a lado los enfoques A y B para gestionar estado en React.
Usa columnas con ejemplos de código, pros/contras y una sección
de recomendación basada en casos de uso."

Lo que obtienes es completamente diferente: dos columnas renderizadas, código con syntax highlighting, comparativa visual, interactividad si la necesitas.

20 casos de uso donde HTML aplasta al texto

Shihipar documentó 20 casos concretos. Estos son los que más uso:

Exploración y análisis

• Comparativas lado a lado de enfoques técnicos con columnas interactivas
• Diffs anotados de cambios de código con comentarios en línea
• Gráficos de dependencias de módulos generados como SVG inline

Diseño y prototipado

• Variantes de componentes renderizadas directamente en el HTML
• Sistemas de diseño con tokens de color, tipografía y espaciado visualizados
• Flujos clickeables para testear navegación sin frontend montado

Investigación y documentación

• Explicadores con secciones colapsables para temas complejos
• Timelines interactivos para arquitecturas o historiales de decisiones
• Dashboards de métricas con datos embebidos y gráficas SVG

Debugging y revisión

• Trazas de ejecución visualizadas como diagramas de secuencia
• Árboles de decisión para lógica de negocio compleja
• Mapas de errores con contexto expandible por error

La clave es que el HTML es el medio en el que se entrega tu sistema de diseño. Pedirle HTML al agente cierra el bucle entre generación y visualización sin pasos intermedios.

Cómo estructurar el prompt

No basta con decir “dame HTML”. Cuanto más específico seas sobre la estructura, mejor el resultado.

Genera un archivo HTML autocontenido (CSS y JavaScript completamente inline,
sin dependencias externas) que:

1. [Qué debe mostrar o hacer]
2. [Estructura visual: columnas, tabs, acordeón, etc.]
3. [Interactividad si la necesitas: filtros, búsqueda, toggles]
4. [Estilo: oscuro/claro, minimalista, con colores de marca]

El archivo debe funcionar abriéndolo directamente en el navegador.

Un ejemplo concreto para una revisión de código:

Genera un archivo HTML autocontenido que muestre el diff entre estas
dos versiones de la función `processPayment()`:

[versión anterior]
[versión nueva]

Usa columnas lado a lado con líneas añadidas en verde y eliminadas en rojo.
Añade anotaciones explicando cada cambio significativo.
El HTML debe funcionar offline, sin CDNs.

Mantener consistencia de diseño con design.md

Aquí está el problema que aparece en cuanto empiezas a generar varios artefactos HTML: cada uno tiene un estilo diferente. El primero usa azul para los acentos, el segundo verde, el tercero una tipografía distinta. Al final tienes una colección de artefactos que no parecen del mismo proyecto.

La solución es un archivo design.md en la raíz de tu proyecto (o en tu carpeta de contexto de IA). Es un documento que la IA lee antes de generar cualquier HTML y que define el sistema de diseño que debe respetar.

Estructura de un design.md efectivo

# design.md — Sistema de diseño para artefactos HTML

## Paleta de colores
- Fondo principal: #0f172a (slate-900)
- Fondo secundario: #1e293b (slate-800)
- Acento primario: #6366f1 (indigo-500)
- Acento secundario: #22d3ee (cyan-400)
- Texto principal: #f1f5f9 (slate-100)
- Texto secundario: #94a3b8 (slate-400)
- Error: #ef4444 (red-500)
- Éxito: #22c55e (green-500)

## Tipografía
- Fuente base: system-ui, -apple-system, sans-serif
- Fuente código: 'Fira Code', 'Cascadia Code', monospace
- Tamaño base: 14px
- Line-height: 1.6
- Escala: 12 / 14 / 16 / 20 / 24 / 32px

## Espaciado
- Unidad base: 4px
- Escala: 4 / 8 / 12 / 16 / 24 / 32 / 48 / 64px

## Bordes y radios
- Radio estándar: 6px
- Radio grande: 12px
- Borde: 1px solid #334155

## Sombras
- Sutil: 0 1px 3px rgba(0,0,0,0.3)
- Tarjeta: 0 4px 12px rgba(0,0,0,0.4)

## Componentes recurrentes
### Tarjeta
- Fondo: slate-800
- Borde: 1px solid slate-700
- Radio: 8px
- Padding: 16px
- Sombra: tarjeta

### Código inline
- Fondo: slate-700
- Color: cyan-400
- Padding: 2px 6px
- Radio: 4px

### Bloque de código
- Fondo: #0d1117
- Borde: 1px solid slate-700
- Padding: 16px
- Radio: 8px

### Etiqueta de estado
- Base: radius 9999px, padding 2px 8px, font-size 12px
- Éxito: fondo green-900, texto green-400
- Error: fondo red-900, texto red-400
- Info: fondo indigo-900, texto indigo-400

## Reglas generales
- Siempre modo oscuro
- Nunca usar librerías externas ni CDNs
- Incluir CSS y JS completamente inline
- Usar variables CSS (--color-accent, --color-bg, etc.)
- Los artefactos deben funcionar offline

Cómo incluirlo en tus prompts

Una vez que tienes el design.md, añades una línea al principio de cada prompt de generación de HTML:

Antes de generar el HTML, lee @design.md y aplica el sistema de
diseño definido ahí. El artefacto debe ser visualmente consistente
con los demás artefactos del proyecto.

Ahora genera un archivo HTML autocontenido que...

En Claude Code puedes referenciarlo directamente:

@design.md

Genera un HTML que muestre un timeline de los eventos del sistema
de autenticación. Sigue el sistema de diseño del archivo de referencia.

Variables CSS para consistencia automática

Para que el diseño sea fácil de mantener, el HTML que genera la IA debe usar variables CSS en lugar de valores hardcodeados:

✅ Con variables CSS (correcto):
<style>
  :root {
    --color-bg: #0f172a;
    --color-surface: #1e293b;
    --color-accent: #6366f1;
    --color-text: #f1f5f9;
    --color-text-muted: #94a3b8;
    --radius: 6px;
    --border: 1px solid #334155;
  }

  .card {
    background: var(--color-surface);
    border: var(--border);
    border-radius: var(--radius);
  }
</style>

❌ Sin variables (difícil de mantener):
<style>
  .card {
    background: #1e293b;
    border: 1px solid #334155;
    border-radius: 6px;
  }
</style>

Si algún día cambias el acento de indigo a violet, solo actualizas --color-accent en design.md y en el nuevo prompt. Los artefactos anteriores mantienen su estilo; los nuevos adoptan el cambio automáticamente.

Flujo de trabajo completo

Así es como queda el flujo una vez integrado:

1. Tienes design.md en tu proyecto con tu sistema de diseño

2. Identificas una necesidad: "quiero ver el árbol de dependencias
   de este módulo antes de refactorizarlo"

3. Prompt:
   @design.md
   Genera un HTML autocontenido que visualice el árbol de dependencias
   del módulo `auth/`. Muestra los imports como un grafo con nodos
   clicables que expanden las dependencias de segundo nivel.
   Sigue el sistema de diseño del archivo de referencia.

4. La IA genera un .html que abres directamente en el navegador

5. Ves el grafo, haces clic en los nodos, entiendes la estructura
   visual sin leer un solo párrafo de texto

Cada artefacto que generes encajará visualmente con el anterior porque todos comparten la misma fuente de verdad de diseño.

Por qué esto funciona mejor que otras alternativas

Podrías pensar en usar Mermaid para diagramas o JSON para datos estructurados. Son válidos, pero tienen limitaciones:

El HTML autocontenido es el único formato que puedes abrir directamente y que soporta cualquier tipo de visualización: tablas, grafos, timelines, comparativas, prototipos.

Conclusión

Para mí, el cambio de mentalidad es simple: el texto es para leer, el HTML es para ver. Cuando necesito entender algo complejo, necesito verlo, no leerlo.

Los modelos de lenguaje son extraordinariamente buenos generando HTML porque han consumido terabytes de él. Cuando les das libertad para expresar información en ese formato, el resultado es cualitativamente diferente: más fácil de consumir, más útil para tomar decisiones, más difícil de malinterpretar.

El design.md cierra el otro problema: la consistencia. Sin él, cada artefacto es un experimento visual distinto. Con él, construyes un lenguaje visual compartido entre tú y tu IA que escala a medida que tu proyecto crece.

Pruébalo en tu próximo prompt. No pidas que te expliquen algo. Pide un HTML que lo muestre.

Preguntas frecuentes

¿Funciona esto con cualquier LLM o solo con Claude? Con cualquier modelo que genere código bien. Claude Code tiene la ventaja de que puedes usar @archivo.md para inyectar contexto directamente, pero el enfoque funciona igualmente con GPT-4, Gemini o cualquier otro modelo al que puedas pegar el contenido de design.md en el prompt.

¿Los archivos HTML generados son seguros de abrir? Sí, siempre que los hayas generado tú mismo o vengan de una fuente confiable. Un HTML autocontenido para visualizar datos de tu propio proyecto no tiene riesgos. No ejecutes HTML de fuentes desconocidas sin revisarlo antes.

¿Cuándo NO usar HTML? Para respuestas cortas y directas, el texto sigue siendo mejor. Si preguntas “¿cuál es la diferencia entre == y === en JavaScript?”, no necesitas un HTML. Usa HTML cuando la cantidad de información o la necesidad de comparación visual lo justifique.

¿Tengo que crear el design.md a mano? Puedes pedirle a la IA que te ayude a crearlo. Dale ejemplos de colores y estilos que te gusten, o una URL con un diseño de referencia, y que redacte el archivo. Después lo revisas y ajustas a tu gusto.

¿Y si el HTML generado tiene bugs? Pega el error en el chat y pide que lo corrija. El bucle de corrección es rápido porque el contexto del artefacto ya está en la conversación. Generalmente un par de iteraciones lo dejan funcional.