Il sito era nato su PrestaShop 1.6. Poi erano arrivati override delle classi, controller modificati e moduli custom scritti in momenti diversi. A un certo punto, prima ancora di capire come portarli verso una versione nuova, serviva ricostruire che cosa facessero.
Una parte del lavoro era nel codice. Un’altra nelle relazioni fra quei pezzi: dove entrava un dato, chi lo modificava, quale modulo si aspettava di ritrovarlo. Leggere un file alla volta lasciava aperta tutta questa seconda parte.
Nota del 13 ottobre 2026. Questo è il racconto di un lavoro storico sui moduli legacy. La revisione chiarisce il metodo e i suoi limiti; non aggiorna lo stato del rilascio di quel sito né certifica la compatibilità attuale dei singoli moduli.
Separare per riuscire a capire
Nel lavoro raccontato qui avevo isolato i moduli sviluppati internamente in repository dedicati. In ogni repository potevamo concentrarci su un contesto più piccolo: funzioni, hook, tabelle, interfacce e dipendenze di quel modulo.
La separazione aiutava a leggere il codice. Le dipendenze, però, continuavano a esistere. Se un modulo si appoggiava a un altro, dovevamo conservare anche quel collegamento nell’analisi. Una cartella pulita non rende indipendente un pezzo che prima non lo era.
Prima capire cosa succedeva
Insieme agli agenti avevamo organizzato gli audit dentro audit_update/. I documenti descrivevano cosa faceva il modulo, quali hook usava, come lavorava sui dati, quali schermate esponeva e da quali altri componenti dipendeva.
Il codice originale restava il riferimento. Un report poteva rendere più leggibile un comportamento, ma poteva anche perderne uno o interpretarlo male. Per questo l’analisi passava attraverso revisioni, domande e correzioni prima di diventare il punto da cui sviluppare.
La cartella cominciava così a contenere qualcosa che una nuova sessione poteva rileggere, senza dover ricostruire tutto dalla conversazione precedente.
Le istruzioni nascevano dall’analisi
Da quel materiale preparavamo AGENTS.md: obiettivi, vincoli, ruoli e regole per chi avrebbe lavorato sul modulo. Auditor, Architect, Coder e Reviewer erano modi per distinguere i compiti dentro il flusso.
Separare i compiti aiutava a mettere in discussione il lavoro. Avere un agente chiamato Reviewer, però, non bastava a rendere corretta la sua revisione. Anche i suoi rilievi dovevano tornare al codice, alla documentazione e alle prove.
Le regole tecniche andavano scelte per la destinazione: versione di PrestaShop, ambiente PHP, API e parti del modulo da mantenere o cambiare. I requisiti ufficiali di PrestaShop e la documentazione dei moduli sono il riferimento da rileggere quando si affronta un lavoro nuovo. Il file di istruzioni conserva le scelte del progetto, non sostituisce quel controllo.
Il nuovo repository aveva un punto di partenza
Nel percorso descritto il nuovo repository partiva dall’audit e dalle istruzioni, per costruire il modulo destinato alla nuova versione. Era una scelta di quel lavoro, da valutare anche rispetto a quello che conveniva conservare.
Il passaggio utile era portare con noi la conoscenza raccolta: comportamenti da riprodurre, dipendenze, dubbi e verifiche necessarie. Ripartire dal codice nuovo senza quei riferimenti avrebbe reso più difficile accorgersi di una funzione persa per strada.
Prova, rifinisci, ritenta
Nel primo racconto avevo scritto “prova, rifinisci, ritenta, torna indietro, fallo due volte e poi ok”. Il problema è proprio quel “poi ok” 😀
Due giri non sono una misura della stabilità. Per decidere se un modulo è pronto servono le prove pertinenti: installazione, percorsi che usa davvero, dati che legge e scrive, convivenza con gli altri componenti. E condizioni di prova abbastanza chiare da poterle ripetere.
Il numero di revisioni racconta quanto ci abbiamo lavorato. L’esito delle verifiche racconta qualcosa sul risultato. Tenerli separati rende più utile anche l’analisi.
Il metodo che è rimasto
Da questo percorso avevo ricavato Audit-to-Refactor: leggere il sistema, conservare quello che abbiamo capito e usarlo per organizzare il lavoro successivo.
La scheda del metodo tiene insieme i due racconti. Il lavoro sul contesto dei progetti continua anche con Repo Forge, su un piano diverso: istruzioni, decisioni e piani da mantenere mentre cambia il codice.
La parte che mi interessa è quella che rimane fra una sessione e l’altra. Se il ragionamento è stato buono, devo poterlo ritrovare. Se era sbagliato, mi serve capire da dove eravamo partiti per poterlo correggere.