Ogni Blocco Ha Un Nome

// Il Post Di Ieri

L'8 maggio 2026 Simon Willison pubblica Using Claude Code: The Unreasonable Effectiveness of HTML. Riprende un post di Thariq Shihipar, che lavora sul team Claude Code dentro Anthropic. La tesi di Shihipar in due righe e' chiara: per gli artifact che gli agenti producono per gli umani, HTML e' meglio di Markdown.

I motivi che porta sono concreti, non opinabili:

• Information density. HTML ha tabelle vere, SVG, CSS, script, layout assoluti, immagini. Markdown ha header, liste, fence di codice. Per uno spec con diagrammi e mockup, MD ti costringe a ripiegare su ASCII art o, nel caso peggiore, a stimare i colori con caratteri Unicode.
• Visual clarity. Un MD da 100+ righe nessuno lo legge. Un HTML rendered con tabs, illustrazioni, link interni, sezioni, e' molto piu' digeribile. Soprattutto se vuoi che lo legga qualcun altro nel team.
• Sharing. Il browser apre l'HTML nativamente. Un MD lo apri in editor, in viewer, o lo converti. La probabilita' che il tuo PR writeup venga davvero letto e' molto piu' alta in HTML.
• Two-way interaction. Sliders, knobs, copy buttons che riportano JSON al prompt. Un Markdown e' un testo, un HTML e' una piccola UI usa-e-getta.

Onesto sui downside: HTML costa 2-4× il tempo di generazione, i diff in PR sono noisy, "in token usa di piu' ma con il context da 1M di Opus 4.7 non si nota". Spende esplicitamente piu' token in cambio di artifact che effettivamente leggi.

Se quello che ti serve e' un piano leggibile dal team con diagrammi e mockup veri, ha ragione lui — HTML e' meglio.

// La Controspinta

Il giorno prima, lunedi' 5 maggio 2026, esce mdream di Harlan Zw, JavaScript library da 6 KB gzipped che converte HTML in Markdown. Filosofia esplicita nella documentazione: every token counts. Output con il 50% di token in meno rispetto a Turndown, 3× piu' veloce, 1.8 MB di HTML processato in 60 ms. La promessa: pipeline RAG piu' efficienti, retrieval piu' denso, context window meno congestionato.

Il 5 marzo Cloudflare aveva lanciato Markdown for Agents. Funzionamento: i crawler AI mandano un header Accept: text/markdown, gli edge server di Cloudflare convertono al volo, restituiscono Markdown con un header aggiuntivo x-markdown-tokens. Esempio citato nell'annuncio: un blog post da 16.180 token in HTML diventa 3.150 token in Markdown. Risparmio dell'80%.

John Mueller di Google ha definito Markdown for Agents "a stupid idea", perche' rimuove contesto e struttura. Cloudflare l'ha lasciato passare. Questa e' la posizione mainstream del mercato adesso: per fare ingestion di contenuti web verso un LLM, il Markdown e' una vittoria di defaults a tre cifre percentuali in costo.

Microsoft il 17 aprile ha rilasciato MarkItDown, converter universale per file Office, PDF, immagini, audio → Markdown. Stessa filosofia: per dare contesto agli LLM, Markdown vince.

L'argomento profondo della controspinta non e' solo il conteggio token. E' che gli LLM sono pretrained su miliardi di token di prosa e codice, contro una frazione di HTML soup. Quando produci HTML come input per il modello paghi due volte: piu' token e meno allineamento con la distribuzione di training. La densita' semantica del Markdown si paga in espressivita', si guadagna in comprensione.

// Il Trucco

Shihipar parla di output: cosa l'agente produce per te.

Cloudflare e mdream parlano di input: cosa tu fai vedere all'agente.

Sono fasi diverse del workflow, con vincoli opposti. Shihipar ha 1M token di context window, gli costa quasi nulla aggiungere CSS e SVG, in cambio gli torna un PDF leggibile. Cloudflare deve farti pagare 16.180 token invece di 3.150 per ogni pagina che dai in pasto a un crawler che fa retrieval batch su milioni di URL. La vittoria del primo non e' la sconfitta del secondo, e viceversa.

Il dibattito di questa settimana sembra "Markdown contro HTML, chi vince per gli LLM". E' una semplificazione che salta in aria appena guardi quale fase del workflow stanno ottimizzando. Tre fasi, tre vincitori diversi.

Il punto del pezzo e' la terza casella. La fase 1 e' coperta dal mainstream Markdown. La fase 2 e' coperta dalla nicchia HTML che cresce questa settimana. La fase 3 nessuno la sta misurando, ed e' quella che fra dodici mesi vi mordera'.

