Caso studio: gestionale per agenzia con l'AI in 15 giorni di lavoro

Quando chiudo un progetto, prima di raccontarlo guardo i repository. Il calendario dice quello che vorrei fosse vero; git dice quello che è successo.

Il progetto di questo articolo è il gestionale interno di un’agenzia di Roma. L’agenzia mette in contatto i propri clienti con gli operatori: i clienti prenotano dal telefono, gli operatori dichiarano quando lavorano, il personale in sede registra i pagamenti e tiene i conti. Dal primo all’ultimo commit passano cinque settimane. Di lavoro vero ce ne sono state quindici: solo le giornate in cui il repository si è mosso, e git non dimentica.

L’ho costruito con l’AI, dall’inizio alla fine. Questo articolo spiega come, e soprattutto perché ha funzionato. Non è una storia su un modello che scrive codice: è una storia su un metodo che qualunque imprenditore può portare nella propria azienda.

Quindici giorni di lavoro, non cinque settimane

Tra il primo commit del 31 luglio e l’ultimo del 3 settembre il calendario conta cinque settimane. I commit ne contano quindici di giornate con attività reale, 108 in totale; la più densa è il 3 agosto, con 29 commit.

Cosa è uscito da quelle giornate: un’applicazione con 14 pagine e 82 file di codice, 11.633 righe scritte e 1.704 cancellate. Il database ha 15 tabelle, 26 funzioni e 34 regole di permesso a livello di dato. Le migrazioni sono 27, per 3.310 righe di SQL. Accanto, il sito pubblico è stato ricostruito nello stesso giro: 33 commit dal 22 luglio al primo settembre, 16 pagine di servizio.

Cosa	Numero
Giornate di lavoro vere	15 (su 35 giorni di calendario)
Commit	108
Righe scritte / cancellate	11.633 / 1.704
File di codice	82
Pagine dell’applicazione	14
Migrazioni del database	27 (3.310 righe di SQL)
Tabelle / funzioni nel database	15 / 26
Regole di permesso sui dati (RLS)	34
File di prove automatiche	25
Prove eseguite a ogni modifica	361

Le 361 prove meritano una nota, perché sono il numero più onesto di questa tabella. È il conteggio del 18 agosto, l’ultimo che ho scritto nel diario: 209 sono logiche, 120 passano dai permessi contro un database vero, 32 guardano l’interfaccia da uno schermo da 390 pixel. Da allora il codice è cresciuto, quindi oggi saranno di più. Non le ho ricontate e non le ho aggiornate: il punto dell’articolo sono i numeri veri, non quelli comodi.

Da soli i numeri non bastano. Il valore sta in quello che gira quando nessuno sta al terminale. Il rilascio in produzione esegue prima le prove, poi le migrazioni, poi il codice, sempre in quest’ordine. Ogni domenica un backup cifrato parte verso uno storage esterno. E il primo di ogni mese il backup viene riletto e contato, per verificare che si possa ripristinare.

Un backup che nessuno ha mai riaperto non è un backup.

Cosa fa, spiegato a chi non lo userà mai

È un’azienda vera, con utenti veri. Ogni schermata risponde a un lavoro dell’agenzia: niente wireframe, niente demo.

Il cliente apre il calendario, vede gli orari liberi raggruppati per operatore e prenota. Non paga dall’app: paga in sede, come ha sempre fatto. Sul telefono vede anche quanti appuntamenti gli restano, che è il motivo per cui lo apre la domenica sera.

L’operatore dichiara una volta le fasce in cui lavora. Dopo tocca solo le eccezioni: ferie, un buco, un recupero. Non vede le schede dei clienti, perché non gli servono.

La segreteria registra clienti e operatori, carica gli appuntamenti pagati, corregge gli errori, disdice e archivia il passato come «svolta» o «mancata».

C’è un dettaglio che vale un paragrafo, e non è mai stato in nessun requisito scritto. La conferma di prenotazione oggi dice con chi: «Prenotata: giovedì 6 agosto, 09:00 con Massimo». Prima diceva solo giorno e ora. L’ha chiesta il titolare in due secondi, guardando la pagina. (La regola generale: una correzione che arriva da chi conosce il lavoro vale più di tutte le specifiche scritte prima.)

