Il mio nuovo tema WordPress

Questo blog è finalmente tornato a essere la mia casa, dove da qualche settimana ho ripreso a scrivere le cose che faccio e provo.

Il vecchio tema WordPress non mi rappresentava più e, visto che ho scritto un articolo su come creare un sito WordPress con l’AI, dovevo provare sulla mia pelle se quello che avevo scritto avrebbe retto sia nella grafica sia nella gestione dei contenuti.

Sono partito dai requisiti: un tema nuovo con grafica elegante e minimale, veloce, accessibile e con blocchi Gutenberg su misura.
Prima ci avrei messo settimane (forse mesi), invece adesso è online dopo pochi giorni da quando ho iniziato a validare le bozze.

In pratica ho fatto quello che consiglio ai clienti: ho deciso cosa e come lo volevo, con un prototipo approvato e delle regole di valutazione, e poi ho fatto sviluppare il resto a Claude Code con un processo multiagente. Un agente sviluppa, un altro agente valida senza aver scritto una riga, e quando è tutto pronto decido se è davvero arrivato il momento di andare online.

In questo articolo ti racconto le scelte di progetto prese per questo tema WordPress prima del codice, il prompt che ho dato a Claude Code (commentato, con una versione generica da scaricare) e cosa ho ancora modificato dopo un giorno di rodaggio.

Perché un tema WordPress nuovo

Il vecchio tema WordPress aveva già qualche anno e, nonostante gli ottimi punteggi nei Core Web Vitals, non era più il vestito giusto per questo blog.

Il tema di prima era arrivato alla versione 1.6: un child di Blocksy con qualche regola CSS, un paio di filtri e molte scelte fatte dal Customizer negli anni. Funzionava, ma ogni pagina nuova finiva per somigliare a un articolo, la home era un lungo paragrafo di presentazione e su telefono era quasi uno schifo.

Non volevo cambiare piattaforma né tema padre: Blocksy resta la mia prima scelta per WordPress. Il nuovo tema WordPress è quindi di nuovo un child theme di Blocksy, che lascia al padre header, footer e opzioni. Con i Content Blocks di Blocksy Pro avrei potuto disegnare anche l’articolo e la 404 dall’editor, ma quei template vivono nel database. Ho preferito metterli nel codice del child, insieme ai token di design, ai template di home, pagine e allegati e a una serie di blocchi dinamici: così stanno in un repository, passano dai controlli automatici e un agente li può sviluppare e verificare.

Child di Blocksy, Gutenberg dentro

Tre scelte di progetto vengono prima del codice: restare child di Blocksy, mettere Gutenberg dentro un tema classico e, dove necessario, fare un blocco su misura.

Prima di parlare di PHP e di phpcs ci sono alcune decisioni che ho preso e che hanno stabilito com’è fatto il tema WordPress. La prima è restare un child theme di Blocksy. Blocksy è il tema padre che uso da anni: ha un ottimo Header Builder, tantissime opzioni nel Customizer, la tipografia, le sidebar, la barra di lettura. Un child eredita tutto questo e ci aggiunge il proprio codice, quindi nel nuovo tema per molte cose ho solo riconfigurato il Customizer, come si faceva prima.

La seconda riguarda Gutenberg. Il nuovo tema non è un block theme, cioè un tema fatto di template HTML e di theme.json: i template sono file PHP (front-page.php, page.php, 404.php), perché sopra Blocksy è la strada più semplice. Dentro quei template, però, c’è solo Gutenberg: ogni sezione è un blocco, i template li chiamano con do_blocks() e render_block() come una volta chiamavano gli shortcode, e la home parte da un pattern del tema. È il compromesso che tiene insieme il Customizer di Blocksy e un’interfaccia che si modifica dall’editor.

La terza è la più grossa: dove necessario le sezioni del tema WordPress diventano blocchi dinamici su misura con regole e comportamenti personalizzati.

Ognuno ha un block.json con apiVersion 3, un render.php e i testi si cambiano nell’editor o nelle Impostazioni.

Dal prototipo al piano

Prima di iniziare lo sviluppo del nuovo tema WordPress ho fatto preparare un prototipo con undici tavole e un piano di sviluppo suddiviso in fasi.

