# Prompt per sviluppare un tema WordPress child con Claude Code **Come usarlo.** Compila la tabella «Dati del progetto», adatta le decisioni già prese e quelle aperte, poi incolla tutto in una nuova sessione di Claude Code avviata dalla cartella del progetto. Il metodo è sempre lo stesso: un piano a fasi, uno sviluppatore e un validatore separati, controlli automatici che decidono quando una fase è finita e la produzione intoccabile fino al tuo via. --- ## Dati del progetto | Campo | Valore | |---|---| | Sito | [nome e URL del sito] | | Tema padre | [per esempio Blocksy, con la versione; indica se hai l'estensione Pro] | | Nome e text domain del nuovo tema | [per esempio `miotema_2026`] | | Prefisso dei blocchi | [per esempio `miotema/`] | | Tema attuale | [nome del tema in uso: da studiare, non da evolvere] | | Riferimento grafico approvato | [dove si trova: immagini, file di design, guida di stile] | | Token di design | [font per titoli, testo ed etichette; colori per testo, testo secondario, sfondi, linee, accento, sezioni scure] | | Copia locale del sito | [percorso dei file del sito, uploads compresi] | | Dump del database | [percorso e data] | | Server di produzione | [accesso SSH con WP-CLI, solo lettura; le credenziali restano in un file locale fuori dal repository] | | Versioni di produzione | [PHP e WordPress] | | Repository | [utente o organizzazione GitHub e nome proposto] | | Lingua di commenti e documentazione | [italiano] | ## Obiettivo Costruisci il nuovo tema di [nome del sito] a partire dal riferimento grafico approvato. Il risultato atteso è un **tema WordPress nuovo, child theme di [tema padre]**, sviluppato e testato in locale con **wp-env**, versionato in un **nuovo repository Git**, con **un solo comando di controllo** che fa da cancello per ogni merge, pronto per il go-live. Quando hai finito faccio io un test in locale; se è tutto a posto do il via e portiamo tutto in produzione. 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. ## Prima del codice: il piano Studia il riferimento grafico, la copia locale del sito e il tema attuale, poi scrivi nel repository `docs/PIANO.md` con: - la struttura del tema e cosa resta al tema padre; - l'elenco dei blocchi, con nome, attributi, dove si usano e da dove prendono i dati; - i template che servono davvero e quelli che restano del padre; - le fasi di lavoro, ciascuna con i suoi criteri di verifica. Nel messaggio iniziale riassumi il piano insieme alle domande e alle proposte sulle decisioni aperte. Dopo la mia risposta il piano è approvato: parti e vai fino in fondo. ## Vincoli non negoziabili 1. **Tema nuovo, child theme di [tema padre]**, cartella e text domain `[nome del tema]`. Non si modifica il tema padre e non si evolve il tema attuale (puoi riportare da lì solo ciò che serve davvero). Non si modifica nessun plugin. 2. **Al tema padre restano header, footer e tutte le opzioni del Customizer** (palette, tipografia, costruttori di header e footer, opzioni dell'articolo, sidebar, barra di lettura, eventuali blocchi di contenuto del padre). Il tema aggancia e sovrascrive solo dove il padre non arriva. Niente `!important` contro il tema padre: dove c'è un'opzione si usa l'opzione. 3. **Componenti Gutenberg su misura**: ogni sezione con una struttura precisa è un blocco dinamico con `block.json` (`apiVersion` 3) e `render.php`, build con `@wordpress/scripts`, registrazione da `blocks-manifest.php`. L'elenco dei blocchi è nel piano. Ogni blocco deve essere anche inseribile a mano dall'editor, con una descrizione che dice cosa contiene e dove si usa. 4. **Template PHP nel child**, solo dove il padre non basta (di solito home, articolo, pagine, allegati, 404, commenti). 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. 5. **SEO e dati strutturati intatti**: titoli, meta, canonical, breadcrumb, schema JSON-LD e FAQ del plugin SEO non si toccano; il tema può cambiarne solo l'aspetto. Se il tema mostra un indice suo, usa le stesse ancore di quello del plugin, così i link già condivisi continuano a funzionare. 6. **Grafica coerente con il riferimento approvato**: stessi token (vedi «Dati del progetto») come custom property in `style.css`, collegati alla palette del tema padre; stesse proporzioni. Font serviti in locale, mai da servizi esterni. Animazioni solo leggere (comparsa allo scroll con `IntersectionObserver`, hover in CSS), `prefers-reduced-motion` rispettato. 7. **Performance**: CSS e JS solo dove servono (caricamento condizionale per template e per blocco), nessun jQuery, immagini con `srcset`, `loading="lazy"` tranne l'immagine LCP, `fetchpriority="high"` sulla copertina, preload dei font, nessun layout shift, HTML semantico con un solo H1. Obiettivo misurabile: Lighthouse mobile con Performance, Accessibility, Best Practices e SEO almeno a 95 sulle pagine chiave, Core Web Vitals verdi. Conta anche il lavoro che il PHP evita: misura le query di ogni template e togli quelle inutili. 8. **Best practice WordPress**: WordPress Coding Standards (phpcs), PHPStan al livello 6 o più, escaping e sanitizzazione in ogni `render.php`, `wp_kses` per l'HTML, nonce sui form, `WP_Query` con `no_found_rows` e cache dei meta solo quando servono, cache oggetti per le query ripetute con l'ultima modifica degli articoli nella chiave (si invalida da sola), i18n con il text domain, accessibilità (focus visibile, menu e finestre usabili da tastiera e chiusi con Esc, contrasti AA). 9. **Regole di codice**: pensa prima di scrivere, scrivi il minimo codice che risolve il problema, nessuna astrazione per codice usato una sola volta, modifiche chirurgiche, commenti sul perché e non sul cosa. Codice e identificatori in inglese, commenti e documentazione in [lingua]. 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. ## Ambiente di sviluppo: wp-env - Usa `@wordpress/env` con un `.wp-env.json` nel repository che monti il tema dal repository e, dalla copia locale, il tema padre, i plugin, i mu-plugin e gli uploads (con `mappings`, senza duplicarli). Allinea PHP e WordPress alle versioni di produzione. - **Database**: importa il dump e fai il `search-replace` degli URL. Se serve un dump più fresco lo fai tu dal server, in sola lettura. Il dump e le credenziali non entrano mai nel repository. - **Velocità**: se il sito locale impiega più di un secondo a pagina, risolvi prima questo (su Windows con Docker spesso basta servire WordPress da una copia dentro il container). Con tempi alti Lighthouse misura il disco, non il tema. - **Licenze**: se il tema padre ha un'estensione Pro, attivala in locale e impedisci alla copia di parlare con il server delle licenze al posto del sito vero (blocca le chiamate in uscita verso quel servizio e spegni il cron). - Plugin di cache disattivati in locale; gli altri plugin restano quelli della copia. ## Repository e controlli - Crea un **nuovo repository privato** con `gh repo create`. Contiene solo il tema, con `.gitignore` (`node_modules`, `vendor`, file `.env` e, se decidi di generarla al deploy, `build`), `README.md` (cos'è, come si avvia wp-env, come si fa la build, come si pubblica), `CHANGELOG.md` e licenza GPL-2.0-or-later come WordPress. - Si lavora sempre su un branch per fase; in `main` si entra solo con una pull request che ha superato i controlli. - **Un solo comando, `npm run check`**, esegue in locale: - phpcs con WPCS e PHPCompatibility per la versione PHP di produzione, e PHPStan; - lint di JavaScript e CSS e build dei blocchi; - un controllo dei contrasti sulle coppie di colori dei token; - PHPUnit su blocchi e funzioni del tema, dentro wp-env; - Playwright con test end-to-end su desktop e telefono delle pagine chiave (home, un articolo con FAQ e commenti, una pagina, un allegato, la 404), con axe per l'accessibilità e nessun errore in console; - Lighthouse mobile sulle pagine chiave, con la mediana di più corse e le soglie del vincolo 7. - Il comando fallisce se una soglia non è rispettata: è la **condizione di arresto** di ogni fase. Se una misura oscilla solo per il carico della macchina (di solito la Performance in locale sulle pagine più pesanti), trasformala in avviso, tieni come errori le altre categorie e i Core Web Vitals e scrivi il perché. - **I controlli devono controllare davvero**: per esempio il test di accessibilità fallisce se le regole valutate sono troppo poche. Un test verde che non verifica niente è peggio di un test rosso. - L'esito di `npm run check` va nella descrizione di ogni pull request. Una CI su GitHub Actions con gli stessi controlli è facoltativa (vedi «Decisioni aperte»). ## Processo per fase: sviluppatore e validatore Lavora per fasi, nell'ordine del piano. Per ogni fase: 1. **Criteri prima del codice**: all'inizio della fase scrivi i criteri di accettazione in `docs/fasi/N-nome.md` (cosa deve esserci e come si verifica). 2. **Sviluppo** su un branch `fase/N-nome`, affidato a un sub-agente sviluppatore. Pull request con descrizione, esito di `npm run check` e screenshot desktop (1440 px) e mobile (390 px) delle pagine toccate, accanto al riferimento grafico. 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 riferimento grafico della pagina e questo elenco di vincoli. Il validatore deve: leggere il diff, eseguire `npm run check`, aprire le pagine in wp-env e confrontarle con il riferimento, controllare escaping, accessibilità, performance e aderenza grafica, e restituire un verdetto `OK` oppure `KO` con l'elenco puntuale dei problemi (file, riga, cosa non va, cosa ci si aspetta). 4. Se `KO`, l'elenco torna allo sviluppatore, che corregge e aggiorna la PR; poi si rivalida con un validatore nuovo. **Si itera finché il validatore dice `OK` e il controllo è verde.** Se lo stesso punto rimbalza per più di cinque giri, scrivilo in `docs/DISACCORDI.md` con le due posizioni, vai avanti con il resto e riportamelo nel messaggio finale. 5. Merge in `main` e registrazione in `CHANGELOG.md`. Se puoi scegliere i modelli, usa un modello veloce per lo sviluppatore e il modello più capace che hai per il validatore. Fasi tipiche (da adattare nel piano): | Fase | Cosa | Verifica | |---|---|---| | 0 | Repository, wp-env, `npm run check` vuoto ma verde, import del DB, licenze | `wp-env start` pulito; sito identico all'attuale con il solo tema padre | | 1 | Pelle: token, font locali, header e footer dal Customizer | stessi contenuti, cambia solo l'aspetto; Lighthouse uguale o migliore | | 2 | Articolo: template, sidebar, blocchi di fine articolo, FAQ, commenti | su tre articoli diversi (con e senza FAQ, con una o più categorie, con e senza commenti), desktop e mobile | | 3 | Home: blocchi e template | aderente al riferimento; testi modificabili senza PHP | | 4 | Pagine, archivi, allegati, 404 | aderenti al riferimento; pagine esistenti corrette senza lavoro manuale | | 5 | QA finale: tastiera, contrasti, `prefers-reduced-motion`, query, Lighthouse, documentazione, lista per il go-live | tutti i criteri delle fasi precedenti, controllo verde su `main` | Dopo il go-live ogni ritocco è una fase nuova, con lo stesso giro. ## Decisioni già prese (non rimetterle in discussione) [Elenca qui le scelte chiuse. Esempi: stile chiaro, niente variante notturna; sezioni della home e il loro ordine; cosa non deve esserci; commenti in una finestra `