Gli ambienti sono due, uno di prova e uno vero, e le prove non possono finire per sbaglio sui dati di produzione: una guardia confronta l’identificativo del database e blocca tutto se punta al posto sbagliato.

# Se l'ambiente punta al database sbagliato, ci si ferma.
if identificativo_database() != "agenzia_produzione":
    raise EnvironmentError("Le prove stanno girando contro i dati veri.")

L’AI non ricorda niente: il metodo dei quattro documenti

Ho usato l’AI come un collaboratore molto bravo e completamente smemorato. Il valore non sta nel modello. Sta nella memoria che gli ho costruito attorno, perché da sola l’AI dimentica tutto tra una sessione e l’altra.

Quella memoria è fatta di quattro documenti, ognuno con un compito preciso.

Le regole non derogabili sono un elenco di divieti, non di consigli, letto prima di ogni modifica. Tutto in italiano, variabili, messaggi e commit, con le parole dell’agenzia: cliente, operatore, appuntamento, disdetta. Mai ignorare un errore del database: se una lettura fallisce e nessuno controlla, l’utente legge «non hai appuntamenti» invece di «non siamo riusciti a leggere». Il vuoto per guasto diventa una bugia in interfaccia. Nelle email non si parla mai di soldi: «ti sono stati caricati 5 appuntamenti», mai il prezzo. I permessi stanno nel database, non nell’interfaccia. Nascondere un bottone non è una difesa. E i bersagli da toccare misurano almeno 44 pixel, con nessuna pagina che sborda su uno schermo da 390: prove automatiche lo verificano a ogni modifica.

Lo stato del lavoro è un file che dice, in ogni momento, cosa è fatto, cosa manca, cosa è bloccato e su chi. Chiude con la frase esatta da incollare nella chat successiva per ripartire. Cambiare sessione costa zero: non riparti da dove eri, riparti dalla frase.

Il diario è una voce per sessione, con cosa ho fatto e soprattutto perché. Tra sei mesi la domanda non sarà «cosa fa questo codice», ma «perché è scritto in questo modo strano». Il diario è l’unico posto dove quella risposta esiste.

Il registro delle trappole raccoglie le cose scoperte a nostre spese, scritte perché non si paghino due volte. Esempi veri: la cache che dopo un rilascio serve ancora la pagina vecchia per due minuti, e ha già fatto sbagliare due diagnosi; un componente del browser che ignora le misure che gli dai; una regola grafica che non si applica e non dà errore.

Il modello da solo non avrebbe prodotto niente di tutto questo. È la parte noiosa del lavoro, ed è la parte che funziona.

Le cinque cose trovate controllando, non ricostruendo

La parte più interessante è quella che è saltata fuori quando ho smesso di fidarmi di quello che c’era scritto e ho verificato. Cinque scoperte, tutte vere, tutte uscite da controlli che non erano nel piano.

Un pezzo dell’applicazione era un fantasma, pubblicamente raggiungibile: codice vecchio, nessuna protezione, collegato al database di prova. Nessuno sapeva che fosse lì. L’ho cancellato.

Un rilascio automatico che nessuno aveva chiesto: un’integrazione dimenticata provava a mandare online il codice a ogni modifica, senza aggiornare prima il database. È fallita, e per fortuna: se fosse riuscita, in produzione ci sarebbe finita un’applicazione che parla con un database che non la capisce.

Il pannello per modificare i testi del sito non ha mai funzionato. Nel file c’era scritto «dopo il deploy, sostituire…». Quel «dopo» non è mai arrivato: la pagina esisteva, il bottone esisteva, e non avrebbe mai potuto funzionare.

Un commento nel codice giustificava una scelta di sicurezza con una motivazione falsa. La scelta era giusta; la ragione scritta era sbagliata. Nessun test lo avrebbe mai segnalato: i commenti non si eseguono.

La firma di sicurezza mancava proprio sul primo contatto. L’indirizzo digitato a mano rimandava alla pagina di accesso senza nessuna protezione, cioè esattamente nel momento in cui quella protezione serve di più.

L’aneddoto preferito è quello della verifica rimasta appesa: la suite faceva 36 accessi in due minuti, contro un tetto di 30 ogni cinque. Passava per fortuna, a seconda di come il caso distribuiva i file nel tempo. Un giorno il controllo è durato 37 minuti invece dei soliti 7. Non era un guasto nuovo: era un difetto vecchio che finalmente si è visto.

