Hace pocos días, Thariq Shihipar (engineer del equipo Claude Code en Anthropic) articuló públicamente en un podcast lo que en onext llevamos meses observando en cliente: HTML es ya el formato superior para los artefactos que viven, se editan y se consumen más. Lo que sigue es la tabla de decisión que aplicamos artefacto a artefacto en el método AI Engine — qué migra a HTML, qué se queda en Markdown, y por qué la decisión importa más en unos que en otros.
Por qué Markdown se vuelve fricción al escalar
Markdown fue popular durante una década por dos razones que importaban mucho: era legible por humanos sin renderizado y al mismo tiempo procesable por máquinas. Esa doble compatibilidad le dio ventaja sobre Word, Confluence, Notion y cualquier formato cerrado. En equipos pequeños con specs cortas, Markdown sigue siendo perfecto: un fichero spec-feature-x.md de cincuenta líneas en el repo es exactamente lo que el equipo necesita.
El problema aparece al escalar. Cuando un Tech Lead recibe un plan de implementación de mil quinientas líneas en Markdown, lo que pasa en la práctica es uno de dos comportamientos: o lo lee por encima haciendo scroll rápido, o lo delega entero al agente para que lo edite. Ambos son fracasos del formato. El primero porque el humano deja de gobernar el contenido. El segundo porque el humano deja de estar en el loop.
Thariq lo articula así: "dejé de leer planes Markdown de mil líneas y empecé a pedirle a Claude que los editara directamente, lo cual me hizo menos involucrado en el trabajo. HTML cambió eso: al convertir los planes en artefactos visuales, scroll, interactivos, Claude hace que el output sea más fácil de leer, criticar y mejorar". La lección no es leer menos. Es hacer el trabajo lo suficientemente legible como para que de verdad lo leas.
Las cuatro razones por las que HTML supera a Markdown en los casos correctos
La argumentación, sintetizada del podcast original y de lo que vemos en cliente, cabe en cuatro puntos:
Densidad informativa
HTML embebe imágenes, mockups, tablas con scroll horizontal, bloques de código con syntax highlighting real, secciones colapsables. Markdown puede mostrar tablas, pero no puede mostrar un mockup junto a la descripción funcional. Cuando el artefacto necesita ese tipo de contexto, Markdown obliga a separar lo que debería ir junto.
Interactividad
HTML permite navegar el artefacto: índice plegable, anchors, secciones colapsables, formularios para editar partes específicas. Markdown es plano. En un plan de mil líneas, navegar importa.
Living documents
Un fichero HTML puede actualizarse, recargarse y mostrar siempre la versión vigente del design system o del estado del proyecto. Markdown es estático por construcción. La diferencia importa cuando el artefacto vive seis meses o más.
Paridad human + machine readable
Esta es la novedad real respecto a 2020. Hace cinco años, HTML era difícil de leer en plano para un humano sin renderizar. Hoy un Claude o un Cursor parsea HTML con la misma facilidad que Markdown, y un humano lo abre en cualquier navegador con un click. El tradeoff histórico ya no existe.
Esos cuatro puntos no aplican a todos los artefactos por igual. La pregunta operativa es: ¿cuáles sí, cuáles no?
La tabla de decisión · 14 artefactos del Spec-Driven Development en el método AI Engine onext
El programa AI Engine genera del orden de quince artefactos distintos durante un ciclo completo de transformación. La decisión Markdown o HTML no se hace por gusto — se hace en función de tres preguntas: ¿qué tamaño tiene el artefacto en plenitud?, ¿se consume una vez o se vive durante meses?, ¿necesita representación visual para entenderse?
Con esos tres ejes, ésta es la tabla actual del método onext a junio de 2026:
| Artefacto | Decisión | Por qué |
|---|---|---|
| Constitución del proyecto | Markdown | Texto puro, reglas estables, versionable en repo, simple de auditar |
| Lean Canvas / JTBD / empathy maps | Cuadrantes visuales, personas con foto, flujos navegables | |
| User flows / behavior flows | Diagramas SVG embebidos, navegación interactiva | |
| Acceptance criteria (lista breve, <20 ítems) | Markdown | Texto breve, checklist simple, casa con PR description |
| Acceptance criteria + casos límite (tabla amplia) | Tabla con scroll, código embebido por caso, mejor densidad | |
| Business rules | Matrices de decisión, flowcharts, condicionales complejos | |
| Specs por feature (<500 líneas) | Markdown | Compacto, navegable, casa con el flujo PR |
| Specs por feature (>500 líneas) | Scroll + densidad + secciones colapsables (el caso de Thariq) | |
| Implementation plans (planes de miles de líneas) | Caso canónico — Markdown se vuelve inmanejable más allá de 800 líneas | |
| Status updates semanales | «Más probable que de verdad se lea» — Thariq | |
| Living design system | El caso «killer app» — supera a Figma según Thariq, alineado con lo que vemos | |
| ADRs (Architecture Decision Records) | Markdown | Históricos breves, append-only, no se editan tras escribir |
| Dashboards de progreso de transformación | Interfaces, no documentos — cifras vivas, comparativas, drill-down | |
| Onboarding técnico de developers nuevos | Interactivo, navegable, embebe mockups y código ejecutable |
De 14 artefactos: 8 HTML · 5 Markdown · 1 depende del tamaño
De los catorce artefactos del método, ocho migran a HTML, cinco se quedan en Markdown, uno depende del tamaño. La distribución no es ideológica — es operativa: a mayor tamaño y mayor vida útil, mayor sentido tiene HTML. A menor tamaño y mayor estabilidad textual, mejor Markdown.
El reframe operacional · el rol del Tech Lead como "compute allocator"
Thariq introduce en el podcast un reframe que conviene tener encima de la mesa del próximo planning. El argumento es que cuando un Claude puede correr ocho horas en una sola tarea, lo que decides ya no es "qué código escribo" — es "cómo gasto quinientos dólares de compute". La habilidad crítica deja de ser escribir código y pasa a ser decidir qué vale la pena construir, definir los límites de lo que necesitas saber, y mantenerte en sincronía con el agente durante el proceso. Eso ocurre primordialmente en la fase de spec y plan.
Para un Tech Lead que llega de la disciplina clásica de code review, el cambio es sutil pero importante: el code review pasa a ser parcialmente automatizable, mientras que el "plan review" se vuelve la actividad de mayor impacto del rol. Y los planes — cuando son grandes — necesitan formato que permita revisarlos de verdad. De ahí la tabla.
Otro dato del podcast que se cita poco y se cita mal: Thariq estima que solo alrededor del 1% de los tokens que su instancia de Claude genera acaban en código de producción. El otro 99% va a dashboards, status updates, micro-apps para editar planes, herramientas de comprensión, visualizaciones de datos. Eso no es desperdicio — es lo que hace que el método funcione. Cuando los tokens son baratos, puedes permitirte hacer hermoso y a medida cada cosa que vas a interactuar con. El compute deja de ser el cuello de botella; el cuello de botella es la atención humana.
Cómo evoluciona el método AI Engine onext en consecuencia
El programa AI Engine no cambia su filosofía: los tres claims canónicos siguen vigentes — el modelo no es la fuente de verdad, el chat no es el sistema, el código no es el único artefacto. Lo que cambia es el soporte de algunos de esos artefactos.
Concretamente, en la actualización del método que aplicamos desde mediados de mayo:
La actualización es retrocompatible. Un equipo cliente que entró en el programa AI Engine con artefactos Markdown sigue funcionando — la migración a HTML donde corresponde se hace gradualmente durante la fase 4 (Transferencia), sin pausar sprints, en el ritmo del equipo.
Lo que NO cambia
Conviene cerrar con la parte honesta. Esta no es una pieza sobre la victoria de HTML sobre Markdown. Es una pieza sobre saber cuándo se usa cada uno. Tres cosas que no cambian:
- Nuestro manifiesto sigue vigente. Cambia el soporte de algunos artefactos; no cambia que el modelo no es la fuente de verdad, que el chat no es el sistema, que el código no es el único artefacto. Si tu equipo no ha interiorizado esos tres antes que migrar formatos, migrar formatos no va a resolver nada.
- La constitución del proyecto sigue siendo Markdown por defecto. Es el artefacto más estable, más auditado y más simple del método. HTML no aporta ventaja allí.
- El método no se compra ni con HTML ni con Markdown. El 70% del éxito de la IA en un equipo es organizativo — carriles humano-agente definidos, framework de métricas reales, gobernanza de quality gates, formación dual y plan de sostenimiento. Migrar artefactos a HTML sin tener eso en su lugar es cambiar la tipografía del documento mientras el equipo se quema.
La elección de formato — HTML aquí, Markdown allá — es un componente concreto de ese método. No es lo más importante. Pero cuando el equipo escala más allá de tres o cuatro specs activas, la decisión sí marca diferencia.
Si quieres revisar cómo aplica la tabla a tu equipo concreto — qué artefactos son los tuyos, qué tamaño tienen, qué cambiaría migrar los que corresponde — hablemos: info@onext.es — asunto «decisión HTML/Markdown». Conversación de treinta minutos sin compromiso.