Claude Code y la eficacia irrazonable de los artefactos HTML
Markdown ganó la primera fase de la colaboración con agentes porque es simple.
Es fácil de generar, fácil de comparar en un diff, fácil de pegar en una pull request y suficientemente bueno para la mayoría de notas. Por eso se convirtió en el formato natural por defecto para coding agents: planes, resúmenes, especificaciones, notas de revisión, postmortems y listas de implementación terminaron como Markdown.
La publicación más reciente de Anthropic sobre Claude Code argumenta que ese valor por defecto empieza a mostrar sus límites.
El argumento no es que Markdown sea malo. Es que Claude Code ahora puede hacer más que escribir un archivo de texto largo, y HTML ofrece al modelo una mejor superficie para ese trabajo: más densidad de información, estructura visual más clara, artefactos más fáciles de compartir e interactividad ligera.
Para desarrolladores, es un cambio práctico. Cambia lo que deberíamos pedir a Claude Code que produzca.
La idea central
En el artículo oficial, Thariq Shihipar, del equipo de Claude Code, explica por qué empezó a preferir archivos HTML en lugar de Markdown para muchas salidas de Claude Code.
La razón es directa: a medida que Claude Code asume tareas más grandes, las salidas también crecen.
Una checklist Markdown de 30 líneas está bien. Un plan de implementación, informe de investigación, revisión de código, explicación de arquitectura o exploración de UI de 300 líneas no está bien solo porque técnicamente se renderice.
HTML da a Claude Code más espacio para organizar la misma información:
- tablas para comparaciones densas
- CSS para jerarquía visual
- SVG para diagramas
- imágenes para referencias
- JavaScript para interacciones locales
- pestañas y secciones para navegación
- botones para copiar prompts, JSON, diffs o configuraciones generadas
Eso hace que HTML sea menos un formato de documento y más una mesa de trabajo puntual.
Para flujos con agentes, esa diferencia importa.
Por qué importa para usuarios de Claude Code
Claude Code es distinto de una interfaz de chat normal porque puede leer el proyecto local, inspeccionar el historial de git, trabajar con archivos, usar servidores MCP y generar artefactos dentro del mismo workspace donde ocurre el trabajo real de ingeniería.
Eso lo hace especialmente adecuado para crear artefactos HTML útiles desde contexto real.
Por ejemplo, en lugar de pedir:
Write a plan for refactoring the billing module.
puedes pedir:
Create an HTML artifact that explains the billing refactor.
Include a module map, the key file changes, risks by severity,
a staged migration plan, and a copyable implementation prompt.
Esos dos prompts pueden contener la misma solicitud de fondo, pero el segundo pide un formato más fácil de inspeccionar, más fácil de compartir y más fácil de usar como referencia en una sesión posterior de Claude Code.
Esa es la verdadera ventaja: HTML puede convertirse en contexto duradero del proyecto, no solo en una respuesta de una vez.
Cuatro lugares donde HTML supera a Markdown
1. Especificaciones y planificación
La planificación es donde Markdown empieza a sufrir primero.
Los planes de implementación largos suelen combinar arquitectura, fragmentos de código, dependencias, diagramas, tradeoffs, capturas de pantalla y preguntas abiertas. Markdown puede contener todo eso, pero no ayuda al lector a navegarlo.
HTML permite que Claude Code divida el plan en una superficie más revisable:
- resumen al inicio
- diagrama de flujo del sistema
- mapa de cambios archivo por archivo
- tabla de riesgos
- plan de despliegue por etapas
- preguntas abiertas
- prompts de seguimiento copiables
Eso es especialmente útil cuando un plan necesita sobrevivir entre sesiones. Un agente futuro puede leer el archivo HTML como contexto, mientras que una persona puede escanearlo sin leer una pared de texto.
2. Revisión y comprensión de código
La revisión de código no es solo texto. Es estructura.
Una buena revisión suele necesitar diff, etiquetas de severidad, módulos afectados, rutas de llamada, flujo de datos y explicaciones breves de por qué algo importa. Markdown puede aproximarlo, pero HTML puede renderizarlo directamente.
Para Claude Code, esto sugiere un flujo mejor:
Review this PR by creating an HTML artifact.
Show the diff with inline annotations, group findings by severity,
and include a small diagram of the streaming/backpressure path.
Eso convierte la salida de revisión en algo más parecido a un paquete de revisión interactivo. Puede seguir siendo temporal, pero es más fácil de entregar a otro ingeniero.
3. Diseño y prototipos
HTML es un destino natural para Claude Code cuando la salida tiene un componente visual o interactivo.
Aunque la aplicación de producción sea React, Swift, Kotlin u otra cosa, HTML sigue siendo una forma rápida de bosquejar layouts, comparar direcciones, probar movimiento y ajustar parámetros de UI.
El artículo original menciona sliders, knobs y botones de copia como primitivas útiles. Ese es el modelo mental correcto. Claude Code puede crear una interfaz desechable para elegir valores difíciles de describir en prosa:
- paletas de color
- curvas de easing
- densidad de componentes
- regiones de recorte
- variantes de prompt
- combinaciones de feature flags
- prioridades de tickets
Lo importante es la exportación. Un buen artefacto HTML debe terminar con algo útil: copiar como JSON, copiar como Markdown, copiar como prompt o copiar diff.
Si el artefacto no puede devolver su salida al flujo de ingeniería, es solo una demo.
4. Informes, investigación y aprendizaje
Claude Code puede sintetizar entre codebase, historial de git, docs, Slack vía MCP, Linear vía MCP y fuentes web. Markdown puede resumir ese contexto, pero HTML puede hacerlo legible.
Para explicaciones internas, incident reviews, resúmenes semanales, auditorías de dependencias y guías de onboarding, HTML da al modelo suficiente espacio visual para mostrar relaciones en lugar de solo describirlas.
Aquí HTML se convierte en un formato de aprendizaje:
- fragmentos de código anotados
- diagramas de sistema
- llamadas de glosario
- vistas de timeline
- matrices de riesgo
- tablas de decisión
El resultado no necesita convertirse en un producto pulido. Solo necesita ser lo bastante legible para que alguien lo use.
El punto oculto: HTML mantiene a las personas en el loop
La parte más fuerte del artículo de Anthropic no es el argumento de formato. Es el argumento de workflow.
A medida que Claude Code gestiona tareas más grandes, los desarrolladores corren el riesgo de leer menos de lo que produce el agente. Los planes largos en Markdown son fáciles de aprobar sin revisar a fondo. Eso es peligroso, porque el plan puede contener suposiciones débiles, casos límite omitidos o cambios que el desarrollador no habría elegido.
HTML puede reducir ese modo de fallo porque da mejores puntos de agarre a la persona:
- escanear el resumen
- inspeccionar el diagrama
- comparar opciones lado a lado
- saltar a riesgos
- ajustar un slider
- copiar la salida seleccionada de vuelta a Claude Code
Eso no elimina la necesidad de revisión. Hace que la revisión sea más probable.
Para flujos serios con agentes, no es cosmética. Es parte del control.
Cuándo Markdown sigue siendo la mejor opción
HTML no debería reemplazar Markdown en todas partes.
Markdown sigue siendo mejor cuando el artefacto necesita ser:
- pequeño
- fácil de revisar en diff
- editado manualmente con frecuencia
- incrustado en un README
- pegado en una issue o descripción de PR
- consumido por herramientas que esperan Markdown
La regla práctica es simple:
Usa Markdown cuando la salida sea principalmente texto y vaya a ser editada por personas.
Usa HTML cuando la salida necesite layout, diagramas, comparación densa, interactividad o una mejor experiencia de lectura.
Así HTML no se convierte en otro valor por defecto abusado.
Un patrón de prompt simple
Si quieres probarlo en Claude Code, empieza con un prompt directo:
Create a single HTML artifact for this task.
It should be readable in a browser, self-contained, and optimized for review.
Use tables, diagrams, and sections where useful.
Add copy buttons for any output I may want to paste back into Claude Code.
Keep all source references visible.
Luego haz específico el propósito:
For this refactor, include:
- a dependency map
- the proposed file changes
- migration steps
- risks by severity
- test plan
- open questions
Con el tiempo, los patrones recurrentes deberían convertirse en skills o templates. Pero el primer paso no necesita infraestructura. Solo necesita el hábito de pedir a Claude Code un mejor artefacto.
Qué deberían hacer los equipos ahora
La oportunidad a corto plazo no es reconstruir todo el sistema interno de documentación alrededor de HTML.
El movimiento útil es más estrecho:
- Identifica las salidas de Claude Code que tu equipo realmente no lee.
- Convierte una de esas salidas en un artefacto HTML.
- Exige que el artefacto exporte algo útil de vuelta al workflow.
- Mantén el artefacto en el repo cuando ayude a sesiones futuras.
- Elimínalo cuando solo haya servido para una decisión.
Ese último punto importa. Muchos artefactos HTML deberían ser desechables. Su valor está en ayudar a una persona a tomar una mejor decisión ahora.
Conclusión
La eficacia irrazonable de HTML no está en que sea un mejor lenguaje de marcado que Markdown.
Está en que HTML da a Claude Code una superficie de colaboración más rica.
Para notas pequeñas, Markdown sigue siendo la herramienta correcta. Pero para especificaciones, revisiones de código, explicaciones de arquitectura, exploraciones de diseño, informes de investigación e interfaces de edición personalizadas, HTML puede hacer que la salida del agente sea más legible, más compartible y más accionable.
A medida que Claude Code se vuelve capaz de gestionar bloques de trabajo más grandes, el formato de salida se convierte en parte del diseño del workflow. Los equipos que traten los artefactos como superficies de revisión de primer nivel mantendrán más control que los equipos que sigan aprobando paredes de Markdown.
Fuente
- Claude blog: Using Claude Code: The unreasonable effectiveness of HTML
https://claude.com/blog/using-claude-code-the-unreasonable-effectiveness-of-html