La parte che nessuno racconta: i dati dei clienti

L’applicazione tratta dati personali dei clienti. Prima di agosto non sapeva fare nessuna delle tre cose che la legge dà per scontate. Ora le fa, e il modo in cui le fa dice più del codice.

L’informativa la registra il server, non il modulo. La colonna per la data di accettazione c’era già nel database, e non la riempiva nessuno: sembrava una prova e non lo era. Un modulo si costruisce anche a mano; il server no.

Chi vuole i propri dati se li scarica con un bottone, senza scrivere email a nessuno.

La cancellazione si chiama anonimizzazione, e la differenza è tutta commerciale. I pagamenti restano, perché sono la contabilità dell’agenzia; ad andarsene è la persona attaccata a quelle righe. L’operazione si ferma prima di fare danni, chiede di scrivere a mano la parola CANCELLA, e se riesce a metà lo dice apertamente invece di dichiarare fatto mezzo lavoro.

La conservazione dura cinque anni dall’ultimo contatto, ed è resa vera da una lista che dice chi non torna e da quando. Senza lista sarebbe una frase in un documento: nessuno apre il database a cercare i vecchi clienti. La lista non cancella niente da sola: decide una persona, guardando i nomi.

Poi c’è la parte che il codice non può risolvere, ed è scritta nero su bianco come compito del titolare: contratti con i fornitori, registro dei trattamenti, consensi su carta, nomina degli incaricati. Il software qui non c’entra: si fa su carta, con le firme.

Cosa l’AI non ha fatto

L’elenco di ciò che manca è fermo, e non è fermo per un bug. Ogni voce passa da una decisione o da una firma di una persona.

Serve un account intestato alla società, non a una persona. Serve una firma su un contratto. Serve una carta di credito. Serve una decisione che ha conseguenze su un altro sito, e quella la prende il proprietario. E serve che qualcuno carichi gli operatori veri e i primi clienti: oggi dentro la produzione c’è un solo utente, la segreteria. L’applicazione è in piedi, ma non lavora ancora.

C’è anche una scelta di continuità che non c’entra col codice: i repository sono passati da un account personale all’organizzazione della società, perché se quell’account sparisce, l’azienda perde rilasci e backup insieme. Nel trasferimento tutti i dodici segreti tecnici sono sopravvissuti; una sola cosa ha chiesto di essere ricollegata a mano.

Per la credibilità del racconto, questo elenco vale più di qualsiasi screenshot. Quando firme e decisioni arriveranno, dentro la produzione ci saranno clienti veri, prenotazioni e minuti risparmiati: quelli saranno i numeri del prossimo articolo.

FAQ: domande frequenti

L’AI ha scritto tutto il codice da sola?

No. L’AI ha scritto gran parte del codice, ma qualcuno doveva sapere cosa chiedere e come verificare il risultato. I quattro documenti sono la parte che ha reso il progetto finito in quindici giornate senza passare un’altra volta sugli stessi errori.

Quanto è durato il progetto, davvero?

Quindici giornate di lavoro vero su cinque settimane di calendario, tra il 31 luglio e il 3 settembre 2026. Le ore davanti allo schermo non le ho misurate e non le scrivo: sarebbe un numero inventato. Anche i costi di hosting, database ed email esistono, ma senza le fatture sotto gli occhi non pubblico cifre.

Posso farlo fare all’AI anche nella mia azienda?

Sì, se accetti che il lavoro vero non è chiedere, è scrivere prima ciò che il modello deve sapere. I quattro documenti non parlano di agenzie: parlano di regole, stato, perché e trappole. Valgono per un magazzino, uno studio, una clinica. Serve qualcuno che sappia dire «questo è giusto, questo no», e quella persona può essere un consulente esterno.

È sicuro gestire i dati personali dei clienti con un’app così?

L’app registra l’informativa lato server, esporta i dati su richiesta e anonimizza invece di cancellare. Il resto è carta e firme del titolare: contratti con i fornitori, registro dei trattamenti, consensi su carta, nomina degli incaricati. Il software non firma al posto tuo.