// Timeline Della Settimana

Quattro voci sul polo input, una sul polo output, zero sul polo editing. Il debate ha un punto cieco. Se non ti accorgi che le tre fasi sono distinte, leggi il post di Shihipar e pensi "ma allora Cloudflare ha sbagliato?". Non ha sbagliato. Stanno parlando di cose diverse.

// La Domanda Mancante

Tutta la letteratura della polemica corrente assume un workflow single-shot. L'utente scrive un prompt, l'LLM legge contesto e produce output, fine. Per quel mestiere Markdown vince in input, HTML inizia a vincere in output ricco, e la decisione e' chiara abbastanza.

Esiste un secondo mestiere che non e' nei benchmark, e non e' ancora un commodity production pattern, ma sta arrivando: piu' agenti diversi modificano lo stesso documento nel tempo. Knowledge base interne aggiornate da agenti per mesi, runbook operativi mantenuti da SRE bot, spec di RFC redatte da swarm di agenti, checklist d'incidente con audit trail. Non e' fantascienza, e' lo scenario operativo di chi sta deployando agenti in produzione adesso.

Cambia tutto. Se piu' agenti devono editare lo stesso documento, ti serve:

Markdown e' un disastro su quasi tutte le righe tranne due. HTML e JSON vanno bene strutturalmente ma costano caro in token e leggibilita'. Il quadrante mancante e' "abbastanza compatto da non bruciare context window, abbastanza strutturato da permettere edit chirurgici, abbastanza umano da leggerlo in cat". Nessuno dei tre formati popolari sta in quel quadrante.

La domanda diventa: qual e' il formato giusto per un documento di lunga vita editato da piu' agenti?

// Tre Regole, Un Sigillo

Per la mia testa, la risposta alla casella vuota e' un formato che eredita il line-oriented di Markdown e ci aggiunge tre cose: ID di blocco stabili, sintassi LL(1) deterministica, operazioni di edit come dati JSON. Il prototipo si chiama AGD (Agent Document) ed e' su github.com/Pinperepette/agd. Rust, MIT, v0.1.0.

Ogni blocco AGD inizia con @<tag> a colonna 0. E' l'intera storia sintattica.

Tre regole, niente di piu':

La grammatica completa e' frozen in grammar/agd.ebnf — 50 righe di EBNF. Nessun backtracking, nessun lookahead oltre la riga corrente. Il parser e' single-pass, LL(1). Il senso di tutto questo e' che lo stesso file dato a due implementazioni diverse di AGD deve produrre lo stesso AST. E' la proprieta' che HTML ha (DOM standard) e Markdown non ha (CommonMark vs GFM vs MDX disagree su edge cases).

// Quello Che Promettevo, Quello Che E' Uscito

Quando ho buttato giu' il design, prima di scrivere una riga di Rust, avevo fatto stime token a vista. Erano sbagliate. Lo dico subito perche' il pezzo non funziona se mento.

L'errore peggiore sta sulla riga uno. Avevo in testa che @h1 e # fossero entrambi 2 token. Falso: @h1 tokenizza come 3 token con BPE cl100k_base, mentre # e' 1 token. Su 1000 blocchi sono gia' 2000 token di prefisso. Misurato su corpora di 100k blocchi, AGD costa il 20% in piu' di Markdown a tutte le scale, con una banda 18-22% molto stretta.

Vince invece contro HTML del 16-19%, contro JSON del 56-59%. Niente di sensazionale rispetto a XML. Il +20% rispetto a Markdown e' il prezzo onesto degli ID espliciti e dei prefissi @<tag>: lo paghi sempre, non c'e' un trucchetto per recuperarlo a livello sintattico.

// La Scoperta Vera

Il valore di AGD e' indicizzare i blocchi per ID. Il primo design ingenuo era Document::find(&id) con linear scan: O(n). Per 100 blocchi va bene. Per 100k inizia a fare male. Quanto male? Misurato:

Senza l'index, ogni edit operation costa 283 µs solo per trovare il blocco target su un documento da 100k entries. Con l'index, 108 ns. Differenza di tre ordini di grandezza.

La conseguenza architetturale e' importante e l'avevo sottovalutata: chiunque usi AGD seriamente deve costruirsi un indice. Non e' un'ottimizzazione, e' la differenza fra "usabile" e "inutilizzabile". Il codice client ideale e' questo:

