Cómo usar Claude Code: la sorprendente eficiencia del HTML

 (twitter.com/trq212)
2 puntos por GN⁺ 1 시간 전 | 1 comentarios | Compartir por WhatsApp
  • Usar HTML como formato de salida en Claude Code en lugar de Markdown permite crear resultados más fáciles de leer y revisar por humanos, con visualizaciones, color, diagramas e interacciones más ricas
  • HTML puede expresar de forma eficiente la mayor parte de la información que Claude puede leer, aprovechando tablas, CSS, SVG, script, interactividad con JavaScript, imágenes, canvas y posicionamiento absoluto
  • Claude Code puede leer contexto como el sistema de archivos, MCP, el navegador y el historial de Git, y unirlo en resultados HTML; basta con pedirle “créame un archivo HTML” para empezar
  • Las principales formas de uso se dividen en especificaciones, planes y exploración, revisión y comprensión de código, diseño y prototipos, reportes, investigación y aprendizaje, e interfaces de edición personalizadas de un solo uso
  • HTML tarda entre 2 y 4 veces más en generarse que Markdown y produce diffs más ruidosos, lo que dificulta el control de versiones, pero sus ventajas en expresividad, capacidad de compartirse y probabilidad real de ser leído destacan más

Por qué empecé a preferir HTML en lugar de Markdown

  • Markdown se volvió el formato de archivo dominante para que los agentes se comuniquen con las personas: es simple, portable, permite algo de formato y es fácil de editar manualmente
  • Claude también genera bien diagramas ASCII dentro de Markdown, pero a medida que los agentes se vuelven más potentes, Markdown empieza a sentirse como un formato limitado
  • Los archivos Markdown de más de 100 líneas son difíciles de leer, y surge la necesidad de compartir visualizaciones, color y diagramas más ricos con mayor facilidad
  • A medida que se vuelve más común pedirle a Claude que edite archivos en vez de editarlos uno mismo, se reduce el valor de una de las grandes ventajas de Markdown: la facilidad de edición manual directa
  • Incluso dentro del equipo de Claude Code está creciendo el uso de HTML como formato de salida; se pueden ver ejemplos en html-effectiveness

La expresividad y capacidad de compartirse de HTML

  • HTML puede representar no solo estructura de documentos, como títulos y formato, sino también una variedad de información mucho mayor que Markdown
  • Entre la información que puede representar están los datos tabulares mediante tablas, datos de diseño mediante CSS, ilustraciones SVG, fragmentos de código mediante la etiqueta script e interactividad con JavaScript y CSS
  • Con SVG y HTML se pueden representar flujos de trabajo, con posicionamiento absoluto y canvas se pueden expresar datos espaciales, y con la etiqueta img se pueden insertar imágenes
  • La mayor parte del conjunto de información que Claude puede leer puede expresarse de forma bastante eficiente en HTML, lo que lo convierte en un formato eficiente para que el modelo transmita información profunda y para que las personas la revisen
  • Si no se usa HTML, Claude puede terminar recurriendo a expresiones ineficientes en Markdown, como diagramas ASCII o intentos de estimar colores con caracteres Unicode
  • A medida que Claude realiza tareas más complejas, también escribe especificaciones y planes más grandes, y en la práctica los archivos Markdown de más de 100 líneas no se leen bien
  • Los documentos HTML pueden organizar su estructura visualmente con pestañas, ilustraciones y enlaces, lo que los hace fáciles de explorar, y también pueden diseñarse de forma responsiva para leerse distinto según el tamaño de pantalla
  • Los archivos Markdown no suelen renderizarse bien de forma nativa en el navegador y muchas veces hay que adjuntarlos en correos o mensajes, mientras que HTML puede subirse a un lugar como S3 y compartirse fácilmente por enlace
  • Las especificaciones, reportes y descripciones de PR en HTML son mucho más fáciles de abrir y consultar para los colegas, lo que aumenta mucho la probabilidad de que realmente se lean
  • Los documentos HTML pueden admitir interacción bidireccional, por ejemplo con sliders o perillas para ajustar diseños o cambiar opciones de algoritmos y ver los resultados
  • También puede crearse una función para copiar lo ajustado y volver a pegarlo en Claude Code como prompt; un ejemplo relacionado se trata en playgrounds post

