Prompt per sviluppare un tema WordPress child con Claude Code

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

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):

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 <dialog> 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.