Il pattern "parse-once, edit-many" gira a 500k op/sec via library API. Lo stesso flow via CLI subprocess (un agd edit per operazione) gira a 76 op/sec. Differenza: 6500×. Implicazione: AGD ha senso solo se mantieni il documento parseato in memoria in un servizio, non se invochi la CLI in loop.

// Tre Agenti, Stesso Documento, Tre Formati

La teoria della casella vuota dice "AGD vince per editing multi-agente". Da soli quei numeri non valgono niente. Ho costruito il lab che dimostra il punto.

Stesso scenario operativo — un piano di risposta a un incidente di security — reso in tre formati: Markdown, HTML, AGD. Tre processi agent indipendenti (analyst, responder, auditor) emettono 12 edit operation a Redis Streams in parallelo. Tre demoni, uno per formato, consumano FIFO con XREADGROUP, applicano l'op alla loro versione del documento (chiave Redis Hash), fanno XACK. Lo stream e' l'audit trail nativo; il replay da XRANGE 0 + ricostruisce lo stato.

Il workload contiene una operazione cattiva alla riga 4: l'analyst rinomina la sezione "Findings" in "Initial findings". Cinque secondi dopo, l'auditor aggiunge un finding tardivo targettando il logical id findings. Il punto: il rename ha cambiato il nome ma non l'id. Markdown non ha un meccanismo di stable id, HTML e AGD si'.

Risultato di una run reale (12 ops emesse in ~600 ms wallclock, demoni concorrenti):

Tre osservazioni che vale la pena fare prima di andare oltre.

Markdown perde una op. Il regex per ## Findings non trova piu' la sezione dopo il rename. L'op dell'auditor finisce nello stream ma il demone la registra come target_not_found. Lo stream e' onesto, lo stato finale e' incompleto. HTML e AGD applicano tutte e 12 — gli id resistono alla rinominazione del titolo.

Replay funziona ovunque. Lo stream e' authoritative: rieseguendo le ops dall'offset 0 su uno stato iniziale fresco ottengo byte-per-byte lo stesso stato live. Vale per tutti e tre i formati. Vuol dire che l'audit log Redis e' l'unica cosa che devi conservare: lo stato live e' una funzione del log, non un database separato. Per uno scenario di compliance — "fammi vedere come era il documento alle 14:31:07 di tre settimane fa" — basta XREAD fino a quel timestamp.

Sulla latenza vale la pena soffermarsi. AGD applica un'op in 2,3 microsecondi mediana — 500× piu' veloce di HTML (BeautifulSoup), 50× piu' veloce di Markdown (regex puro). Non e' magia: il demone agdd e' scritto in Rust, parsea il documento una sola volta all'avvio, costruisce un DocumentIndex in memoria, applica ogni op come mutazione strutturale tipata via la library API. Niente subprocess, niente fork+exec, niente reparse tra ops. Il prezzo e' aver scritto il demone in Rust invece che Python: ~150 righe di codice in src/bin/agdd.rs nel repo agd.

HTML e MD nel lab girano in Python con BeautifulSoup e regex. Una versione Rust di entrambi (lxml-rs, regex crate) probabilmente farebbe un po' meglio, ma la differenza strutturale resta: HTML deve riserializzare l'intero DOM ad ogni mutazione, AGD muta in-place strutture tipate.

Numeri di base sul motore AGD, dal repo agd (riproducibili con cargo run --release --bin agd-bench): parse 60 MB/s, serialize 830 MB/s, find by ID a 100k blocchi via DocumentIndex in 108 ns. Vedi benches/BENCHMARKS.md.

Il codice del lab gira in cinque secondi su qualunque macchina con docker + python3 + cargo installati: scripts/ogni-blocco-ha-un-nome/v2_redis/run_lab.sh. Output completo: output/report.md, output/daemon-{md,html,agd}.log con audit trail tab-separated, output/final.{md,html,agd} con i tre documenti finali. Tutto riproducibile, tutto sul repo del blog.

// Riprodurre I Benchmark

Tutto quello che hai letto e' verificabile con cinque comandi. Niente nascosto, niente hand-waved. Repository: github.com/Pinperepette/agd.

Il punto 4 e' quello che ti convince o ti smonta. Genera corpora sintetici deterministici (stesso seed, stesso byte output su qualunque macchina), parsea, serializza, edita, conta token, confronta con pulldown-cmark. Output finale: benches/BENCHMARKS.md, lo stesso file da cui ho preso tutti i numeri di questo post.

Tre scoperte uniche del lab che vale la pena fissare:

// Vale La Pena Spendere Piu' Token?

