L’intelligenza artificiale può accelerare alcune attività di sviluppo, ma il codice generato non dovrebbe essere accettato soltanto perché il prompt chiedeva di rispettare accessibilità, sicurezza e standard tecnici.
I modelli linguistici operano in modo non deterministico: possono prendere scorciatoie, commettere errori o inserire accidentalmente informazioni sensibili nel codice. Per agenzie e freelance, il problema non consiste quindi solo nello scrivere istruzioni migliori, ma nel trasformare i requisiti del progetto in controlli persistenti e verificabili.
Un possibile modello operativo è il project contract presentato da Chris Reynolds in un’intervista a WP Tavern. Non si tratta di uno standard ufficiale di WordPress, del W3C o del settore: è un insieme strutturato di regole, checklist e blocchi integrato nel workflow di sviluppo.
Di cosa parlerò in questa pagina
Perché un prompt non basta a controllare il codice generato dall’AI
Un prompt esprime un’intenzione. Può chiedere all’AI di usare HTML semantico, proteggere un form o controllare la navigazione da tastiera, ma non impedisce materialmente l’accettazione di una modifica che non rispetta queste indicazioni.
Un controllo coercitivo aggiunge invece tre elementi:
- regole persistenti, conservate nel repository e disponibili durante il progetto;
- verifiche definite, come build, linting, test e controlli di sicurezza o accessibilità;
- blocchi tecnici, capaci di fermare un commit o una pull request quando mancano la revisione o l’approvazione previste.
La differenza è sostanziale: non ci si limita a chiedere un risultato, ma si definiscono le condizioni necessarie per accettarlo. Questo non garantisce che il software sia accessibile o sicuro, ma rende il processo più esplicito e documentabile.
Che cos’è un project contract per lo sviluppo WordPress
Nel modello descritto da Reynolds, il project contract è un insieme di regole e checklist conservate nel repository. Può comprendere:
- uno o più file Markdown con requisiti e criteri di approvazione;
- indicazioni applicabili al codice generato o modificato con l’AI;
- un reviewer agent incaricato di eseguire controlli prestabiliti;
- verifiche su build, linting, test, accessibilità e possibili segreti nel codice;
- un pre-commit hook che impedisca il commit se la revisione manca o non è stata approvata.
Il contract rimane nel progetto e può essere versionato insieme al codice. A differenza di un’istruzione isolata in chat, diventa quindi un riferimento condiviso e aggiornabile.
Un esempio di struttura documentale
Un file Markdown potrebbe organizzare i criteri in questo modo:
## Build e qualità
- [ ] Build completata senza errori
- [ ] Lint completato senza errori
- [ ] Test previsti superati
## Sicurezza
- [ ] Escaping e sanitizzazione controllati
- [ ] Nonce e capability verificati dove richiesti
- [ ] Nessuna password, chiave API o token individuato
## Accessibilità
- [ ] HTML semantico controllato
- [ ] Gerarchia delle intestazioni verificata
- [ ] Navigazione da tastiera e focus verificati
- [ ] Form, contrasto e target interattivi controllati
## Approvazione
- [ ] Revisione automatica eseguita
- [ ] Verifica manuale completata
- [ ] Approvazione umana registrata
Questo esempio è una checklist organizzativa, non un file eseguibile né una certificazione. Le regole devono essere adattate agli standard interni, alle parti modificate e ai requisiti specifici del cliente.
I controlli tecnici da inserire nel contract
Il contract dovrebbe distinguere i controlli eseguibili automaticamente dalle verifiche che richiedono giudizio umano. Fra i criteri tecnici indicati nel modello rientrano i seguenti.
Build, linting e test
- richiedere che la build termini senza errori;
- eseguire il linting previsto dal progetto;
- verificare che i test definiti siano superati;
- applicare i controlli alle pagine o ai componenti modificati.
Il superamento di questi passaggi indica soltanto che i criteri configurati non hanno rilevato problemi. Non dimostra che il codice sia privo di difetti.
Controlli di sicurezza per WordPress
La checklist può richiedere verifiche su:
- escaping dell’output;
- sanitizzazione dei dati ricevuti;
- uso di nonce;
- controllo delle capability;
- presenza accidentale di password, token o chiavi API.
Questi criteri devono essere associati alle modifiche effettivamente realizzate. Un elenco generico, non collegato al codice interessato, rischia di diventare un adempimento formale anziché un controllo utile.
Blocco del workflow
Il pre-commit hook può impedire un commit quando la revisione richiesta non è stata eseguita o approvata. Lo stesso principio organizzativo può essere applicato alle pull request: se un criterio definito fallisce, la modifica non prosegue fino alla risoluzione o alla revisione prevista.
Il blocco non certifica la qualità complessiva del codice. Serve a far rispettare una sequenza di controlli concordata.
Come integrare l’accessibilità WordPress nei criteri di revisione
Per inserire l’accessibilità WordPress nel workflow non basta aggiungere una voce generica come “componente accessibile”. Occorre tradurre l’obiettivo in aspetti osservabili sulle pagine e sui componenti modificati.
Controlli da documentare
- HTML semantico: verificare che la struttura rappresenti correttamente contenuti e funzioni.
- Intestazioni: controllare la gerarchia usata nella pagina.
- Tastiera: provare l’uso dei componenti interattivi senza affidarsi al puntatore.
- Focus: verificare il comportamento durante la navigazione e le interazioni.
- Form: controllare i componenti e i relativi flussi di compilazione.
- Contrasto: includerlo tra le verifiche visive previste.
- Target interattivi: controllarne la dimensione.
Gli Accessibility Coding Standards di WordPress adottano le WCAG 2.2 livello AA come riferimento per il core, i siti WordPress.org e i plugin ufficiali. Le interfacce nuove o aggiornate sono inoltre incoraggiate ad applicare ATAG 2.0, con l’obiettivo di aiutare gli autori a produrre contenuti accessibili.
Per siti e applicazioni commerciali esterni all’ecosistema ufficiale, le WCAG 2.2 livello AA possono essere adottate come benchmark tecnico autorevole. Questo non estende automaticamente a ogni progetto gli standard dell’ecosistema ufficiale e non costituisce, da solo, una certificazione o una dichiarazione di conformità.
Perché test automatici e reviewer agent non sono sufficienti
L’automazione può eseguire controlli ripetibili e bloccare modifiche quando rileva condizioni previste. Non è però in grado, da sola, di valutare ogni aspetto dell’esperienza accessibile.
Esistono almeno tre limiti da considerare:
- Il controllo dipende dai criteri configurati. Un problema non incluso nelle verifiche può non essere rilevato.
- Il reviewer agent può sbagliare. Può anche replicare gli errori del modello che ha prodotto il codice.
- Zero errori non significa conformità WCAG. L’assenza di segnalazioni automatiche non dimostra da sola la conformità.
Il workflow deve quindi affiancare ai test automatici verifiche manuali su navigazione, linguaggio, usabilità, tecnologie assistive e percorsi reali. Prima del rilascio resta necessaria una revisione con approvazione umana.
Come adottare il workflow in agenzia o come freelance
Il project contract può diventare un asset riutilizzabile, purché non venga trattato come un documento immutabile. Un possibile percorso operativo comprende cinque passaggi.
1. Inserire il contract nello starter repository
Conservare regole e checklist nello starter repository dell’agenzia permette di versionarle e di renderle disponibili fin dall’avvio del progetto.
2. Adattare i criteri al progetto
La base condivisa deve essere aggiornata in funzione degli standard interni e dei requisiti del cliente. Anche i controlli devono concentrarsi sulle pagine, sulle funzioni o sui componenti coinvolti dalle modifiche.
3. Separare controlli automatici e manuali
È utile indicare chiaramente quali verifiche vengono eseguite dal reviewer agent e quali richiedono l’intervento di una persona. Questa distinzione evita di attribuire all’automazione una copertura che non possiede.
4. Definire le condizioni di blocco
Il team deve stabilire quando impedire commit o pull request: per esempio, se la revisione manca oppure se uno dei criteri obbligatori non è stato soddisfatto.
5. Documentare esiti e approvazione
Registrare i controlli eseguiti e i relativi esiti consente di presentare al cliente lo sviluppo assistito dall’AI come un processo governato. Non significa promettere assenza di errori, sicurezza completa o conformità automatica.
Una matrice operativa per il repository
| Area | Controllo | Gestione |
|---|---|---|
| Qualità del codice | Build, linting e test previsti | Verifica automatica e blocco in caso di fallimento |
| Sicurezza | Escaping, sanitizzazione, nonce e capability | Checklist e revisione del codice interessato |
| Segreti | Password, token e chiavi API | Scansione prima dell’accettazione della modifica |
| Accessibilità | Semantica, intestazioni, tastiera, focus, form, contrasto e target | Test automatici affiancati da verifiche manuali |
| Rilascio | Esito dei controlli e revisione | Approvazione umana |
Governare l’AI invece di affidarsi alle sue promesse
Il valore del project contract non sta nella promessa di generare automaticamente codice accessibile e sicuro. Sta nella possibilità di rendere espliciti i criteri del progetto, collegarli a controlli ripetibili e impedire che una modifica prosegua senza la revisione richiesta.
Per agenzie web, digital agency e professionisti, questo approccio permette di presentare l’AI come uno strumento inserito in un processo controllato, nel quale automazione e supervisione umana svolgono ruoli distinti.
Vuoi impostare un workflow WordPress assistito dall’AI con criteri documentati di accessibilità, sicurezza e revisione? Contattami per saperne di più.
Fonti
- #233 – Chris Reynolds on Building Trust With Project Contracts for Reliable AI Development (wptavern.com)
- Accessibility Coding Standards – Coding Standards Handbook | Developer.WordPress.org (developer.wordpress.org)
- Web Content Accessibility Guidelines (WCAG) 2.2 (www.w3.org)
Domande frequenti
È un modello operativo composto da regole persistenti, checklist e criteri di approvazione conservati nel repository. Può includere file Markdown, reviewer agent e pre-commit hook. Non è uno standard ufficiale di WordPress o del W3C.
Il prompt fornisce istruzioni al modello durante un’interazione. Il project contract mantiene nel repository regole e checklist e le collega a verifiche e blocchi tecnici. Chiedere all’AI di produrre codice accessibile non equivale a controllare che i criteri stabiliti siano stati soddisfatti.
La checklist può includere HTML semantico, gerarchia delle intestazioni, navigazione da tastiera, comportamento del focus, form, contrasto e dimensione dei target interattivi. I controlli vanno applicati alle pagine o ai componenti modificati.
No. L’assenza di errori nei test automatici non dimostra, da sola, la conformità alle WCAG. Servono anche verifiche manuali, prove sui percorsi reali e approvazione umana.
Il reviewer agent può eseguire i controlli previsti dal contract. Il pre-commit hook può impedire il commit quando la revisione manca o non è stata approvata. Un reviewer agent può comunque commettere o replicare errori e non sostituisce la code review umana.
Perché aspetti come navigazione, linguaggio, usabilità, impiego delle tecnologie assistive e percorsi reali non possono essere dimostrati soltanto tramite controlli automatici. La decisione finale prima del rilascio deve quindi rimanere sotto responsabilità umana.