Il prototipo l’ho costruito insieme a Claud.ia come una serie di tavole HTML dentro un artefatto, facendo diverse prove anche con le skill di design di cui ho già parlato: home desktop e mobile, articolo, pagina di servizio, allegato e 404.
Per la pagina di dettaglio articolo sono arrivato a fare sei prove diverse…

Dal prototipo è nato un brief di sviluppo: obiettivo, vincoli non negoziabili, elenco dei blocchi, token di colore e font, regole di codice, processo per fasi. Claude Code ha letto tutto e ha proposto un piano, che ho approvato dopo aver risposto alle sue domande. Il brief lo commento più avanti, pezzo per pezzo.

Il piano divideva il lavoro in fasi, ognuna con un branch e una pull request: ambiente e controlli, pelle (colori, font, header e footer), articolo, home, pagine e archivi, QA e performance.

Quando siamo arrivati alla fine del piano iniziale, la prova su strada ha richiesto altri ritocchi per un totale di diciotto pull request su GitHub.

Anche la pagina d’errore è passata dal prototipo: la 404 è un terminale con il numero in ASCII art.

Il prompt, parte per parte

Il brief che ho dato a Claude Code è lungo, ma poche frasi decidono com’è fatto il tema WordPress: le riporto una per una, con il mio commento, e in fondo c’è una versione generica da riusare.

Il prompt è un file Markdown di circa diciottomila caratteri: un obiettivo, una tabella con dove stanno le cose, dieci vincoli non negoziabili, l’ambiente di sviluppo, il processo per fasi con lo sviluppatore e il validatore, le decisioni già prese e quelle aperte, la lista per il go-live. Qui sotto trovi le citazioni testuali che contano di più, ciascuna con quello che ho voluto ottenere.

Lavora in autonomia fino alla fine. Prima di iniziare puoi farmi domande o propormi miglioramenti sulle decisioni aperte (sezione «Decisioni aperte»): fallo in un solo messaggio, poi parti e non fermarti più se non per questioni che non puoi decidere da solo o per azioni distruttive.

Questa frase fa metà del lavoro. Un agente che chiede conferma a ogni passo non fa risparmiare niente, e uno che parte senza domande rischia di costruire la cosa sbagliata. Con le domande tutte in un messaggio, all’inizio, e poi via da solo, ci si ferma soltanto per ciò che non si può decidere o per le azioni che non si disfano.

1. **Tema nuovo, child theme di Blocksy**, cartella e text domain `miziomon_2026`. Non si modifica il tema padre e non si evolve il vecchio child `miziomon` (…). Non si modifica nessun plugin.
2. **A Blocksy restano header, footer e tutte le opzioni del Customizer** (palette, tipografia, Header Builder, Footer Builder, opzioni del single, sidebar, barra di lettura, Content Blocks). Il tema aggancia e sovrascrive solo dove Blocksy non arriva. Niente `!important` contro Blocksy: dove c'è un'opzione si usa l'opzione.

Sono le due righe che fissano la prima scelta di progetto. Il vecchio child resta da studiare e non da evolvere: era cresciuto per aggiunte, e portarlo con me avrebbe portato anche i suoi difetti. Il divieto di !important è un modo per costringere l’agente a capire come funziona il padre invece di vincere a colpi di CSS, e a me evita di ritrovarmi fra un anno un tema che combatte contro il suo genitore. Fra le opzioni lasciate a Blocksy ci sono anche i Content Blocks: restano a disposizione, ma i template del tema stanno nel codice del child.

3. **Componenti Gutenberg su misura**: ogni sezione con markup preciso è un blocco dinamico con `block.json` (`apiVersion` 3) e `render.php`, build con `@wordpress/scripts`, registrazione da `blocks-manifest.php`. (…) Ogni blocco deve essere anche inseribile a mano dall'editor.

È il punto che ha dato forma al tema WordPress. «Inseribile a mano dall’editor» vuol dire che nessun blocco vive solo dentro un template: domani posso metterlo in una pagina nuova senza chiedere niente a nessuno. Più avanti, nella sezione sui blocchi, si vede come appaiono nell’editor.

