Quando una codebase viene creata o modificata con agenti AI, il controllo non può limitarsi a verificare che il sito funzioni o che lo scanner non segnali errori. Serve un processo capace di distinguere i problemi reali dai falsi positivi, proteggere i fallback necessari e valutare ogni intervento rispetto ai browser supportati e ai requisiti del progetto.
Le Modern Web Guidance pubblicate da Google possono essere utilizzate come primo livello di un audit del codice AI. Il loro legacy-scan individua specifici pattern codificati e fornisce una base per la modernizzazione. Non è però un audit tecnico completo e non certifica la qualità, la sicurezza o la conformità del sito.
Di cosa parlerò in questa pagina
Modern Web Guidance: che cosa sono e che cosa non sono
Le Modern Web Guidance 1.0 sono un progetto open source rivolto agli agenti di coding AI. Raccolgono best practice web, dati di compatibilità Baseline e indicazioni relative a fallback e progressive enhancement. Il progetto tratta aree come HTML, CSS, API JavaScript, performance, sicurezza e accessibilità.
È importante chiarire subito tre limiti:
- le Guidance non stabiliscono se il codice sia stato generato dall’AI;
- il superamento della scansione non certifica qualità, sicurezza o conformità;
- il legacy-scan copre solo una parte dei pattern descritti dalle guide.
La definizione “audit codice AI” indica quindi il contesto in cui viene applicata la procedura: codebase realizzate o modificate con il supporto di agenti AI. Non significa che lo strumento possa attribuire con certezza l’origine di ogni porzione di codice.
Come funziona il legacy-scan
La scansione viene eseguita localmente sul repository e riguarda:
- file HTML e CSS;
- JavaScript e TypeScript;
- componenti di framework;
- il file
package.json.
La prima scansione usa parser AST, DOM e CSS. È descritta come deterministica e senza chiamate a un LLM: cerca pattern legacy già codificati nelle regole dello scanner. Questo rende il primo passaggio ripetibile, ma ne delimita anche la copertura.
L’assenza di chiamate a un modello linguistico durante la prima scansione non significa che l’intero workflow sia privo di AI. Nelle fasi successive l’agente può recuperare le guide, interpretare i risultati e proporre un refactoring. È proprio in questo passaggio che il controllo umano diventa essenziale.
Workflow per un audit del codice AI controllato
Per una web agency, una digital agency o un freelance, eseguire il comando non è sufficiente. La scansione deve essere inserita in una procedura verificabile.
1. Definire il perimetro
Prima di iniziare occorre documentare:
- stack e dipendenze del progetto;
- browser e versioni che devono essere supportati;
- componenti e flussi critici;
- obiettivi di performance e accessibilità;
- eventuali fallback e vincoli già presenti.
Senza questo quadro non è possibile stabilire se una soluzione apparentemente legacy debba essere rimossa, mantenuta o sostituita in modo progressivo.
2. Installare le Guidance o avviare la scansione
Il dossier riporta due comandi:
npx modern-web-guidance@latest install
oppure, per avviare il legacy-scan sulla directory corrente:
npx modern-web-guidance@latest legacy-scan .
Il primo passaggio dovrebbe essere eseguito senza modificare i file, così da ottenere un quadro iniziale e produrre un report prima di intervenire sulla codebase.
3. Verificare i finding nel loro contesto
Ogni risultato deve essere controllato attraverso i criteri keepWhen e dropWhen previsti dalle guide. La verifica serve a distinguere:
- un problema effettivo da un pattern formalmente rilevato ma ancora necessario;
- codice obsoleto da un fallback intenzionale;
- un finding valido da una regola già protetta tramite
@supports; - una modernizzazione applicabile da una soluzione incompatibile con i browser richiesti.
Poiché la copertura è parziale, l’assenza di finding non dimostra che la codebase sia priva di problemi.
4. Preparare report e piano di intervento
I risultati confermati possono essere ordinati in base all’impatto:
- sicurezza e rischio di perdita dei dati;
- accessibilità e compatibilità;
- performance e dipendenze;
- semplificazione e debito tecnico.
Il report dovrebbe separare i finding confermati, i falsi positivi, i fallback da mantenere e gli elementi che richiedono ulteriori test. In questo modo il committente può valutare rischi, priorità e budget prima del refactoring.
5. Recuperare le guide e applicare il refactoring
Il workflow completo prevede scansione, verifica contestuale, report e piano, recupero delle guide pertinenti, refactoring e una nuova esecuzione di scanner e test.
Il progetto non offre deliberatamente un’opzione automatica --fix. Una sostituzione tecnicamente plausibile può infatti alterare il comportamento dell’interfaccia, eliminare una compatibilità necessaria o introdurre una regressione non visibile nell’analisi statica.
Le correzioni dovrebbero essere applicate in piccoli lotti, su branch separati e con l’approvazione di uno sviluppatore.
Dai finding al piano di intervento
Lo scanner individua pattern, non prende decisioni di progetto. La valutazione professionale deve rispondere almeno a queste domande:
- Il pattern segnalato produce un problema reale nel contesto corrente?
- La soluzione proposta è compatibile con il target Baseline e con i browser supportati?
- Esiste un fallback intenzionale che deve essere conservato?
- La modifica incide su tastiera, focus, tecnologie assistive o validazione dei form?
- Quali test possono dimostrare che il comportamento non è cambiato in modo indesiderato?
Questo passaggio evita di trasformare la modernizzazione in una sostituzione indiscriminata del codice esistente.
Quali pattern può suggerire di modernizzare
Tra gli esempi documentati nelle Guidance rientrano:
field-sizing: contentper determinati campi ridimensionabili;- il controllo di
isComposingnella gestione degli input; - la pseudo-classe
:user-invalid; - l’uso appropriato dei token
autocomplete; - la Popover API;
- il selettore
:has(); - Subresource Integrity per le risorse pertinenti.
Le API native possono offrire vantaggi potenziali per semantica, interazione da tastiera, tecnologie assistive e carico sul main thread. Questi benefici, però, non sono automatici: devono essere verificati sul progetto concreto in base all’implementazione, ai browser supportati, al target Baseline e agli eventuali fallback.
I test da aggiungere dopo la scansione
Il legacy-scan non misura autonomamente Core Web Vitals, comportamento reale dell’interfaccia, regressioni visuali, memory leak o problemi che emergono solo durante l’esecuzione. Non equivale inoltre a un audit WCAG e non sostituisce i controlli di sicurezza.
Dopo il refactoring è quindi opportuno integrare più livelli di verifica:
- Performance: Lighthouse e controllo dei Core Web Vitals;
- Accessibilità: test automatici e verifiche manuali, comprese tastiera, focus e tecnologie assistive pertinenti;
- Sicurezza: vulnerability scanning e controlli su CSP, cookie, sanitizzazione e header;
- Compatibilità: test nei browser previsti dal progetto;
- Interfaccia: visual regression test;
- Flussi applicativi: test end-to-end sui percorsi critici;
- Controllo finale: nuova esecuzione dello scanner dopo ogni lotto di modifiche.
Un codice che supera il legacy-scan può comunque presentare difetti di runtime, problemi architetturali o comportamenti non rilevabili tramite regole statiche.
Telemetria: che cosa verificare
Il repository dichiara la raccolta di dati anonimi relativi all’agente chiamante, alle guide recuperate e alle query eseguite tramite CLI. Secondo le informazioni disponibili, i prompt originali non vengono raccolti.
La telemetria può essere disabilitata impostando la variabile:
DISABLE_TELEMETRY=1
Prima di usare lo strumento su un progetto è utile verificare questa configurazione rispetto alle procedure interne dell’agenzia o del cliente.
Perché la revisione umana resta centrale
Il valore professionale non consiste soltanto nell’avviare lo scanner. Consiste nel validare i finding, individuare i falsi positivi, proteggere i fallback necessari e trasformare i risultati in un piano coerente con requisiti, rischi, compatibilità e budget.
Le Modern Web Guidance possono rendere più strutturato il primo livello di analisi, ma non sostituiscono lo sviluppatore. Un sito funzionante, o una codebase capace di superare lo scanner, non è automaticamente affidabile, accessibile, sicura o compatibile con tutti i browser richiesti.
Vuoi validare i risultati della scansione?
Posso supportare agenzie web, digital agency e professionisti nella verifica dei finding, nella definizione delle priorità e nell’integrazione del legacy-scan con test tecnici adeguati al progetto. Contattami per saperne di più.
AI Modified
Fonti
- Google Releases Modern Web Guidance 1.0 For AI Coding Agents via @sejournal, @MattGSouthern (www.searchenginejournal.com)
- Modern Web Guidance 1.0: The web platform expertise your coding agent is missing | Blog | Chrome for Developers (developer.chrome.com)
- How Modern Web Guidance modernizes your codebase—and why you should do it | Chrome for Developers (developer.chrome.com)
- GitHub – GoogleChrome/modern-web-guidance: Keep your coding agent up to date with the latest web best practices · GitHub (github.com)
Domande frequenti
No. Le Guidance individuano specifici pattern codificati nella codebase, ma non stabiliscono se il codice sia stato scritto da una persona o generato da un agente AI.
No. Può essere il primo livello di un audit del codice AI, ma la sua copertura è parziale. Non sostituisce analisi di runtime, test nei browser, controlli di sicurezza, verifiche di accessibilità e revisione dell’architettura.
La scansione riguarda HTML, CSS, JavaScript, TypeScript, componenti di framework e package.json. La prima analisi utilizza parser AST, DOM e CSS.
No. Non è prevista un’opzione automatica –fix. Le modifiche richiedono valutazione del contesto, applicazione controllata, test e approvazione di uno sviluppatore.
Ogni finding deve essere confrontato con i criteri keepWhen e dropWhen. Occorre inoltre verificare i browser supportati, il target Baseline, le regole protette da @supports e gli eventuali fallback intenzionali.
È necessario integrare test di performance e Core Web Vitals, controlli manuali e automatici di accessibilità, vulnerability scanning, verifiche di CSP, cookie, sanitizzazione e header, test nei browser, visual regression ed end-to-end.
Sì. La telemetria dichiarata può essere disabilitata tramite la variabile DISABLE_TELEMETRY=1.