Fa pocs dies, Thariq Shihipar (engineer de l'equip Claude Code a Anthropic) va articular públicament en un podcast el que a onext fa mesos que observem en client: HTML és ja el format superior per als artefactes que viuen, s'editen i es consumeixen més. El que segueix és la taula de decisió que apliquem artefacte a artefacte al mètode AI Engine — què migra a HTML, què es queda en Markdown, i per què la decisió importa més en uns que en altres.
Per què Markdown es converteix en fricció en escalar
Markdown va ser popular durant una dècada per dues raons que importaven molt: era llegible per humans sense renderitzar i alhora processable per màquines. Aquesta doble compatibilitat li va donar avantatge sobre Word, Confluence, Notion i qualsevol format tancat. En equips petits amb specs curtes, Markdown continua sent perfecte: un fitxer spec-feature-x.md de cinquanta línies al repo és exactament el que l'equip necessita.
El problema apareix en escalar. Quan un Tech Lead rep un pla d'implementació de mil cinc-centes línies en Markdown, el que passa a la pràctica és un de dos comportaments: o el llegeix per sobre fent scroll ràpid, o el delega sencer a l'agent perquè l'editi. Tots dos són fracassos del format. El primer perquè l'humà deixa de governar el contingut. El segon perquè l'humà deixa d'estar al loop.
Thariq ho articula així: "vaig deixar de llegir plans Markdown de mil línies i vaig començar a demanar-li a Claude que els editi directament, cosa que em va fer estar menys implicat en la feina. HTML va canviar això: en convertir els plans en artefactes visuals, amb scroll, interactius, Claude fa que l'output sigui més fàcil de llegir, criticar i millorar". La lliçó no és llegir menys. És fer la feina prou llegible perquè de veritat la llegeixis.
Les quatre raons per les quals HTML supera Markdown en els casos correctes
L'argumentació, sintetitzada del podcast original i del que veiem en client, cap en quatre punts:
Densitat informativa
HTML incrusta imatges, mockups, taules amb scroll horitzontal, blocs de codi amb syntax highlighting real, seccions col·lapsables. Markdown pot mostrar taules, però no pot mostrar un mockup al costat de la descripció funcional. Quan l'artefacte necessita aquest tipus de context, Markdown obliga a separar el que hauria d'anar junt.
Interactivitat
HTML permet navegar l'artefacte: índex plegable, anchors, seccions col·lapsables, formularis per editar parts específiques. Markdown és pla. En un pla de mil línies, navegar importa.
Living documents
Un fitxer HTML es pot actualitzar, recarregar i mostrar sempre la versió vigent del design system o de l'estat del projecte. Markdown és estàtic per construcció. La diferència importa quan l'artefacte viu sis mesos o més.
Paritat human + machine readable
Aquesta és la novetat real respecte al 2020. Fa cinc anys, HTML era difícil de llegir en pla per a un humà sense renderitzar. Avui un Claude o un Cursor parseja HTML amb la mateixa facilitat que Markdown, i un humà l'obre a qualsevol navegador amb un clic. El tradeoff històric ja no existeix.
Aquests quatre punts no apliquen a tots els artefactes per igual. La pregunta operativa és: quins sí, quins no?
La taula de decisió · 14 artefactes del Spec-Driven Development al mètode AI Engine onext
El programa AI Engine genera de l'ordre de quinze artefactes diferents durant un cicle complet de transformació. La decisió Markdown o HTML no es fa per gust — es fa en funció de tres preguntes: quina mida té l'artefacte en plenitud?, es consumeix una vegada o es viu durant mesos?, necessita representació visual per entendre's?
Amb aquests tres eixos, aquesta és la taula actual del mètode onext a juny de 2026:
| Artefacte | Decisió | Per què |
|---|---|---|
| Constitució del projecte | Markdown | Text pur, regles estables, versionable al repo, simple d'auditar |
| Lean Canvas / JTBD / empathy maps | Quadrants visuals, persones amb foto, fluxos navegables | |
| User flows / behavior flows | Diagrames SVG incrustats, navegació interactiva | |
| Acceptance criteria (llista breu, <20 ítems) | Markdown | Text breu, checklist simple, casa amb la PR description |
| Acceptance criteria + casos límit (taula àmplia) | Taula amb scroll, codi incrustat per cas, millor densitat | |
| Business rules | Matrius de decisió, flowcharts, condicionals complexos | |
| Specs per feature (<500 línies) | Markdown | Compacte, navegable, casa amb el flux PR |
| Specs per feature (>500 línies) | Scroll + densitat + seccions col·lapsables (el cas de Thariq) | |
| Implementation plans (plans de milers de línies) | Cas canònic — Markdown es torna inmanejable més enllà de 800 línies | |
| Status updates setmanals | «Més probable que de veritat es llegeixi» — Thariq | |
| Living design system | El cas «killer app» — supera Figma segons Thariq, alineat amb el que veiem | |
| ADRs (Architecture Decision Records) | Markdown | Històrics breus, append-only, no s'editen després d'escriure |
| Dashboards de progrés de transformació | Interfícies, no documents — xifres vives, comparatives, drill-down | |
| Onboarding tècnic de developers nous | Interactiu, navegable, incrusta mockups i codi executable |
Dels 14 artefactes: 8 HTML · 5 Markdown · 1 depèn de la mida
Dels catorze artefactes del mètode, vuit migren a HTML, cinc es queden en Markdown, un depèn de la mida. La distribució no és ideològica — és operativa: a més mida i més vida útil, més sentit té HTML. A menys mida i més estabilitat textual, millor Markdown.
El reframe operacional · el rol del Tech Lead com a "compute allocator"
Thariq introdueix al podcast un reframe que convé tenir a sobre de la taula del proper planning. L'argument és que quan un Claude pot córrer vuit hores en una sola tasca, el que decideixes ja no és "quin codi escric" — és "com gasto cinc-cents dòlars de compute". L'habilitat crítica deixa de ser escriure codi i passa a ser decidir què val la pena construir, definir els límits del que necessites saber, i mantenir-te en sincronia amb l'agent durant el procés. Això passa primordialment a la fase de spec i pla.
Per a un Tech Lead que arriba de la disciplina clàssica de code review, el canvi és subtil però important: el code review passa a ser parcialment automatitzable, mentre que el "plan review" es converteix en l'activitat de més impacte del rol. I els plans — quan són grans — necessiten un format que permeti revisar-los de veritat. D'aquí la taula.
Una altra dada del podcast que se cita poc i es cita malament: Thariq estima que només al voltant de l'1% dels tokens que la seva instància de Claude genera acaben en codi de producció. L'altre 99% va a dashboards, status updates, micro-apps per editar plans, eines de comprensió, visualitzacions de dades. Això no és malbaratament — és el que fa que el mètode funcioni. Quan els tokens són barats, et pots permetre fer bonic i a mida cada cosa amb què vas a interactuar. El compute deixa de ser el coll d'ampolla; el coll d'ampolla és l'atenció humana.
Com evoluciona el mètode AI Engine onext en conseqüència
El programa AI Engine no canvia la seva filosofia: els tres claims canònics segueixen vigents — el model no és la font de veritat, el chat no és el sistema, el codi no és l'únic artefacte. El que canvia és el suport d'alguns d'aquests artefactes.
Concretament, en l'actualització del mètode que apliquem des de mitjans de maig:
L'actualització és retrocompatible. Un equip client que va entrar al programa AI Engine amb artefactes Markdown segueix funcionant — la migració a HTML on correspon es fa gradualment durant la fase 4 (Transferència), sense pausar sprints, al ritme de l'equip.
El que NO canvia
Convé tancar amb la part honesta. Aquesta no és una peça sobre la victòria de HTML sobre Markdown. És una peça sobre saber quan es fa servir cadascun. Tres coses que no canvien:
- El nostre manifest segueix vigent. Canvia el suport d'alguns artefactes; no canvia que el model no és la font de veritat, que el chat no és el sistema, que el codi no és l'únic artefacte. Si el teu equip no ha interioritzat aquests tres abans de migrar formats, migrar formats no resoldrà res.
- La constitució del projecte segueix sent Markdown per defecte. És l'artefacte més estable, més auditat i més simple del mètode. HTML no aporta avantatge aquí.
- El mètode no es compra ni amb HTML ni amb Markdown. El 70% de l'èxit de la IA en un equip és organitzatiu — carrils humà-agent definits, framework de mètriques reals, governança de quality gates, formació dual i pla de sosteniment. Migrar artefactes a HTML sense tenir això al seu lloc és canviar la tipografia del document mentre l'equip es crema.
L'elecció de format — HTML aquí, Markdown allà — és un component concret d'aquest mètode. No és el més important. Però quan l'equip escala més enllà de tres o quatre specs actives, la decisió sí que marca diferència.
Si vols revisar com aplica la taula al teu equip concret — quins artefactes són els teus, quina mida tenen, què canviaria migrar els que corresponen — parlem-ne: info@onext.es — assumpte «decisió HTML/Markdown». Conversa de trenta minuts sense compromís.
