Markdown Fue un Error para la Salida de Agentes. Un Ingeniero de Código de Claude Acaba de Demostrarlo.

6 min read

"HTML es el nuevo markdown."

Eso dice Thariq Shihipar, del equipo Claude Code en Anthropic, en X la semana pasada.

PERO

CLAUDE.md, AGENTS.md, SKILL.md... Markdown por todas partes. Se volvió el aire que respiras en un proyecto de Claude Code, el formato por defecto que nadie decidió conscientemente. Así que cuando el agente produce una salida, entrega Markdown. Es lo que ha visto en todos lados.

Entonces Thariq suelta una galería de veinte artefactos HTML para respaldar su afirmación.

RESUMEN: Markdown se apoderó de nuestros proyectos a través de archivos de configuración (CLAUDE.md, AGENTS.md, SKILL.md), luego se filtró a todo lo demás, incluyendo las salidas de agentes que nadie lee. Un miembro del equipo Claude Code acaba de explicar por qué cambió a HTML, y todo se reduce a un comando corto.

Para un archivo de configuración, perfecto. Corto, instructivo, se lee una vez y se guarda en contexto. ¿Pero cuando el agente te entrega un plan de 200 líneas o un reporte de revisión de código? Otra historia. Lo abres, lees quince líneas, cierras la pestaña. Tres días después le preguntas al agente otra vez porque no recuerdas nada de lo que decidió.

El agente funcionó bien. El formato lo hizo desaparecer.

Volvamos a lo básico. HTML es anterior a Markdown por más de una década. El navegador se construyó alrededor de él. Markdown siempre fue una abreviación.

Trabajador de oficina abrumado por texto markdown infinito en el monitor, mientras una figura de superhéroe señala una interfaz HTML limpia con tablas organizadas y botones
Salida en Markdown: donde la legibilidad va a morir una muerte lenta y dolorosa.

Por Qué Ganó Markdown: La Excusa de los 8,192 Tokens

En 2022, ChatGPT llegó con una ventana de contexto de 8,192 tokens. No es mucho. Para el mismo contenido, HTML quema aproximadamente 3x más tokens que Markdown (las cifras de web2md.org son cerca de 8,000 tokens para HTML versus 2,800 para el equivalente en Markdown). Cuando tu presupuesto es 8K y tu salida recorta tu entrada, cada token ahorrado es un párrafo que sobrevive.

Markdown ganó esa pelea por costo.

Simon Willison, una de las voces más fuertes en la comunidad de desarrolladores de IA, lo admitió públicamente la semana pasada: había estado escribiendo Markdown para LLMs desde los días de GPT-4 exactamente por esa razón. No estaba equivocado. Nadie estaba equivocado, dadas las matemáticas de ese momento, y las matemáticas funcionaban.

Ya no. Las ventanas de contexto en 2026 están en un millón de tokens y subiendo. La restricción que hizo racional a Markdown se evaporó. El comportamiento no. Seguimos metiendo archivos .md en nuestros proyectos porque es lo que siempre habíamos hecho, no porque fuera la decisión correcta para lo que hacemos ahora.

Pura inercia a estas alturas.

La Comunidad Ya Ha Hecho Esto Antes

La comunidad de IA adopta formatos en oleadas. Alguien prueba algo, funciona, se extiende, y tres años después levantamos la vista y notamos que la opción obvia desde el primer día estaba ahí mismo.

El mismo ciclo para Markdown en salidas de agentes: adoptado rápido, cuestionado tarde.

El mismo instinto me llevó a argumentar, hace unos meses, que los CLIs superan a MCP para agentes de IA. La comunidad había saltado a MCP porque era nuevo y brillante, mientras que la solución aburrida y estable había estado desplegada en producción por décadas. Hacemos esto cada doce meses sin falta.

¿La diferencia esta vez? Es alguien de dentro de Anthropic tocando la campana.

Lo Que Realmente Hace un Miembro del Equipo Claude Code

Thariq Shihipar, del equipo Claude Code en Anthropic, acaba de publicar un post con veinte ejemplos concretos. No teoría. Prompts reales, salidas reales, y artefactos que puedes abrir en tu navegador ahora mismo.

La galería muestra lo que un agente puede entregarte en HTML que Markdown no puede hacer estructuralmente. Una comparación de especificaciones lado a lado con dos columnas, diferencias codificadas por color, y una caja de veredicto en la parte inferior. Un reporte de revisión de código donde el diff está anotado en línea, puntos de severidad en rojo/ámbar/verde, enlaces de salto a cada hallazgo. O el editor desechable que viene con un botón "copiar como JSON" que nunca pediste pero usas inmediatamente.

