Cuando trabajamos con Claude Code, solemos recurrir por costumbre a ficheros Markdown para planificar, documentar o pedirle al asistente que redacte un informe. Sin embargo, existe una alternativa mucho más potente y flexible que muchos desarrolladores están empezando a adoptar: usar HTML como formato de trabajo en lugar de .md. Este artículo explica por qué el HTML puede convertirse en tu mejor aliado a la hora de sacar el máximo partido a Claude Code, basándonos en la experiencia compartida por Thariq Shihipar, ingeniero de Anthropic, en el blog oficial de Claude.
La idea central es simple pero transformadora: el HTML no es solo un lenguaje de marcado para páginas web, es un lenguaje expresivo capaz de representar estructura, estilo e interactividad en un único fichero autocontenido. Eso lo convierte en un lienzo mucho más rico que el texto plano de Markdown para casi cualquier tarea en la que Claude Code participe.
Revisión y comprensión de código
El código puede ser difícil de leer en un fichero Markdown plano, pero con HTML podemos generar representaciones mucho más ricas: diferencias de color (diffs), anotaciones, diagramas de flujo o módulos interactivos. Usar HTML permite a Claude Code entender el código que el propio agente ha escrito, revisarlo, o incluso explicar un pull request a otra persona del equipo de forma visual y didáctica.
“Ayúdame a revisar este PR creando un artefacto HTML que lo describa. No conozco bien la lógica de streaming/backpressure, así que céntrate en eso. Renderiza el diff real con anotaciones en el margen, hallazgos codificados por color según gravedad y cualquier otra cosa que ayude a transmitir el concepto.”
Este enfoque resulta especialmente útil para crear un pull request, revisarlo o entender un tema concreto del código sin perderse en párrafos de texto sin formato.
Diseño y prototipado
Claude Design se basa en HTML porque es un lenguaje increíblemente expresivo para el diseño, incluso cuando el resultado final no es una página web. Se puede bocetar un diseño en HTML y después traducirlo al lenguaje que se necesite: React, Swift o cualquier otro framework.
También es posible prototipar interacciones como animaciones o acciones concretas. Se le puede pedir a Claude que construya deslizadores, mandos o controles para ajustar exactamente el comportamiento que se busca antes de llevarlo a producción.
“Quiero prototipar una nueva animación de pago que, al hacer clic, cambie de color rápidamente. Crea un fichero HTML con varias opciones y un botón para copiar los parámetros de la que funcione mejor.”
Este flujo de trabajo es ideal para crear artefactos de sistemas de diseño, ajustar componentes, visualizar librerías de componentes o prototipar animaciones.
Informes, investigación y aprendizaje
Claude Code es muy eficaz sintetizando información de múltiples fuentes y convirtiéndola en un informe fácil de leer. Se le puede pedir que busque código, historial de commits, información en internet, y que la use para generar un informe claro y bien estructurado.
Todo esto se puede ensamblar en forma de documento HTML, un explicador interactivo o incluso una presentación de diapositivas. También se le puede pedir a Claude que use SVG para diagramas que ayuden a visualizar la información.
“No entiendo cómo funciona realmente nuestro limitador de tasa (rate limiter). Lee el código relevante y produce una única página HTML explicativa: un diagrama del flujo token-bucket, los fragmentos de código clave anotados y una sección de ‘trampas habituales’ al final. Optímizalo para que se pueda leer de un vistazo.”
Este uso resulta perfecto para redactar resúmenes de funcionalidades, informes semanales de estado, explicar incidencias técnicas o producir ilustraciones SVG y diagramas de flujo.
Interfaces de edición personalizadas
A veces resulta muy difícil describir con palabras exactamente lo que se necesita en un cuadro de texto. En estos casos, es mucho más práctico pedirle a Claude que construya una interfaz desechable y de un solo uso: un fichero HTML único y autocontenido.
El truco está en terminar siempre con una exportación: un botón “copiar como JSON” o “copiar como prompt” que convierta lo que se ha hecho en la interfaz de nuevo en algo que se pueda pegar en Claude Code para confirmarlo en un fichero. Así se permanece en el bucle de trabajo y el ciclo se cierra de forma mucho más ajustada.
“Necesito volver a priorizar estos 30 tickets de Linear. Házme un fichero HTML con cada ticket como una tarjeta arrastrable en columnas Ahora / Después / Más tarde. Ordena por tu mejor estimación. Incluye un botón ‘copiar como Markdown’ que exporte el orden final con una razón de una línea por cubo.”
Este enfoque funciona muy bien para reordenar, priorizar o categorizar cualquier cosa (tickets, casos de prueba, feedback), editar configuraciones estructuradas (feature flags, variables de entorno, JSON o YAML con restricciones), ajustar prompts, plantillas o copiar con vista previa en directo, seleccionar conjuntos de datos, anotar documentos o transcripciones, y elegir valores difíciles de expresar en texto como colores, recortes de imagen o rangos de fechas.
Preguntas frecuentes
¿No es menos eficiente?
Aunque Markdown suele usar menos tokens, la expresividad adicional del HTML y la mayor probabilidad de que se lea suele traducirse en un resultado global mejor. Con la ventana de contexto de un millón de tokens de Opus 4.5, el aumento en el uso de tokens no supone un problema notable en la práctica diaria.
¿Cuándo se sigue usando Markdown?
El propio autor del artículo original reconoce que ha dejado de usar Markdown casi por completo. Probablemente sea más purista del HTML que la mayoría, pero la tendencia apunta en esa dirección.
¿Es esto planificación reutilizable?
Tener un único fichero HTML tiende a ser doloroso a la hora de expresar diferentes partes o etapas de un plan. Por eso suele ser mejor tener varios ficheros HTML diferentes: uno por cada etapa de implementación del plan y otro para la exploración, además de un componente HTML final que enumere todo, a modo de referencia durante la verificación.
Conclusión: mantenerse en el bucle con Claude
La razón de fondo para usar HTML en lugar de Markdown es que ayuda a sentirse mucho más implicado en el proceso de trabajo con Claude Code. A medida que Claude Code toma más decisiones de forma autónoma, leer Markdown supone menos esfuerzo, pero también hace que sea más fácil desconectar de sus decisiones y dejar de prestar atención. El HTML, en cambio, mantiene la atención activa: se siente más presente en el bucle y menos como si se soltara el mando de control.
En definitiva, cambiar el hábito de trabajar con ficheros .md por ficheros .html en Claude Code no es solo una cuestión de formato: es una forma de ganar expresividad, mejorar la comprensión del código, prototipar diseños con rapidez, generar informes más claros, crear interfaces de edición a medida y, sobre todo, mantenerse mucho más cerca del proceso de decisión del agente.