Por qué usar Claude Code junto con HTML

  • Claude Code puede leer distintos tipos de contexto, como el sistema de archivos, MCP, el navegador y el historial de Git, y unirlos en resultados HTML
  • Por ejemplo, puede encontrar todos los archivos HTML generados en una carpeta de código, agruparlos y clasificarlos, y luego crear un archivo HTML con diagramas que representen cada tipo
  • Además del sistema de archivos, también puede buscar contexto adicional en MCP como Slack o Linear, en el navegador web mediante Claude in Chrome y en el historial de Git
  • El proceso de crear documentos HTML junto con Claude se siente más divertido y da una mayor sensación de participación e inversión en el resultado
  • No hace falta crear una habilidad /html; basta con pedir “créame un archivo HTML” o “créame un artifact HTML” para empezar
  • El consejo importante es saber qué debe hacer el artifact y cómo se va a usar; al principio conviene redactar el prompt desde cero cada vez para aprender distintos usos

Principales formas de uso

  • Especificaciones, planes y exploración

    • HTML puede servir como un lienzo rico para que Claude profundice en un problema, y el trabajo puede comenzar con un conjunto de varios archivos HTML en lugar de un único plan en Markdown
    • Primero se pueden hacer lluvias de ideas en varias direcciones, luego expandir una de ellas para crear mocks o fragmentos de código y finalmente redactar un plan de implementación
    • Si el plan resulta satisfactorio, se puede crear una nueva sesión y pasarle esos archivos para implementarlo; incluso un agente de verificación puede leer los mismos archivos y obtener contexto más amplio
    • Se le puede pedir que cree un grid HTML con 6 enfoques distintos para una pantalla de onboarding, con variaciones de layout, tono y densidad, e indicando los trade-offs de cada opción
    • También se le puede pedir un plan de implementación en HTML fácil de leer, que incluya mockups, flujo de datos y fragmentos de código para revisar
    • Puede usarse para explorar formas de implementar código y comparar varios diseños visuales

  • Revisión de código y comprensión del código

    • El código puede ser difícil de leer en archivos Markdown, pero en HTML se pueden renderizar diffs, comentarios, diagramas de flujo y estructuras de módulos
    • Puede usarse para entender código escrito por un agente, recibir revisión de código o explicar cambios a quienes revisan un PR
    • A veces funciona mejor que la vista de diff básica de GitHub, y también es posible un flujo donde se adjunta a cada PR un archivo HTML de explicación del código
    • Se le puede pedir que cree un artifact HTML para revisar un PR, que se concentre en una lógica de streaming/backpressure poco familiar, y que agregue comentarios al margen sobre el diff real con colores según la severidad
    • Puede usarse para redactar PR, revisar PR y entender temas de código

  • Diseño y prototipos

    • Claude Design se basa en HTML, y HTML tiene una gran expresividad para diseño incluso cuando la superficie final no es HTML
    • Claude puede esbozar un diseño en HTML y luego escribirlo en el lenguaje deseado, como React o Swift
    • Se pueden prototipar interacciones como animaciones y acciones, y añadir sliders o perillas para ajustar los valores deseados
    • Se le puede pedir que haga un botón de checkout que, al hacer clic, reproduzca una animación y luego cambie rápidamente a morado, incluyendo varios sliders y opciones, además de un botón para copiar los parámetros que mejor funcionen
    • Puede usarse para generar artifacts de sistemas de diseño, ajustar componentes, visualizar bibliotecas de componentes y crear prototipos de animaciones atractivas

  • Reportes, investigación y aprendizaje

    • Claude Code es fuerte para sintetizar información de múltiples fuentes de datos y convertirla en reportes fáciles de leer
    • Se le puede pedir que busque en Slack, el codebase, el historial de Git e internet, y que genere reportes fáciles de leer para uno mismo, liderazgo o el equipo
    • El resultado puede tomar la forma de un documento HTML largo, una explicación interactiva o un conjunto de slides o deck
    • Pedirle que haga diagramas con SVG ayuda a la visualización
    • Al preparar un texto sobre prompt caching, se usó un enfoque donde leyó el historial de Git y creó un archivo de investigación profunda en HTML que cubría todos los cambios de prompt caching
    • Se le puede pedir que lea el código relacionado con un rate limiter y cree una sola página explicativa en HTML con un diagrama del flujo token-bucket, de 3 a 4 fragmentos clave de código anotados y una sección final de gotchas
    • Puede usarse para resumir cómo funciona una funcionalidad, explicar conceptos, hacer reportes semanales de estado, informes de incidentes, e ilustraciones SVG, diagramas de flujo y diagramas técnicos

  • Interfaces de edición personalizadas

    • Cuando es difícil explicar lo que se quiere solo con una caja de texto, se puede crear un editor HTML desechable adaptado a los datos con los que se está trabajando
    • No se trata de un producto ni de una herramienta reutilizable, sino de un único archivo HTML hecho a la medida para una pieza específica de datos
    • La clave es agregar al final una exportación como “copy as JSON” o “copy as prompt”, para poder pegar en Claude Code el resultado manipulado en la interfaz
    • Se pueden convertir 30 tickets de Linear en tarjetas arrastrables dentro de columnas Now / Next / Later / Cut, y hacer que copie en Markdown el orden final junto con una justificación de una línea por bucket
    • Se puede crear un editor basado en formularios para la configuración de feature flags, agruparlo por áreas, mostrar dependencias, advertir si se activa un flag cuando el flag prerequisito está apagado, y copiar solo las claves modificadas como diff
    • Al ajustar un system prompt, se puede poner a la izquierda un prompt editable con variables destacadas, y a la derecha el render en tiempo real de tres entradas de ejemplo, junto con contador de caracteres, contador de tokens y botón de copiar
    • Puede usarse para reordenar tickets, casos de prueba y feedback; editar configuraciones estructuradas; ajustar prompts, plantillas y copy; curar datasets; anotar documentos, transcripciones y diffs; y elegir valores difíciles de expresar en texto, como color, easing curve, región de recorte, cron schedule o regex