4. **Pagine di template PHP nel child**: (…) I template chiamano i blocchi con `do_blocks()` o `render_block()`, come una volta con `do_shortcode()`. I testi che vorrò cambiare senza toccare il PHP non stanno negli attributi hard-coded ma in una pagina «Home» o in opzioni del sito lette dal template.

Il confronto con gli shortcode dice all’agente quale modello mentale usare: il template PHP è un guscio che chiama blocchi, non un posto dove scrivere HTML. E la seconda frase è la regola che ha fatto nascere le Impostazioni del sito: eventi e «Da leggere dopo» si cambiano da un modulo, senza aprire il codice.

In questo file ho definito anche la parte tecnica: WordPress Coding Standards con phpcs, PHPStan al livello 6, escaping e sanitizzazione in ogni render.php, query pensate per non lavorare a vuoto, traduzioni con il text domain. Sono regole che ogni sviluppatore WordPress conosce, e scriverle serve a non doverle ripetere; la differenza la fanno le tre scelte di progetto qui sopra.

3. **Validazione da un agente validatore**: lancia un sub-agente nuovo (non un fork, così non eredita le tue convinzioni) a cui passi la PR, i criteri di accettazione, il percorso dell'artboard di riferimento e questo elenco di vincoli. (…)

Grazie al dettaglio «non un fork» parte un agente nuovo, che legge il diff e le pagine come le leggerebbe un collega che arriva il lunedì.

## Decisioni già prese (non rimetterle in discussione)
(…)
## Decisioni aperte (proponi la tua scelta nel messaggio iniziale, poi procedi)

Due elenchi opposti: le decisioni già prese non si riaprono, quelle aperte arrivano con una proposta dell’agente, e le sette del brief le ho chiuse dopo aver risposto alle sue domande. Non tutto quello che il prompt chiede è sopravvissuto: la CI con GitHub Actions, per esempio, l’ho tolta quando ho approvato il piano.

10. **Produzione intoccabile** durante lo sviluppo: sul server solo letture (dump del DB, download di immagini, `wp option get`). Niente upload, niente attivazioni, niente cache svuotate finché non do il via.
(…)
Questa lista la eseguiremo insieme dopo il mio test in locale: tu la prepari e la provi in wp-env, ma **in produzione non tocchi nulla senza il mio via esplicito**.

Sono le due righe più rassicuranti: l’agente può leggere tutto dal server e non può cambiare niente. Il documento di go-live nasce durante lo sviluppo, con i comandi eseguibili e il backup come primo passo, e si prova in locale prima di toccare il sito vero.

Chi scrive il codice non lo approva

Per ogni fase del tema WordPress uno sviluppatore scrive e un validatore nuovo, che non ha visto nulla, decide se si può fare il merge.

Il cuore del metodo è una regola semplice: chi scrive il codice non è chi lo approva. All’inizio di ogni fase del tema WordPress i criteri di accettazione finiscono in un file, prima di qualunque riga di codice. Poi lo sviluppatore, un sub-agente con Sonnet, lavora sul branch della fase e apre la pull request con screenshot a 1440 e a 390 pixel accanto alla tavola del prototipo.

A quel punto entra il validatore: un sub-agente Opus creato da zero che riceve la pull request, i criteri, il prototipo e i vincoli del brief; legge il diff, lancia i controlli, apre le pagine nel sito locale e risponde OK oppure KO con un elenco puntuale: file, riga, cosa non va, cosa si aspetta. Con un KO si corregge e si rivalida, e il merge arriva solo dopo l’OK.

Per non farsi mancare nulla ho chiesto una validazione finale a Fable su resa grafica, codice e performance: il verdetto è stato «OK con riserve», e il giro di correzioni l’ha pianificato Opus e sviluppato Sonnet. Il piano prevedeva anche il freno del loop: se lo stesso punto rimbalzava per più di cinque giri, finiva in un file dei disaccordi e si andava avanti. Alla consegna quel file non aveva punti aperti.