Il "+20% di token" l'abbiamo gia' detto sei volte. Misurato di nuovo, su corpora controllati di 100, 1.000 e 10.000 blocchi, e' confermato: AGD costa il +18-22% in piu' di Markdown quando carichi l'intero documento. Banda stretta, scala ortogonale, niente sorprese.

Quello che il post ha taciuto fino a qui e' che il +20% e' solo meta' della storia. L'altra meta' e' che AGD abilita una forma di richiesta che Markdown non puo' fare: caricare il Table of Contents (lista degli ID), scegliere il blocco, caricare solo quello. Un agente in stile Claude Code che cerca informazioni in un documento di 10.000 blocchi non deve leggerlo tutto. Pesca l'ID giusto e ne legge uno.

Misurato:

Lo speedup cresce con la scala. A 10.000 blocchi, una richiesta mirata su AGD costa 1/15 di un caricamento completo Markdown. A 100.000 blocchi diventa ~1/20. Il crossover — il punto in cui AGD ti ripaga il +20% del primo caricamento — e' dopo la seconda lookup mirata sullo stesso documento. In quasi tutti i workflow agentici reali quel breakeven arriva nei primi minuti.

I numeri sono nel benchmark benches/RETRIEVAL.md del repo agd, riproducibili con cargo run --release --bench retrieval.

Le due cifre stanno insieme. Il +20% e' il costo che paghi quando carichi tutto, il fattore 14× e' lo sconto che ottieni quando leggi solo quello che ti serve. Quale dei due conta di piu' dipende dal pattern di accesso del tuo agente, non dal formato in se'.

Conta i casi uno per uno con questa lente.

Conta i casi: 3 dove altri formati vincono, 1 pareggio, 4 dove AGD vince. La proporzione e' cambiata rispetto a quello che pensavo all'inizio — il selective retrieval e' una vittoria che il post non aveva contato. Pragmatica: se il tuo agente carica sempre tutto, usa Markdown. Se fa lookup mirati, AGD si ripaga dopo due query. Il salto di costo non e' lineare, e' di natura: passi dal regime "leggi tutto, paga proporzionale" al regime "leggi solo l'indice, paga la lista".

Nota di realta': se vuoi il 90% del valore di AGD senza buttarti su un formato nuovo, prova Markdown + kramdown anchors:

Hai gli ID, resti dentro l'ecosistema Markdown, GitHub li renderizza, Pandoc li capisce. Perdi la forma canonica rigorosa e il parser LL(1) puro, ma probabilmente non li userai mai. AGD ha senso quando perdere quei due e' un costo reale, non teorico — e oggi quei costi pochi li sentono.

// Quello Che Mi Resta In Mano

La polemica MD vs HTML di questa settimana e' viva e fondata, ma confonde tre fasi diverse del workflow degli agenti. C'e' la fase di ingestion (Markdown vince, e Cloudflare la serve nativa), la fase di output ricco per umani (HTML vince, e Anthropic la spinge), e una terza fase — l'editing collaborativo di documenti che durano nel tempo — per cui adesso non c'e' un formato dedicato. AGD e' un esperimento che prova a riempire quel buco.

Funziona, nei limiti che si pone. 89 test su 10 suite, proptest robusto, un lab Redis multi-agente che gira in cinque secondi, benchmark riproducibili sul repo. Costa il 20% di token in piu' di Markdown se carichi tutto il documento e ne risparmia un fattore 14 se cerchi un blocco specifico. Pulldown-cmark resta 2-3 volte piu' veloce nel parsing su file grandi, ma quel campionato AGD non lo sta giocando: scrivendo il demone in Rust e tenendo il documento in memoria la latenza per op va a 2,3 microsecondi, e a quel punto la velocita' assoluta del parser conta poco perche' parsi una volta sola.

Quello che mi porto a casa pero' non sono i numeri. E' una mappa del design space che a inizio settimana non avevo. Il +20% di token cambia segno appena l'agente smette di leggere tutto e inizia a chiedere blocchi specifici, e questo non lo si capisce finche' non si misura. Il determinismo del parser e' una proprieta' che non sapevo di volere finche' non ho visto un regex Markdown rompersi su un rename in produzione. Capire dove conviene combattere e dove no, prima di adottare qualcosa, e' tutto il valore di questa settimana.

Se ti capita davvero il problema dell'editing multi-agente, AGD e' un punto di partenza riproducibile da cui rubare idee, fare fork, oppure semplicemente buttare via tutto e tornare a Markdown con kramdown anchors sapendo cosa stai perdendo. Il valore del prototipo per me e' stato quello: rendere visibile un trade-off che senza misurarlo restava una sensazione.