Preguntas frecuentes y límites

  • Markdown normalmente usa menos tokens, pero HTML ofrece mayor expresividad y una mayor probabilidad de que realmente se lea, lo que mejora el resultado final en conjunto
  • En la ventana de contexto de 1MM de Opus 4.7, el aumento en uso de tokens no se nota demasiado dentro de la ventana de contexto
  • Se ha dejado de usar Markdown en casi todos los casos, pero eso corresponde a una forma de trabajo muy inclinada a favorecer HTML al máximo
  • Los archivos HTML pueden abrirse en un navegador local, también se le puede pedir a Claude que los abra, y si se necesita un enlace compartible se pueden subir a S3
  • Generar HTML toma más tiempo que Markdown, y puede tardar entre 2 y 4 veces más, pero se considera que el resultado lo vale
  • Uno de los mayores inconvenientes es el control de versiones, porque los diffs de HTML son más ruidosos y más difíciles de revisar que los de Markdown
  • Para que Claude genere HTML alineado con los gustos deseados, ayuda usar un frontend design plugin
  • Para ajustarlo al estilo de una empresa, se puede hacer que Claude revise el codebase y cree un único archivo HTML del sistema de diseño, que luego sirva como referencia para otros archivos HTML
  • Usar HTML reduce el miedo a dejarle decisiones a Claude por no leer a fondo los planes que escribe, y permite mantenerse más en flow durante el proceso de trabajo con Claude

Lecturas relacionadas

