Utilizzare Claude Code: L'irragionevole efficacia dell'HTML

Markdown è diventato il formato di file dominante usato dagli agenti per comunicare con noi. È semplice, portabile, ha qualche capacità di testo ricco ed è facile da modificare. Claude è persino diventato sorprendentemente bravo a usare l'ASCII per creare diagrammi all'interno dei file Markdown.

Ma con l'aumento della potenza degli agenti, ho iniziato a sentire che Markdown è diventato un formato limitante. Trovo difficile leggere un file Markdown di più di cento righe. Voglio visualizzazioni più ricche, colore e diagrammi, e voglio poterli condividere facilmente.

Inoltre, sempre più spesso non modifico più questi file da solo, ma li uso come specifiche, file di riferimento, output di brainstorming, ecc. Quando faccio modifiche, di solito chiedo a Claude di modificarle, il che elimina uno dei maggiori vantaggi di Markdown.

Ho iniziato a preferire HTML come formato di output invece di Markdown, e vedo sempre più persone nel team di Claude Code fare lo stesso. Ecco perché.

(se vuoi iniziare con qualche esempio, puoi vederne molti qui: https://thariqs.github.io/html-effectiveness, ma torna indietro per leggere di più sul perché)

Perché HTML?

Densità informativa

L'HTML può trasmettere informazioni molto più ricche rispetto a Markdown. Ovviamente può gestire una semplice struttura di documento come intestazioni e formattazione, ma può anche rappresentare molti altri tipi di informazioni, come:

• Dati tabellari usando le tabelle
• Dati di design con CSS
• Illustrazioni con SVG
• Frammenti di codice con tag script
• Interazioni usando elementi HTML con JavaScript + CSS
• Flussi di lavoro usando SVG e HTML
• Dati spaziali usando posizioni assolute e canvas
• Immagini usando tag immagine

Oserei dire che non esiste quasi nessun insieme di informazioni che Claude possa leggere che non possa essere rappresentato in modo abbastanza efficiente con HTML. Questo lo rende un modo estremamente efficiente per il modello di comunicarti informazioni approfondite e per te di revisionarle.

Ho scoperto che, in assenza di questa possibilità, il modello potrebbe fare cose più inefficienti in Markdown, come diagrammi ASCII o, il mio preferito, stimare i colori con caratteri Unicode, come in questo screenshot di Claude Code.

Claude Code che cerca di mostrare i colori in Markdown

Chiarezza visiva e facilità di lettura

Man mano che Claude è in grado di svolgere lavori più complessi, scrive anche specifiche e piani sempre più grandi. In pratica, ho scoperto che tendo a non leggere più di un file Markdown di 100 righe, e sicuramente non riesco a convincere nessun altro nella mia organizzazione a leggerlo.

Ma i documenti HTML sono molto più facili da leggere: Claude può organizzare la struttura visivamente in modo ideale per navigare con schede, illustrazioni, link, ecc. Può anche essere responsive per dispositivi mobili, così puoi leggerlo in modo diverso in base al tuo dispositivo.

Facilità di condivisione

I file Markdown sono piuttosto difficili da condividere perché la maggior parte dei browser non li renderizza bene in modo nativo. Spesso devi aggiungerli come allegati a email o messaggi.

Con HTML, finché carichi il file (ad esempio su S3), puoi condividere facilmente il link. I tuoi colleghi possono aprirlo dove preferiscono e consultarlo facilmente.

La probabilità che qualcuno legga effettivamente la tua specifica, report o descrizione di PR è molto più alta se è in HTML.

Interazione bidirezionale

L'HTML ti permette di interagire con il documento, ad esempio potresti chiedergli di aggiungere slider o manopole per regolare un design o di permetterti di modificare diverse opzioni nell'algoritmo per vedere cosa succede. Puoi anche chiedergli di permetterti di copiare queste modifiche in un prompt da incollare di nuovo in Claude Code.

Leggi di più sul mio post sui playground per vedere esempi di questa interazione bidirezionale: https://x.com/trq212/status/2017024445244924382

Inserimento dati

Perché usare Claude Code per creare file HTML invece di ClaudeAI o Claude Design, per esempio? Uno dei motivi principali è tutto il contesto che Claude Code può inserire.

Ad esempio, mentre scrivevo questo articolo, ho chiesto a Claude Code di leggere la mia cartella di codice e trovare tutti i file HTML che ho generato, raggrupparli e categorizzarli, e poi creare un file HTML con tutti i diagrammi che rappresentano ogni tipo. I diagrammi che vedi in questo articolo sono il risultato diretto di questo.

Oltre al file system, Claude Code può trovare contesto aggiuntivo usando i tuoi MCP (come Slack, Linear, ecc.), il tuo browser web (con Claude in Chrome), la tua cronologia git, ecc.

È piacevole

Creare documenti HTML con Claude è semplicemente più divertente e mi fa sentire più coinvolto e investito nella creazione, e questo di per sé è sufficiente.

Come iniziare

Ho un po' paura che le persone leggano questo articolo e lo trasformino in una skill /html o qualcosa del genere. Anche se potrebbe avere un certo valore, voglio sottolineare che non devi fare molto per ottenere questo da Claude. Puoi semplicemente chiedergli di "creare un file HTML" o "creare un artefatto HTML".

Il trucco è sapere cosa vuoi che l'artefatto faccia e come potresti usarlo. Con il tempo potresti creare una skill, ma per ora ti suggerisco di iniziare da zero con i prompt per prendere confidenza con come usarlo in diversi casi.

Casi d'uso

Per rendere tutto più concreto, ho creato molti file HTML diversi per vari casi d'uso. Puoi vederli tutti qui: https://thariqs.github.io/html-effectiveness/ ma ecco una panoramica.

Specifiche, pianificazione ed esplorazione

L'HTML è una tela ricca per Claude per immergersi in un problema. Quando inizio a lavorare su un problema, invece di un semplice piano in Markdown, mi aspetto di creare una rete di file HTML. Ad esempio, potrei iniziare chiedendo a Claude Code di fare brainstorming e creare alcune esplorazioni di diverse opzioni. Poi gli chiederei di approfondirne una, magari creando mockup o frammenti di codice. Infine, quando mi sento soddisfatto, gli chiederò di scrivere un piano di implementazione. Quando sono contento del piano, creerò una nuova sessione e passerò tutti questi file per l'implementazione.

Quando verifico, chiedo anche all'agente di verifica di leggere i file e avrà un contesto molto più ampio su ciò che è necessario.

Esempi di prompt:

• Non sono sicuro di quale direzione prendere per la schermata di onboarding. Genera 6 approcci nettamente diversi — varia layout, tono e densità — e disponili in un unico file HTML in una griglia in modo da poterli confrontare fianco a fianco. Etichetta ciascuno con il compromesso che sta facendo.
• Crea un piano di implementazione approfondito in un file HTML, assicurati di includere alcuni mockup, mostra il flusso dei dati e aggiungi frammenti di codice importanti che potrei voler revisionare. Rendilo facile da leggere e digerire.

Casi d'uso:

• Esplorare altri modi per implementare qualcosa nel codice
• Esplorare più design visivi

Revisione del codice e comprensione

Il codice può essere difficile da leggere in un file Markdown. Ma con HTML possiamo renderizzare diff, annotazioni, diagrammi di flusso, moduli, ecc. Usalo per comprendere il codice scritto dall'agente, per ottenere una revisione del codice o per spiegare una PR a qualcuno che sta revisionando il tuo codice. Trovo che spesso funzioni meglio della vista diff predefinita di GitHub, e ora allego un spiegatore HTML del codice a ogni PR che faccio.

Esempio di prompt:

Aiutami a revisionare questa PR creando un artefatto HTML che la descriva. Non ho molta familiarità con la logica di streaming/backpressure, quindi concentrati su quella. Renderizza il diff effettivo con annotazioni a margine, codifica a colori i risultati per gravità e tutto ciò che potrebbe essere necessario per trasmettere bene il concetto.

Casi d'uso:

• Creare una PR
• Revisionare una PR
• Comprendere un argomento nel codice

Design e prototipi

Claude Design si basa su HTML perché HTML è incredibilmente espressivo per il design, anche se la tua superficie finale non è HTML. Claude può abbozzare un design in HTML e poi scriverlo nel linguaggio che preferisci, che sia React, Swift, ecc.

Puoi anche prototipare interazioni, come animazioni, azioni, ecc. Considera di chiedere a Claude di creare slider, manopole, ecc. per mettere a punto esattamente ciò che stai cercando.

Esempio di prompt:

Voglio prototipare un nuovo pulsante di checkout, quando viene cliccato esegue un'animazione di riproduzione e poi diventa viola rapidamente. Crea un file HTML con diversi slider e opzioni per provare diverse varianti di questa animazione, dammi un pulsante di copia per copiare i parametri che hanno funzionato bene.

Usalo per:

• Creare artefatti di design system
• Regolare componenti
• Visualizzare librerie di componenti
• Prototipare animazioni piacevoli

Report, ricerca e apprendimento

Claude Code è incredibilmente bravo a sintetizzare informazioni da più fonti di dati e convertirle in un report leggibile. Puoi chiedere a Claude di cercare nel tuo Slack, nel tuo codebase, nella cronologia git, su internet, ecc. e usarlo per generare report estremamente leggibili per te stesso, per la dirigenza, per il tuo team, ecc.

Potresti assemblarlo sotto forma di un lungo documento HTML, un spiegatore interattivo o anche una presentazione/diapositive. Chiedi a Claude di usare SVG per i diagrammi per aiutare a visualizzarlo.

Ad esempio, per i miei post sul prompt caching, ho chiesto a Claude di preparare un file di ricerca approfondito in HTML da leggere su tutte le nostre modifiche al prompt caching dopo aver letto la cronologia git.

Esempio di prompt:

Non capisco come funziona effettivamente il nostro rate limiter. Leggi il codice pertinente e produci una singola pagina HTML esplicativa: un diagramma del flusso del token bucket, i 3-4 frammenti di codice chiave annotati e una sezione "insidie" in fondo. Ottimizzala per qualcuno che la legge una volta.

Usalo per:

• Riassumere come funziona una funzionalità
• Spiegarmi un concetto
• Report settimanali di stato al tuo capo
• Report di incidenti alla tua dirigenza
• Illustrazioni SVG, diagrammi di flusso, diagrammi tecnici, ecc.

Interfacce di modifica personalizzate

A volte è difficile descrivere ciò che vuoi puramente in una casella di testo. In questo caso, chiedo a Claude di costruirmi un editor usa e getta per l'esatta cosa su cui sto lavorando. Non un prodotto, o uno strumento riutilizzabile, ma un singolo file HTML, costruito appositamente per questo singolo dato.

Il trucco è sempre finire con un'esportazione: un pulsante "copia come JSON" o "copia come prompt" che trasforma ciò che ho fatto nell'interfaccia in qualcosa che posso incollare di nuovo in Claude Code.

Esempi di prompt:

• Devo riprioritizzare questi 30 ticket di Linear. Fammi un file HTML con ogni ticket come una carta trascinabile nelle colonne Ora / Prossimo / Dopo / Tagliato. Presortali secondo la tua migliore ipotesi. Aggiungi un pulsante "copia come markdown" che esporta l'ordinamento finale con una motivazione di una riga per bucket.
• Ecco la configurazione del nostro feature flag. Costruisci un editor basato su moduli per essa, raggruppa i flag per area, mostra le dipendenze tra di loro, avvertimi se abilito un flag il cui prerequisito è disattivato. Aggiungi un pulsante "copia diff" che mi dà solo le chiavi modificate.
• Sto mettendo a punto questo system prompt. Crea un editor affiancato: prompt modificabile a sinistra con gli slot delle variabili evidenziati, tre input di esempio a destra che ri-renderizzano il template compilato in tempo reale. Aggiungi un contatore di caratteri/token e un pulsante di copia.

Usalo per:

• Riordinare, triage o raggruppare qualsiasi cosa (ticket, casi di test, feedback)
• Modificare configurazioni strutturate (feature flag, variabili d'ambiente, JSON/YAML con vincoli)
• Mettere a punto prompt, template o testi con anteprima live
• Curare dataset, approvare/rifiutare righe, etichettare esempi, esportare la selezione
• Annotare un documento, trascrizione o diff ed esportare le annotazioni
• Scegliere valori difficili da esprimere in testo: colori, curve di easing, regioni di ritaglio, pianificazioni cron, regex.

Domande frequenti

Ho parlato con molte persone di come sono passato all'HTML e ho visto alcune domande ricorrenti.

Non è meno efficiente in termini di token?

Sebbene Markdown usi spesso meno token, ho scoperto che la maggiore espressività dell'HTML e la probabilità molto più alta che io lo legga portano a un output complessivamente migliore. Con la finestra di contesto di 1MM in Opus 4.7, l'aumento dell'uso dei token non è realmente percepibile nella finestra di contesto.

Quando usi ancora Markdown?

Onestamente ho smesso di usare Markdown del tutto per quasi tutto, ma probabilmente sono all'estremo massimalista dell'HTML.

Come visualizzo il file HTML?

Di solito lo apro in un browser localmente (puoi chiedere a Claude di aprirlo), o lo carico su S3 se vuoi un link condivisibile.

Non richiede più tempo per essere generato rispetto a Markdown?

Sì, richiede più tempo! L'HTML può richiedere da 2 a 4 volte più tempo di Markdown, ma ho scoperto che i risultati ne valgono la pena.

E il controllo versione?

Questa è onestamente una delle maggiori limitazioni dell'HTML: i diff HTML sono rumorosi e difficili da revisionare rispetto a Markdown.

Come faccio a far sì che Claude corrisponda ai miei gusti / non lo renda brutto?

Il plugin di frontend design aiuta Claude a creare buoni file HTML. Ma per abbinare lo stile della tua azienda, puoi creare un singolo file HTML di design system puntando Claude al tuo codebase. Puoi poi usare quel file di design system come riferimento per altri file HTML.

Resta aggiornato

Tutto quanto sopra significa che penso che la vera ragione per cui uso HTML è che mi sento molto più coinvolto con Claude. Avevo iniziato a temere che, poiché avevo smesso di leggere i piani in profondità, avrei dovuto semplicemente lasciare che Claude facesse le sue scelte.

Ma sono felice di dire che invece mi sento più coinvolto che mai quando uso HTML. Spero che lo sia anche tu.