Lo que trae HTML: tablas que se renderizan, colores que significan algo, diagramas SVG, pestañas, layouts responsivos para móvil, bits interactivos cuando los necesitas. Lo que trae Markdown: un scroll largo.

Lo que importa no es lo bonito. Es esta línea del post de Thariq:

"Me siento más en el bucle que nunca cuando uso HTML. Honestamente he dejado de usar Markdown por completo para casi todo."

En el bucle. Ese es todo el juego. Un agente que produjo un plan perfecto que no leíste es un agente que no hizo nada. La salida existe en un sentido metafísico, claro. La decisión que documentó se fue en el momento que cerraste la pestaña. Un archivo Markdown que pasas scrolleando es lo mismo que ningún archivo. ¿Un archivo HTML que abres en tu navegador, compartes por enlace, capturas para Slack? Ese archivo existe. La gente lo lee. Tú lo lees. Te mantienes consciente de lo que tu agente decidió.

El verdadero desbloqueo es mantenerte parte del flujo de trabajo. Los artefactos que se ven mejor son un efecto secundario.

Un plan que nunca se lee es un plan que nunca se escribió.

Las Advertencias Honestas

HTML cuesta más tokens. El costo de tokens es toda la resistencia contra el post de Thariq. Cuando llegó el anuncio, una cuenta en X (@EXM7777) respondió: "sí claro voy a gastar 5x la cantidad de tokens por archivos de texto que se ven bien." La respuesta tuvo tracción porque suena correcto.

Es correcto, para un caso específico. Es incorrecto para el caso del que habla Thariq.

Si el lector principal de tu salida es otro LLM (un agente downstream que va a consumir el archivo, parsearlo, y actuar sobre él), Markdown está bien. Al agente no le importan los colores. No renderiza tablas. Los tokens son lo único que importa. La misma lógica para salidas rápidas de borrador que vas a tirar en tres minutos, para pipelines de alto rendimiento donde generas doscientos archivos por hora, para cualquier cosa donde el costo por salida domine el valor de la salida.

Si el lector principal de tu salida es un humano (y tú, querido constructor, eres un humano, incluso el viernes por la tarde cuando ya mentalmente te fuiste y el barco para ver delfines sale en dos horas), el cálculo se voltea. El costo es unos centavos extra en tokens. El valor es si realmente lees la cosa. Un plan de 5 centavos que lees le gana a un plan de 1 centavo que ignoraste, siempre.

La otra advertencia real que Thariq admite él mismo: los archivos HTML son dolorosos para hacer diff en git. Markdown se lee limpiamente en un pull request. HTML envuelve todo en una sopa de tags que hace miserable la revisión línea por línea. Si el artefacto va a vivir en un repo y ser revisado a través de commits, Markdown sigue ganando.

Cloudflare también empuja Markdown para el flujo de entrada del agente, convirtiendo páginas web a Markdown para que los agentes puedan consumirlas eficientemente. Conversación diferente. Web → agente es entrada. Agente → humano es salida. Ambas pueden ser verdad al mismo tiempo sin contradicción.

Si tu lector es un modelo, Markdown. Si tu lector eres tú, HTML.

Un Prompt. Sin Configuración.

Todo el cambio cabe en una oración al final de tu prompt:

"Haz esto como un archivo HTML único."

Eso es todo. Sin editar CLAUDE.md, sin scaffolding de skills, sin configuración. Thariq es explícito sobre esto: no lo sobre-ingenierices. Prueba el prompt en tu próxima tarea de planificación. Ve qué sale. Si te encuentras usándolo tres veces seguidas, entonces tal vez piensa en un skill. No antes.

El mismo reflejo de no-sobre-ingenierizar que cuando un solo repo open-source convirtió Claude Code en un arquitecto n8n funcional. El repo fue el desbloqueo. Todo lo que traté de construir alrededor solo estorbó.

La galería tiene veinte ejemplos ordenados por caso de uso: planificación, revisión de código, diseño, prototipado, diagramas, presentaciones, investigación, reportes, editores personalizados. Escoge el más cercano a lo que vas a hacer mañana. Roba la estructura del prompt. Envía.

Mi último plan se abrió en el navegador con pestañas, un diff codificado por color, y un botón "copiar como JSON" que nunca pedí. Lo leí todo. Por primera vez en un rato, sabía exactamente lo que mi agente había decidido sin tener que volver y leerlo tres veces.

Prueba "haz esto como un archivo HTML único" en tu próximo plan. Lo vas a leer.

Fuentes