` aperta con `showModal()`, visibili anche senza JavaScript, con l'URL `#comment-123` che apre la finestra; box autore largo quanto la griglia.] ## Decisioni aperte (proponi la tua scelta nel messaggio iniziale, poi procedi) 1. Contenuti ripetuti, come una CTA per categoria: blocchi di contenuto del tema padre (si gestiscono a clic, stanno nel database) o PHP nel tema (codice versionato e controllato). 2. Chi sceglie gli articoli in evidenza o da leggere dopo: un selettore nel blocco o un'opzione del sito. 3. Indice dell'articolo: un blocco del tema con le stesse ancore del plugin SEO, oppure l'indice del plugin spostato in sidebar. 4. Commenti: nativi o servizio esterno. 5. Pagine degli allegati: redirect all'articolo oppure un template dedicato con `noindex`. 6. Cartella `build/` nel repository o generata al momento del deploy. 7. CI su GitHub Actions oppure solo `npm run check` in locale. 8. Nome del repository. ## Configurazione del tema padre e lista per il go-live Tutte le configurazioni del tema padre (palette, font locali, header e footer, opzioni dell'articolo, sidebar, barra di lettura, eventuali blocchi di contenuto) le fai tu in locale, e in produzione si rifanno al mio via. Perciò, man mano che le fai, annotale in **`docs/GO-LIVE.md`** in forma eseguibile: esportazione del Customizer salvata in `docs/export/` e aggiornata a ogni fase, più comandi `wp option` o passi manuali per tutto quello che l'esportazione non copre (widget, menu, impostazioni dei plugin, opzioni create dal tema, pagina Home impostata come front page). `GO-LIVE.md` deve essere una checklist completa e ordinata: 1. **Backup** di produzione prima di tutto: dump del DB, archivio del tema attuale, esportazione del Customizer e delle opzioni che cambierai, con il comando esatto per il ripristino. 2. Caricamento del tema (senza `node_modules`, con `build/`), attivazione, import del Customizer, configurazioni elencate, pagina Home. 3. Svuotamento delle cache e **verifica automatica**: home, alcuni articoli, una pagina, un allegato e la 404 rispondono; titolo, meta description, canonical, immagine social, robots e schema della home identici a prima; `.htaccess` invariato; sitemap e `robots.txt` raggiungibili; Lighthouse sul sito vero. 4. **Rollback** in poche righe: riattivare il tema precedente, reimportare il Customizer, ripristinare il DB se serve. Prova la sequenza in locale con uno script che ricostruisce il sito da un dump fresco ed esegue gli stessi passi, fermandosi al primo errore. 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**. ## Consegna finale Quando tutte le fasi sono in `main` con il controllo verde, scrivimi un unico messaggio con: il comando per avviare wp-env e l'URL locale con utente e password di test; l'elenco delle pagine da guardare e cosa controllare; le decisioni prese sulle questioni aperte; gli eventuali punti in `docs/DISACCORDI.md`; le decisioni che restano a me, in un elenco numerato a cui posso rispondere punto per punto; il link a `GO-LIVE.md`. Poi aspetti il mio test e il mio via.