Questo modo di lavorare ha un nome: loop engineering. Nell’articolo sull’harness degli agenti AI l’avevo descritto riprendendo Addy Osmani: invece di dialogare con l’agente turno per turno, progetti il sistema che parte da un innesco, genera il prompt successivo e si ferma su una condizione che una macchina può verificare. Qui i loop sono due, uno dentro l’altro: quello esterno percorre le fasi del piano, quello interno gira tra sviluppatore e validatore finché non arriva l’OK.

L’innesco è uno solo, il «lavora in autonomia fino alla fine» del brief. Il prompt successivo non lo scrivo io: è l’elenco del KO, con file, riga e correzione attesa, che torna allo sviluppatore. La condizione di arresto sono i criteri scritti prima e i controlli automatici, che racconto qui sotto.

I controlli prima di ogni merge

Un solo comando, npm run check, passa il tema WordPress attraverso standard di codice, analisi statica, test e Lighthouse, tutto in locale.

Il brief chiedeva una CI con GitHub Actions; quando ho approvato il piano ho deciso di farne a meno. Tutti i controlli girano quindi in locale, sul sito di test con i dati di prova, con un solo comando, npm run check, e l’esito va scritto nella descrizione della pull request. Dentro ci sono:

• phpcs con i WordPress Coding Standards e il controllo di compatibilità con PHP 8.3;
• PHPStan al livello 6;
• lint di JavaScript e CSS e build dei blocchi;
• un controllo dei contrasti sulle coppie di colori del tema;
• PHPUnit, arrivato a 218 test con l’ultima versione;
• Playwright con i test end-to-end su desktop e telefono, che comprendono axe per l’accessibilità;
• Lighthouse in modalità mobile su home, articolo e pagina di servizio, con la mediana di cinque corse, più la 404 con soglie sue.

Per i test con Lighthouse una nota: nell’ambiente di test locale la Performance oscilla a seconda di quanto è carico il computer, quindi in questo caso la Performance è solo un avviso, mentre restano errori le altre tre categorie e i Core Web Vitals (CLS, LCP e TBT).

Diciotto blocchi su misura

Ogni sezione con un markup preciso è un blocco dinamico: diciotto in tutto.

Nel tema WordPress non volevo HTML scritto a mano nelle pagine: ogni sezione è un blocco dinamico con block.json e render.php, inseribile anche dall’editor. I template PHP li chiamano come una volta si chiamavano gli shortcode, e i testi che voglio cambiare stanno negli attributi dei blocchi della pagina, non nel codice.

Nell’editor ogni blocco ha una descrizione che dice cosa contiene e dove si usa, e i testi si modificano lì. Il blocco Servizi, per esempio, raccoglie titolo, introduzione, la griglia delle card «Servizio» e a lato il box del partner tecnico; il Libro compare in quattro varianti (sezione della home, striscia nel footer, card in sidebar e nel menu mobile) ed è sempre lo stesso blocco, che non si stampa sulla pagina della guida a Claude Code a cui rimanda.

Un dettaglio che si vede poco: l’indice in sidebar è un blocco che usa le stesse ancore dell’indice di Rank Math, così i link già condivisi continuano a funzionare. Le FAQ restano il blocco di Rank Math, con lo schema invariato: il tema aggiunge solo CSS e un piccolo script per aprirle con il bottone giusto. I commenti stanno in una finestra dialog nativa, che si chiude con Esc e restituisce il focus, e senza JavaScript restano in pagina.

La riga di stato in home, quella con il pallino verde, dice da quanto è uscito l’ultimo articolo e ne mostra il titolo: una sola query, in cache, che si invalida da sola quando pubblico.

Performance vuol dire PHP pulito

Per me performance vuol dire anche il lavoro inutile che il PHP del tema WordPress evita, oltre al punteggio di Lighthouse.

Su questo punto il brief era il più insistente, perché è quello che controllo per primo quando metto le mani su un sito. Nella fase di QA Claude Code ha riletto tutto il PHP del tema WordPress e ha contato le query di ogni template con un piccolo plugin di misura, usato solo in locale. Il resto è di Blocksy, Rank Math e del core. I blocchi del tema stanno sotto i 10 millisecondi su richieste da circa 120 millisecondi.

