L’articolo di Thariq parte da una frizione molto concreta per chi usa agenti di coding: Markdown funziona benissimo finché l’artefatto non diventa troppo lungo, troppo visuale o troppo interattivo. È portabile, leggibile, facile da modificare a mano. Ma quando un agente produce specifiche, esplorazioni, spiegazioni di pull request, report, mockup o piccoli editor usa e getta, Markdown smette di essere solo un formato e diventa un limite.
La tesi interessante non è che HTML sia più bello. È che HTML offre all’agente una superficie più ricca per pensare: struttura, layout, diagrammi, tabelle, controlli, link, immagini e piccole interazioni possono vivere nello stesso artefatto. L’output non è più un lungo file di testo, ma un’interfaccia leggibile.
Markdown Nasce per i Documenti
Markdown ha vinto perché è volutamente piccolo. Puoi leggerlo grezzo. Puoi fare diff puliti. Puoi incollarlo quasi ovunque. Per note scritte da umani, documentazione, README, changelog e specifiche leggere, questa sobrietà è un vantaggio.
Gli agenti cambiano la pressione sul formato. Non soffrono nel generare markup più verboso. Possono creare layout, CSS, diagrammi SVG, blocchi di codice annotati, griglie comparative e pulsanti copy senza percepire il costo come lo percepirebbe un autore umano. Il costo umano si sposta altrove: qualcuno leggerà davvero questo output?
Qui HTML diventa interessante. Un piano Markdown da 150 righe spesso chiede al lettore di simulare la gerarchia nella propria testa. Lo stesso artefatto in HTML può separare visivamente le sezioni, mettere alternative fianco a fianco, rendere leggibili i diagrammi e far emergere la prossima decisione invece di seppellirla nel testo.
Il miglior artefatto agentico non è quello più facile da generare per il modello. È quello che l'umano ha più probabilità di leggere, contestare e riusare.
L’Interfaccia Può Essere Temporanea
La parte più utile dell’idea è che il file HTML non deve diventare codice di prodotto. Può essere un’interfaccia temporanea, costruita per una singola decisione.
Devi confrontare sei direzioni per un onboarding? Genera una pagina con sei pannelli. Devi capire un diff delicato? Mostra il flusso, annota le righe rischiose e colora i finding per severità. Devi riordinare ticket, tarare un prompt, modificare feature flag o classificare righe di dataset? Costruisci un piccolo editor locale con un pulsante di export che trasforma le scelte umane in Markdown, JSON o prompt.
Non è un sostituto di design system, piattaforme di documentazione o UI di produzione. È un nuovo strato intermedio: interfacce operative generate dagli agenti. Sono temporanee, contestuali e ottimizzate per il momento in cui una persona deve decidere.
Perché Conta per Claude Code
Claude Code è particolarmente adatto a questo pattern perché lavora dentro il contesto del progetto. Può leggere codice, history, documentazione, test e file locali, poi sintetizzare un artefatto fondato sul sistema reale invece che su un prompt generico in browser.
Questo conta per code review e pianificazione. Un buon artefatto di review può mostrare il diff, spiegare il control flow, evidenziare invarianti e collegare le modifiche ai test. Un buon piano può includere mockup, data flow, ownership dei file, criteri di accettazione e una mappa di sequenziamento. Il formato permette al modello di unire spiegazione e ispezione nello stesso posto.
HTML Cambia il Ciclo di Review
Quando l’artefatto diventa visuale, anche l’umano può rispondere in modo diverso. Invece di dire “riscrivi questo piano”, può indicare una sezione, confrontare varianti, regolare uno slider, esportare opzioni selezionate o chiedere all’agente di preservare un ramo preferito dell’esplorazione.
Il file diventa così uno spazio di lavoro condiviso, non una risposta statica. L’agente crea la prima interfaccia. L’umano corregge la direzione. L’agente riconverte quel segnale in lavoro implementativo.
I Tradeoff Sono Reali
HTML non è gratis. È più rumoroso in version control. Può richiedere più tempo per essere generato. Un HTML scritto male può diventare un accumulo confuso di stili inline e complessità accidentale. Se l’artefatto deve essere mantenuto nel tempo, Markdown o un formato documentale strutturato possono restare scelte migliori.
C’è anche un confine di sicurezza. HTML generato da agenti va trattato come codice, soprattutto quando contiene script, dati locali o snippet da copiare. Aprilo localmente quando ha senso, evita risorse terze non fidate e non confondere un prototipo con una UI di produzione già revisionata.
La regola pratica è semplice: usa HTML quando l’artefatto ha bisogno di layout, confronto, visualizzazione, interazione o condivisione. Usa Markdown quando servono prosa durevole, diff puliti e poca cerimonia.
Da Dove Iniziare
Non serve un framework per adottare il pattern. Chiedi all’agente un singolo file HTML quando l’output diventerebbe altrimenti poco leggibile:
- trasformare un piano implementativo complesso in un brief navigabile di una pagina;
- trasformare una pull request in uno spiegone visuale con snippet annotati;
- trasformare una decisione di prodotto in opzioni affiancate con tradeoff espliciti;
- trasformare dati strutturati confusi in un editor temporaneo con azione copy/export;
- trasformare una sintesi di ricerca in un report compatto con diagrammi e riferimenti.
La lezione più profonda riguarda l’agenzia, non il markup. Quando gli agenti diventano più bravi a fare il lavoro, il collo di bottiglia si sposta sull’attenzione umana. HTML è utile perché offre a quell’attenzione una superficie migliore su cui atterrare.
Glossario tecnico
Artefatto agentico: output prodotto da un agente AI per revisione o riuso umano, come piano, report, mockup, spiegazione o tool temporaneo.
Interfaccia operativa: UI costruita per una decisione o un task specifico, spesso scartata dopo aver svolto il suo compito.
Markdown: formato testuale leggero per documenti. È facile da leggere grezzo, semplice da confrontare nei diff e supportato ovunque.
HTML: linguaggio di markup del web. Può rappresentare struttura semantica, link, media, form, tabelle e superfici interattive con CSS e JavaScript.
UI temporanea: interfaccia pensata per uso contestuale e non per manutenzione di prodotto nel lungo periodo.
Azione di export: controllo in un’interfaccia temporanea che converte le modifiche umane in un formato durevole, come JSON, Markdown, patch o prompt.
Ciclo di review: ciclo in cui un agente propone lavoro, un umano lo ispeziona o modifica, e l’agente usa quel feedback per continuare.