Plugin per il caricamento automatico di form

Costruito con un agente, eseguito da codice deterministico, verificato da un secondo plugin

Periodo: dal 2026
Ruolo: progettazione e sviluppo
Ambito: automazione di portali esterni
Tecnologie: Claude Code · Playwright · MCP · Python · CSV · AppleScript
Stato: in uso, seconda fase aperta

a cosa serve

Una domanda di contributo pubblico nasce nell'applicazione di scrittura assistita e deve finire dentro un portale esterno: venti sezioni di form, sub-form ripetuti, allegati PDF, campi a tendina con testi predefiniti lunghi. Ricopiarla a mano è mezza giornata per pratica, e ogni ricopiatura è un'occasione di errore che nessuno rilegge.

Questi sono due plugin di Claude Code che fanno quel lavoro: il primo compila, il secondo controlla che quanto è finito nel portale coincida con quanto è uscito dall'applicazione. Sono la parte che chiude il cerchio descritto nella scheda della scrittura assistita, dove il metodo è riassunto in una riga: un agente per esplorare finché la mappa è ignota, codice fisso appena la mappa si stabilizza, una verifica indipendente che dice cosa è arrivato dall'altra parte.

il flusso

Il plugin non tocca mai i dati: li legge da un export e li ricopia. La sessione autenticata la apre una persona, e il plugin ci entra dentro — è il motivo per cui l'automazione si ferma prima della firma.

L'avvio arriva da un bottone dell'applicazione: scarica un piccolo eseguibile che apre un terminale e lancia il plugin sulla cartella giusta. Chi carica la pratica non vede una riga di codice.

com'è fatto un plugin

Un plugin di Claude Code non è un programma: è un pacchetto di istruzioni che l'agente legge quando servono, più gli attrezzi deterministici che gli evitano di improvvisare.

La skill sta in duecento righe perché è sempre in contesto; i riferimenti sono nove volte tanto e si aprono solo al passo che li usa. È la stessa economia di un manuale con l'indice: si porta dietro l'indice, non il manuale.

La mappa dei form — URL, selettori, tipo di ogni campo — è il pezzo più grosso, ed è stata scritta esplorando il portale con l'agente: si fa il login a mano, gli si chiede di aprire una sezione alla volta e leggerne l'albero di accessibilità, e lui riempie la mappa. Fatta una volta, da lì in poi il caricamento non esplora più: legge.

due runtime, e perché

Conviene distinguere tre rapporti diversi con l'AI, perché «automazione fatta con l'AI» li confonde: c'è ciò che è generato con un modello e poi gira senza — la mappa dei form, il codice che la usa; c'è ciò che è guidato da un modello mentre lavora; e c'è ciò che ne è libero. Qui il caricamento vero è sempre andato sull'ultimo — il che non vuol dire che il modello sia marginale, perché è stato centrale in tutto quello che è venuto prima: ha mappato il portale campo per campo, ha scritto insieme a me il codice che oggi gira da solo, e ha condotto i caricamenti di collaudo su cui quel codice è stato corretto. Il percorso deterministico non è l'alternativa all'AI: ne è il prodotto.

Il primo runtime è quindi l'agente, che pilota il browser attraverso un server MCP: legge la pagina e sceglie come compilare ogni campo. È il modo in cui il portale è stato mappato e in cui si torna quando qualcosa cambia.

Il secondo è un CLI Python che usa la stessa libreria di automazione senza modello nel ciclo, ed è quello che gira in esercizio. È più veloce e ripetibile, e ha una forma dettata da un vincolo preciso: le versioni recenti di Chrome hanno chiuso l'aggancio a un browser già aperto dall'esterno, quindi invece di attaccarsi a una finestra esistente apre da sé una finestra dedicata, con un profilo isolato, e aspetta che l'operatore completi il login. Poi riconosce dall'indirizzo che la pratica giusta è aperta e parte.

Copre 14 delle 17 sezioni: le tre che mancano aspettano che l'applicazione a monte produca i dati corrispondenti, e intanto si compilano a mano.

C'è però un guadagno che si vede solo qui, ed è il motivo per cui, appena la mappa sta ferma, conviene congelarla in codice: il runtime deterministico si può testare, e ha una suite di 150 casi — abbinamento dei valori, riconciliazione fra quanto si voleva scrivere e quanto è finito nel portale, utilità delle sezioni ripetute, invio, ritentativi. Il percorso pilotato dal modello, per sua natura, no: se ne misura l'esito, non se ne fissa il comportamento.

la verifica, che è il pezzo che mi piace di più

Il secondo plugin rilegge dal portale quello che c'è scritto e lo confronta col file di partenza. Il problema è che il testo completo dei record sta nell'ordine dei 100 KB, e farlo uscire dal browser per confrontarlo fuori non è praticabile.

Una firma per riga dice se qualcosa è cambiato; una firma per campo dice dove. Non si trasporta il testo, si trasportano i numeri — e la normalizzazione dev'essere identica dalle due parti, altrimenti confronta rumore.

La parte delicata è proprio la normalizzazione: unificare le forme dell'apostrofo, gli spazi non separabili, i caratteri invisibili. E una regola che sembra una scorciatoia e non lo è: i campi a tendina si confrontano solo sui primi caratteri, perché è così che vengono abbinati in fase di caricamento — confrontarli per intero segnalerebbe come errori le varianti del testo predefinito del portale, che nessuno può cambiare.

L'ordine dei record non conta: il confronto è per insieme, non per posizione. Righe invertite non sono un errore, e dirlo come se lo fosse avrebbe reso il report inservibile.

le tre regole che evitano i danni veri

Mai indovinare un valore a tendina. Meglio un campo vuoto, segnalato nel report come «da compilare a mano», che un valore verosimile e sbagliato: il primo lo vede chi rilegge, il secondo no.
Controllo preventivo sull'identità della pratica. Prima di scrivere qualsiasi cosa, il plugin confronta il titolo che legge nel portale con quello dell'export. Se non coincidono si ferma con un avviso in maiuscolo. Su un account che contiene più domande, scrivere venti sezioni in quella sbagliata è il danno peggiore possibile, ed è anche il più facile da fare.
Non fermarsi al primo errore, ma dirli tutti. Una sezione che fallisce non interrompe le altre: si prosegue e si riporta alla fine. L'eccezione è la sessione scaduta, dove proseguire significherebbe solo accumulare fallimenti identici.

dove si ferma, di proposito

L'automazione compila i dati e basta. La generazione dei documenti finali, la convalida, la firma digitale e l'invio restano manuali — e non per una difficoltà tecnica: sono gli atti in cui una persona si assume la responsabilità di quello che sta dichiarando. Il login con la smart card è sempre a mano per la stessa ragione.

limiti dichiarati

La mappa dei form è una fotografia. Se il portale cambia una sezione, il caricamento fallisce lì e la mappa va rifatta con l'agente. È il prezzo di aver congelato l'esplorazione: in cambio, finché il portale sta fermo, non si paga un modello per riscoprire ogni volta la stessa cosa.
Tre sezioni su diciassette non sono coperte nel runtime deterministico, perché i dati a monte non esistono ancora.
La verifica copre tre sezioni, le tre in cui il testo lungo rende la ricopiatura più fragile. Le altre si controllano a occhio, che è esattamente ciò che questo plugin esiste per evitare.
I test coprono la metà deterministica, non l'altra. Il runtime Python ha la sua suite; il percorso pilotato dal modello e la mappa dei form si collaudano con esecuzioni di prova che non scrivono niente, contro una pratica reale già caricata a mano. È il limite naturale della parte che si adatta: si può misurare l'esito, non fissare il comportamento.