La cache è volutamente semplice: il tema non usa transient, salva solo liste di ID nella cache oggetti e mette nella chiave l’ultima modifica degli articoli, così pubblicare o modificare un contenuto la invalida da sola, senza hook di pulizia. Le copertine di archivi e ricerca si caricano in blocco: sulla categoria WordPress le query sono scese da 113 a 81.

Sul frontend le correzioni sono state poche e mirate. Uno script dell’indice calcolava la voce attiva all’avvio e forzava un layout della pagina intera: spostando il calcolo dopo il caricamento il TBT dell’articolo è sceso da 280-360 a 120-170 millisecondi. Il menu mobile ridisegnato, invece, non aggiunge né query né JavaScript: è costruito con le opzioni di Blocksy e un CSS minimo.

Le decisioni che restano mie

Gli agenti hanno scritto quasi tutto il codice del tema WordPress; le scelte su cosa fare, cosa rimandare e cosa non toccare le ho fatte io.

Alla consegna della prima versione completa ho provato il sito locale e Claude Code mi ha messo davanti un elenco di 24 decisioni da prendere.
Alcune erano di gusto, altre decisamente di sostanza.

Ci sono poi le regole, alcune date prima ancora di vedere il codice, come la produzione in sola lettura fino al mio via. Sono tutte scelte che richiedono di conoscere il sito e che un agente non trova nel repository. Nel loop il mio posto è ai bordi: approvo il piano prima che parta, rispondo alle decisioni quando si ferma e do il via al go-live.

Usando il sito e facendo un po’ di rodaggio sono arrivate altre otto versioni del tema WordPress, dalla 1.0.5 alla 1.0.12, ciascuna con la sua fase e con ritocchi nati anche da qualche consiglio esterno.

Il go-live, con la rete di sicurezza

Il tema WordPress è online: la procedura scritta e provata in locale ha girato sul sito vero in meno di un minuto, con il backup fatto prima.

Mettere online il nuovo tema WordPress voleva dire più che caricare una cartella e attivarla: copiare le impostazioni del Customizer dal vecchio child al nuovo, creare la nuova home, attivare il tema, scaricare i font in locale, configurare sidebar e menu, svuotare le cache. La procedura è un documento passo per passo, con backup del database, del tema e delle opzioni prima di toccare qualunque cosa, la verifica dopo e il rollback. Prima l’avevo vista girare in locale: uno script ricostruisce da zero il sito da un dump fresco ed esegue la stessa sequenza, fermandosi al primo errore.

Sul sito vero, dopo il mio via, la sequenza dei passi ha richiesto 57 secondi, senza errori. Poi una verifica automatica: 19 controlli su 19, con il file .htaccess invariato e titolo, description, canonical, immagine social, robots e tipi di schema della home identici a prima. Il giorno stesso ho misurato anche Lighthouse mobile sul sito vero: la home fa 97 in Performance e 100 nel resto, un articolo lungo come la guida a Claude Code 90-91 con 100 nelle altre tre categorie.

Il mio blog ha un vestito nuovo

La prova sulla mia pelle è passata: il blog è di nuovo casa mia, e il tema WordPress si gestisce dall’editor senza aprire il codice.

Ero partito per capire se il metodo che racconto nell’articolo su come creare un sito WordPress reggeva anche a casa mia, con i miei contenuti e le mie abitudini, e ha retto, sia nella grafica sia nella gestione dei contenuti. Il tema WordPress continuerà a cambiare con l’uso, una piccola fase alla volta, ma il vestito nuovo c’è e adesso posso tornare a fare la cosa per cui l’ho cucito: scrivere.

Se vuoi provare un metodo simile, parti dalla guida pratica a Claude Code, che è gratuita e nella versione 6.2 spiega anche subagent e code review. Se invece hai un tema WordPress da rifare e vuoi capire se un processo così fa al caso tuo, possiamo parlarne in una call conoscitiva: trenta minuti, senza impegno. Se sei un’agenzia, trovi come collaboro nell’articolo sul partner tecnico per agenzie.

E tu come lo trovi, il blog nuovo?
Dimmelo nei commenti, soprattutto se scopri qualcosa che non va…

Domande frequenti sul nuovo tema