1 comentarios

 
GN⁺ 1 시간 전
Comentarios en Hacker News

  • Me preocupa que, si nos inclinamos por HTML, perdamos la capacidad de que personas y LLM redacten y editen documentos juntos con facilidad
    Para un texto explicativo simple está bien, pero si se trata de una especificación más compleja, es muy importante poder entrar directamente al resultado generado y corregirlo. En documentos HTML eso es mucho más difícil que en Markdown, y claro, también se le puede pedir al LLM que vuelva a editar el HTML, pero cuando ya tienes muy claro en la cabeza lo que quieres decir, eso en sí mismo se vuelve otra barrera. Si este patrón se vuelve común, parece que la co-creación entre humanos y LLM va a disminuir más, y que nos moveremos hacia delegarle al LLM incluso el estilo, el tono y la selección del contenido. Me sorprendió que esta preocupación no aparezca en las preguntas frecuentes del blog

    • Markdown soporta HTML en línea para elementos interactivos, así que un documento Markdown con una plantilla HTML conocida y un proceso de build sencillo podría ser una alternativa interesante
      Por ejemplo, algo como un comando de pandoc de una sola línea
    • Creo que aquí hay un paso más. Con HTML se puede hacer casi todo, pero también fue sorprendentemente efectivo dejar que el LLM defina su propio lenguaje
      Ahora mismo estoy haciendo un pequeño juego móvil con vista isométrica y sonido, y le pedí a Codex que creara una herramienta para colocar bloques en documentos three.js preparados y tomar capturas con las herramientas de desarrollador de Chromium; terminó creando una pequeña estructura JSON para definir bloques, colores y efectos, y generar un tileset 2.5D. También le hice definir sonido y música con un script Python de uv, y se inventó un formato YAML que puede producir ruido. Ya superó por completo la prueba del pelícano en SVG, y Codex incluso generó suficiente arte prototipo y una banda sonora prototipo para soldados, caballeros y sacerdotes
    • Llevamos décadas escribiendo HTML fácilmente a mano. Los editores de texto son muy buenos para escribir HTML, y hay muchos comandos como ajuste automático de línea y cierre automático, así que leerlo y escribirlo es simple
    • Eso parece cierto solo si te encierras en un emulador primitivo de teletipo. En un entorno de programación decente, editar HTML debería ser muy sencillo, y si la tendencia es hacia salidas de modelo más ricas, un editor WYSIWYG integrado también podría ser una opción
    • Últimamente empecé a usar HTML para reportes, pero siempre dejo un archivo Markdown como formato intermedio y le pido al LLM que cree una versión más elegante con gráficos y dibujos SVG basados en las tablas de Markdown

  • Es irónico que esto no sea una página HTML interactiva, sino una imagen renderizada de HTML subida a Twitter
    Defender HTML desde una plataforma con una estructura semántica más pobre que Markdown termina siendo bastante gracioso

  • Un prompt que uso seguido cuando exploro nuevas ideas o herramientas es este

    In a single index.html, no dependencies, sparse styling, create an app that

    Ya hacía herramientas pequeñas así incluso antes de la IA, y me gusta poder mandar una herramienta por email a un amigo y decirle “si quieres cambiar algo, aviéntasela a un LLM”

    • Este enfoque sí funciona
      Es sorprendentemente amplio el rango de cosas para las que puedes usar un solo archivo HTML con estilos y JS incluidos: dashboards, apps pequeñas, utilidades que interactúan con APIs o traen datos de algún lado. Si lo dejas en tu carpeta personal ~ del servidor compartido de la empresa, cualquiera puede verlo y usarlo de inmediato
    • Cuando itero en el diseño de un cliente nuevo, también lo hago en un index.html simple con CSS en línea, y cuando me gusta el resultado, pongo ese archivo junto al archivo de plantilla del proyecto y le pido al LLM que incorpore el diseño de index.html al archivo de plantilla
    • Nunca había pensado bien en este caso de uso y me siento un poco tonto. Es demasiado obvio lo útil que puede ser
      Hasta ahora, cuando usaba LLM, el foco estaba en la “app” en sí, no en las herramientas auxiliares alrededor de la app. Esas herramientas de apoyo no necesitan estar súper pulidas ni cubrir todos los casos; basta con que funcionen lo suficiente para ser útiles. Cuando terminas, las tiras y mañana haces otras nuevas
    • Descubrí este truco hace tiempo y terminé haciendo un montón de calculadoras para circuitos electrónicos analógicos: https://cofree.coffee/~solomon/calculators/
      Es muy práctico poder armar este tipo de herramientas rápido y subirlas a un sitio estático
    • En Claude web también hace esto cuando le pides HTML. Te lo entrega como artifact, así que es probable que el modelo esté bien entrenado en este patrón

  • Las tecnologías web realmente acertaron en muchísimas cosas. Mucha gente se queja, pero son impresionantes
    En mi trabajo anterior tuve que lidiar con una app hecha con vibe coding y terminé renunciando por eso. Era una estructura de frontend de una sola página en Next.js con un backend de API aparte, así que las URL para usuarios no coincidían con los endpoints del backend. Como la IA le ponía hooks de React a todo, el estado vivía en memoria y no existía enrutamiento basado en URL a menos que se diseñara de forma consciente. Así que los enlaces no salían gratis, y los usuarios no tenían forma de enlazar a ningún lugar excepto al punto de entrada principal. Enlaces. Sobre todo en herramientas internas, todo debería poder enlazarse para facilitar la colaboración y la resolución de problemas. Esa idea de diseño de ubicaciones uniformes de recursos y verbos ya estaba muy bien pensada hace 30 o 40 años

    • ¿Quieres decir que, aunque navegabas a otra página o pestaña, la URL no se actualizaba?

  • Como punto intermedio entre HTML y Markdown, aquí faltan algunas cosas. HTML es mucho menos eficiente en tokens, y dar retroalimentación precisa sobre un diseño en HTML es más difícil que en Markdown
    Ambos trade-offs juegan a favor de Anthropic. Si usas HTML como medio, aumenta el consumo de tokens, y además es probable que estén invirtiendo en herramientas para anotar o marcar HTML como parte de Claude Design, así que el lock-in podría hacerse más fuerte. O es coincidencia o es una estrategia brillante

    • Sí es un poco menos eficiente, pero si no hay demasiada estructura ni demasiados elementos visuales, la diferencia no es tan grande
      Tampoco entiendo bien por qué sería más difícil dar retroalimentación precisa que en Markdown. Puedes poner id, secciones, etc. en las etiquetas
    • HTML también tiene un alcance más amplio de vulnerabilidades por ejecución de código. El texto plano no hace daño

  • Llevo décadas trabajando con HTML, pero para documentos simples Markdown sigue siendo más rápido. Estaría bueno tener un punto intermedio, y de hecho ya existen opciones con más funciones, como GitHub Markdown
    También puedes incrustar Mermaid, y cuando hace falta mezclar componentes, usar algo como MDX. Según entiendo, readme.com también usa MDX internamente. Si necesitas tarjetas o layouts, hasta podrías meter componentes basados en algo como Bootstrap. Lo único que falta ahora es soporte de interfaz. Como ya se puede renderizar HTML puro, no parece tan difícil agregar un Markdown más potente

    • Creo que MDX es el punto medio perfecto. Gracias a este comentario, creo que voy a empezar a usar MDX en vez de Markdown común

  • Tanto la especificación original de Markdown [1] como CommonMark [2] definen claramente el soporte para HTML en línea. Así que, según el uso, se puede obtener hasta cierto punto lo mejor de ambos mundos
    La mayor parte del tiempo puedes usar encabezados y párrafos normales de Markdown, y si agregas imágenes y tablas, el texto sigue siendo legible en su forma fuente sin etiquetas HTML. Si quieres meter algo como el SVG que puso el autor como ejemplo, puedes incrustar el SVG directamente, y quien lo vea solo tiene que renderizar el Markdown con el visor que prefiera. Si estás viendo el archivo Markdown crudo en VS Code y te topas con etiquetas HTML, basta con abrir la vista previa con Cmd+Shift+V. Claro, si hablas de una página web completa con botones interactivos y estilo totalmente personalizado, eso sí es difícil de lograr, pero si es sobre todo texto, imágenes y tablas con algunos extras aquí y allá, se puede llegar bastante lejos
    [1] https://daringfireball.net/projects/markdown/syntax#html
    [2] https://spec.commonmark.org/0.31.2/#html-blocks

    • Yo diría que un documento Markdown no debería necesitar vista previa. Para eso mejor haces directamente un documento HTML

  • Desde enero he estado impulsando mucho este enfoque para usos no relacionados con programación. La propiedad importante es que sea una única fuente de verdad editable, comprensible para LLM y humanos, renderizable y modificable de forma incremental
    Hablo seguido con gente común sobre trabajo con IA, y cuando me topo con una conversación sobre IA en la calle, me meto como antropólogo. Los artifacts HTML son como una nueva barra de direcciones del navegador. Es como cuando algunos usuarios entienden esa barra como si en realidad fuera Google. Hoy mucha gente habla de trabajos como “hoja de cálculo”, “presentación”, “resumen de una página de marketing”, “slideshow”, “análisis competitivo” o “diagrama de sistema HVAC”, y dice que trabajar en eso dentro de ChatGPT o Claude web no fue gran cosa, pero que crear un documento nuevo con Claude Code u OpenClaw fue casi milagroso
    Cuando les preguntas cuál era el documento real y cuál fue la diferencia en la experiencia, como todavía no existe el vocabulario de computación para explicarlo, hay que insistir bastante o pedir que te lo muestren directamente, pero al final siempre se llega a la misma conclusión: el artifact es HTML. La experiencia agradable viene de iterar sobre archivos HTML (+CSS+imágenes) en el sistema de archivos con renderizado inmediato de alta calidad, y si hace falta, también puedes espolvorear un poco de JavaScript. Si tienen un sistema git, hasta podrían estar versionando sin darse cuenta. Si no lo tienen, les recomiendo hacer checkpoints. Tal vez el control de versiones sea el siguiente paso de aprendizaje para la gente común
    En cambio, la experiencia incrustada en la web consiste en picotear muchas veces un DOCX/PPTX/XLSX que se quedó dentro de la ventana de contexto y lidiar con una idea borrosa de almacenamiento local. Y eso incluso cuando en realidad se está renderizando como HTML en una barra lateral. El flujo de trabajo con HTML también facilita mucho integrar otros medios. Al final, este tipo de trabajo de presentación es vibe coding para las masas, y no hace falta entender todas las tortugas que hay debajo. Pero, si quieres, puedes abrirlo, modificarlo o pasárselo fácilmente a otro agente. Un sistema creado para comunicación multimedia colaborativa terminó siendo útil para que la inteligencia de máquina ayude a nuestra comunicación

  • Antes hacíamos que el agente de nosotros (https://www.definite.app/) escribiera reportes y dashboards en una especificación YAML que renderizaba un framework frontend
    Por ejemplo, si un usuario decía “hazme un reporte que muestre ventas mensuales y cantidad de pedidos, y también los 100 pedidos más recientes”, el agente escribía la especificación que luego se renderizaba en el frontend. Este enfoque era rápido, pero quedábamos enterrados bajo solicitudes de funciones que el framework pudiera renderizar. Cosas como “aquí quiero quitar la etiqueta”, “allá sí necesito una etiqueta”, “¿se puede hacer este gráfico como heatmap?”. Hace unos meses pasamos a dejar que el agente simplemente escriba HTML, y aunque la generación tarda más, ya no hay límites para la personalización. El nuevo enfoque también tiene problemas, como que usuarios no técnicos tengan que depurar las apps monstruosas que ellos mismos crearon, pero en general a los clientes les gusta mucho más

    • En este caso, ¿cómo están evitando la inyección de prompts?

  • Para salidas largas de agentes, leo usando VIM y macOS Quick Look (con extensiones de renderizado de Markdown), o pegándolo en MarkEdit, que tiene panel de vista previa
    En el peor de los casos, puedes hacer que el agente cree una página web local simple que interprete y renderice Markdown. Markdown se inventó como una abreviatura de la sintaxis web [0], y justo sirve para eso. Me parece que los tokens y el tiempo que cuesta pedirle al agente que convierta Markdown básico a HTML son mayores que usar estos métodos
    0. https://daringfireball.net/projects/markdown/

    • Sí, es probable que use más tokens, pero como el autor trabaja en Anthropic, supongo que nunca ha tenido que pagar directamente el costo de los tokens
    • Si quieres llevar el vibe hasta el final, ¿no bastaría con pedirle al bot que también te resuma las salidas largas?
      Usar bots se está volviendo realmente caótico y autorreferencial
    • Me da curiosidad cuál extensión de Quick Look es. He estado buscando una decente