Uso de Claude Code: La eficacia irrazonable del HTML

Markdown se ha convertido en el formato de archivo dominante que los agentes usan para comunicarse con nosotros. Es simple, portátil, tiene cierta capacidad de texto enriquecido y es fácil de editar. Incluso Claude se ha vuelto sorprendentemente bueno usando ASCII para hacer diagramas dentro de archivos markdown.

Pero a medida que los agentes se han vuelto más y más potentes, he sentido que markdown se ha convertido en un formato restrictivo. Me resulta difícil leer un archivo markdown de más de cien líneas. Quiero visualizaciones más ricas, color y diagramas, y poder compartirlos fácilmente.

Además, cada vez edito menos estos archivos yo mismo, y los uso más como especificaciones, archivos de referencia, resultados de lluvia de ideas, etc. Cuando hago ediciones, normalmente le pido a Claude que las haga, lo que elimina uno de los mayores beneficios de markdown.

He empezado a preferir HTML como formato de salida en lugar de Markdown, y cada vez veo que otros en el equipo de Claude Code también lo usan. Esta es la razón.

(si quieres empezar con algunos ejemplos, puedes ver varios aquí: https://thariqs.github.io/html-effectiveness, solo asegúrate de volver para leer más sobre por qué)

¿Por qué HTML?

Densidad de información

HTML puede transmitir información mucho más rica en comparación con markdown. Por supuesto, puede hacer estructura de documento simple como encabezados y formato, pero también puede representar todo tipo de otra información, como:

• Datos tabulares usando tablas
• Datos de diseño con CSS
• Ilustraciones con SVG
• Fragmentos de código con etiquetas script
• Interacciones usando elementos HTML con JavaScript + CSS
• Flujos de trabajo usando SVG y HTML
• Datos espaciales usando posiciones absolutas y lienzos
• Imágenes usando etiquetas de imagen

Incluso diría que casi no hay ningún conjunto de información que Claude pueda leer que no puedas representar de manera bastante eficiente con HTML. Esto lo convierte en una forma muy eficiente para que el modelo te comunique información detallada y para que tú la revises.

He descubierto que, al no poder hacer esto, el modelo puede hacer cosas más ineficientes en markdown, como diagramas ASCII o, mi favorito, estimar colores con caracteres Unicode como en esta captura de pantalla de Claude Code.

Claude Code intentando mostrar color en markdown

Claridad visual y facilidad de lectura

A medida que Claude puede hacer trabajos más complejos, también escribe especificaciones y planes cada vez más grandes. En la práctica, he notado que tiendo a no leer realmente un archivo markdown de más de 100 líneas, y ciertamente no puedo lograr que nadie más en mi organización lo lea.

Pero los documentos HTML son mucho más fáciles de leer. Claude puede organizar la estructura visualmente para que sea ideal navegar con pestañas, ilustraciones, enlaces, etc. Incluso puede ser adaptable a dispositivos móviles para que puedas leerlo de manera diferente según tu factor de forma.

Facilidad para compartir

Los archivos Markdown son bastante difíciles de compartir, ya que la mayoría de los navegadores no los renderizan bien de forma nativa. A menudo tienes que agregarlos como archivos adjuntos en correos electrónicos o mensajes.

Con HTML, siempre que subas el archivo (por ejemplo, a S3), puedes compartir el enlace fácilmente. Tus colegas pueden abrirlo donde quieran y consultarlo sin problemas.

La probabilidad de que alguien lea realmente tu especificación, informe o resumen de PR es mucho mayor si está en HTML.

Interacción bidireccional

HTML te permite interactuar con el documento. Por ejemplo, puedes pedirle que agregue controles deslizantes o perillas para ajustar un diseño, o que te permita modificar diferentes opciones en el algoritmo para ver qué sucede. También puedes pedirle que te permita copiar estos cambios en un prompt para pegarlos de nuevo en Claude Code.

Lee más sobre mi publicación de playgrounds para ver ejemplos de esta interacción bidireccional: https://x.com/trq212/status/2017024445244924382

Ingesta de datos

¿Por qué usar Claude Code para hacer archivos HTML en lugar de ClaudeAI o Claude Design, por ejemplo? Una de las razones más importantes es todo el contexto que Claude Code puede ingerir.

Por ejemplo, al escribir este artículo, le pedí a Claude Code que leyera mi carpeta de código, encontrara todos los archivos HTML que había generado, los agrupara y categorizara, y luego hiciera un archivo HTML con todos los diagramas que representaran cada tipo. Los diagramas que ves en este artículo son el resultado directo de eso.

Además del sistema de archivos, Claude Code puede encontrar contexto adicional usando tus MCP (como Slack, Linear, etc.), tu navegador web (con Claude en Chrome), tu historial de git, etc.

Es alegre

Hacer documentos HTML con Claude es simplemente más divertido y me hace sentir más involucrado e interesado en la creación, y eso por sí solo es suficiente.

Cómo empezar

Tengo un poco de miedo de que la gente lea este artículo y lo convierta en una habilidad /html o algo así. Si bien puede haber algo de valor en eso, quiero enfatizar que no necesitas hacer mucho para que Claude haga esto. Simplemente puedes pedirle que "haga un archivo HTML" o "haga un artefacto HTML".

El truco está en saber qué quieres que haga el artefacto y cómo podrías usarlo. Con el tiempo, podrías crear una habilidad, pero por ahora te sugiero que empieces desde cero para familiarizarte con cómo usarlo en diferentes casos.

Casos de uso

Para hacer esto más concreto, he creado muchos archivos HTML diferentes para distintos casos de uso. Puedes verlos todos aquí: https://thariqs.github.io/html-effectiveness/ pero aquí tienes un resumen.

Especificaciones, planificación y exploración

HTML es un lienzo rico para que Claude profundice en un problema. Cuando empiezo a trabajar en un problema, en lugar de un simple plan en markdown, espero crear una red de archivos HTML. Por ejemplo, podría empezar pidiéndole a Claude Code que haga una lluvia de ideas y cree algunas exploraciones de diferentes opciones. Luego le pediría que profundice en una, tal vez haciendo maquetas o fragmentos de código. Finalmente, cuando me sienta satisfecho, le pediré que escriba un plan de implementación. Cuando esté contento con el plan, crearé una nueva sesión y le pasaré todos estos archivos para que los implemente.

Al verificar, también le pediré al agente de verificación que lea los archivos y tendrá un contexto mucho más amplio sobre lo que se necesita.

Ejemplos de prompts:

• No estoy seguro de qué dirección tomar para la pantalla de inicio. Genera 6 enfoques claramente diferentes — varía el diseño, el tono y la densidad — y colócalos en un solo archivo HTML en una cuadrícula para poder compararlos lado a lado. Etiqueta cada uno con la compensación que está haciendo.
• Crea un plan de implementación exhaustivo en un archivo HTML, asegúrate de incluir algunas maquetas, mostrar el flujo de datos y agregar fragmentos de código importantes que pueda querer revisar. Hazlo fácil de leer y digerir.

Casos de uso:

• Explorar otras formas de implementar algo en código
• Explorar múltiples diseños visuales

Revisión y comprensión de código

El código puede ser difícil de leer en un archivo Markdown. Pero con HTML podemos renderizar diferencias, anotaciones, diagramas de flujo, módulos, etc. Úsalo para entender el código que el agente ha escrito, para obtener una revisión de código o para explicar un PR a alguien que revisa tu código. Encuentro que esto a menudo funciona mejor que la vista de diferencias predeterminada de GitHub, y ahora adjunto un explicador de código HTML a cada PR que hago.

Ejemplo de prompt:

Ayúdame a revisar este PR creando un artefacto HTML que lo describa. No estoy muy familiarizado con la lógica de streaming/contrapresión, así que concéntrate en eso. Renderiza la diferencia real con anotaciones en el margen, colorea los hallazgos por gravedad y cualquier otra cosa que sea necesaria para transmitir bien el concepto.

Casos de uso:

• Crear un PR
• Revisar un PR
• Entender un tema en el código

Diseño y prototipos

Claude Design se basa en HTML porque HTML es increíblemente expresivo para el diseño, incluso si tu superficie final no es HTML. Claude puede esbozar un diseño en HTML y luego escribirlo en el lenguaje de tu elección, ya sea React, Swift, etc.

También puedes prototipar interacciones, como animaciones, acciones, etc. Considera pedirle a Claude que haga controles deslizantes, perillas, etc. para ajustar exactamente lo que buscas.

Ejemplo de prompt:

Quiero prototipar un nuevo botón de pago. Al hacer clic, reproduce una animación y luego se vuelve púrpura rápidamente. Crea un archivo HTML con varios controles deslizantes y opciones para que pueda probar diferentes opciones en esta animación. Dame un botón de copia para copiar los parámetros que funcionaron bien.

Úsalo para:

• Crear artefactos de sistemas de diseño
• Ajustar componentes
• Visualizar bibliotecas de componentes
• Prototipar animaciones alegres

Informes, investigación y aprendizaje

Claude Code es increíblemente bueno sintetizando información de múltiples fuentes de datos y convirtiéndola en un informe legible. Puedes pedirle a Claude que busque en tu Slack, tu base de código, el historial de git, internet, etc., y usarlo para generar informes extremadamente legibles para ti, para la dirección, para tu equipo, etc.

Puedes armarlo en forma de un documento HTML largo, un explicador interactivo o incluso una presentación/diapositivas. Pídele a Claude que use SVG para los diagramas y ayudar a visualizarlo.

Por ejemplo, para mis publicaciones sobre prompt caching, le pedí a Claude que preparara un archivo de investigación detallado en HTML para que yo leyera sobre todos nuestros cambios en prompt caching después de leer el historial de git.

Ejemplo de prompt:

No entiendo cómo funciona realmente nuestro limitador de velocidad. Lee el código relevante y produce una sola página explicativa en HTML: un diagrama del flujo del token-bucket, los 3 o 4 fragmentos de código clave anotados, y una sección de "trampas" al final. Optimízalo para alguien que lo lea una sola vez.

Úsalo para:

• Resumir cómo funciona una función
• Explicarme un concepto
• Informes de estado semanales para tu jefe
• Informes de incidentes para la dirección
• Ilustraciones SVG, diagramas de flujo, diagramas técnicos, etc.

Interfaces de edición personalizadas

A veces es difícil describir lo que quieres solo con un cuadro de texto. En ese caso, le pido a Claude que me construya un editor desechable para exactamente lo que estoy trabajando. No un producto, ni una herramienta reutilizable, sino un solo archivo HTML, creado específicamente para ese único dato.

El truco es siempre terminar con una exportación: un botón de "copiar como JSON" o "copiar como prompt" que convierta lo que hice en la interfaz de usuario en algo que pueda pegar de nuevo en Claude Code.

Ejemplos de prompts:

• Necesito reordenar estos 30 tickets de Linear. Hazme un archivo HTML con cada ticket como una tarjeta arrastrable en las columnas Ahora / Siguiente / Después / Eliminar. Ordénalos previamente según tu mejor criterio. Agrega un botón "copiar como markdown" que exporte el orden final con una justificación de una línea por grupo.
• Aquí está la configuración de nuestros feature flags. Construye un editor basado en formularios para ella, agrupa los flags por área, muestra las dependencias entre ellos, adviérteme si activo un flag cuyo prerrequisito está desactivado. Agrega un botón "copiar diff" que me dé solo las claves cambiadas.
• Estoy ajustando este prompt de sistema. Haz un editor lado a lado: prompt editable a la izquierda con los espacios de variables resaltados, tres entradas de muestra a la derecha que rendericen la plantilla rellenada en vivo. Agrega un contador de caracteres/tokens y un botón de copia.

Úsalo para:

• Reordenar, triar o agrupar cualquier cosa (tickets, casos de prueba, comentarios)
• Editar configuraciones estructuradas (feature flags, variables de entorno, JSON/YAML con restricciones)
• Ajustar prompts, plantillas o textos con vista previa en vivo
• Curar conjuntos de datos, aprobar/rechazar filas, etiquetar ejemplos, exportar la selección
• Anotar un documento, transcripción o diff y exportar las anotaciones
• Elegir valores que son difíciles de expresar en texto: colores, curvas de easing, regiones de recorte, programaciones cron, expresiones regulares.

Preguntas frecuentes

He estado contándole a mucha gente cómo he cambiado a HTML y he visto algunas preguntas repetidas.

¿No es menos eficiente en tokens?

Si bien markdown a menudo usa menos tokens, he descubierto que la mayor expresividad de HTML y la probabilidad mucho más alta de que yo lo lea significa que obtengo un mejor resultado general. Con la ventana de contexto de 1MM en Opus 4.7, el mayor uso de tokens no se nota realmente en la ventana de contexto.

¿Cuándo usas markdown ahora?

Honestamente, he dejado de usar markdown por completo para casi todo, pero probablemente estoy en el extremo maximalista de HTML.

¿Cómo veo el archivo HTML?

Normalmente lo abro en un navegador localmente (puedes pedirle a Claude que lo abra), o lo subo a S3 si quiero un enlace compartible.

¿No tarda más en generarse que markdown?

¡Sí, tarda más! HTML puede tardar de 2 a 4 veces más que Markdown, pero he descubierto que los resultados valen la pena.

¿Qué pasa con el control de versiones?

Este es honestamente uno de los mayores inconvenientes de HTML. Las diferencias de HTML son ruidosas y difíciles de revisar en comparación con Markdown.

¿Cómo consigo que Claude se ajuste a mi gusto / que no lo haga feo?

El plugin de diseño frontend ayuda a Claude a hacer buenos archivos HTML. Pero para que coincida con el estilo de tu propia empresa, puedes crear un único archivo HTML de sistema de diseño señalando a Claude a tu base de código. Luego puedes usar ese archivo de sistema de diseño como referencia para otros archivos HTML.

Mantente al tanto

Todo lo anterior quiere decir que creo que la verdadera razón por la que uso HTML es que me siento mucho más involucrado con Claude. Había empezado a temer que, como había dejado de leer los planes en profundidad, simplemente tendría que dejar que Claude tomara sus decisiones.

Pero me alegra decir que, en cambio, me siento más involucrado que nunca cuando uso HTML. Espero que tú también.