Quando hai un modulo vecchio da portare avanti, la prima difficoltà può essere capire cosa stai cercando di conservare. Il codice funziona dentro un sito, incontra dati e configurazioni, si appoggia ad altri moduli. Riscriverlo leggendo solo le funzioni rischia di lasciare fuori proprio quei collegamenti.
Nel racconto sul lavoro con PrestaShop legacy descrivo il contesto da cui è nato Audit-to-Refactor. Qui provo a spiegare come avevamo organizzato il percorso.
Che cosa intendo con Audit-to-Refactor
È il nome che ho dato al metodo per analizzare i moduli, conservare le informazioni utili e preparare lo sviluppo insieme agli agenti. L’audit produce un punto di partenza: funzioni, dipendenze, vincoli e dubbi. Il lavoro successivo deve ancora verificarlo.
Nel caso raccontato il metodo accompagnava la riscrittura di moduli verso una versione nuova di PrestaShop. Il refactoring di un componente e la migrazione del sito sono lavori collegati: la disponibilità di un modulo riscritto, da sola, non documenta il completamento della migrazione.
1. Delimitare il modulo e i suoi collegamenti
Nel percorso iniziale avevamo isolato i moduli custom in repository dedicati. Questa scelta restringeva il contesto da leggere, ma richiedeva di annotare le dipendenze che attraversavano quel confine.
Prima di decidere che un pezzo va riscritto, conviene capire quali funzioni servono ancora, quali sono già disponibili altrove e quali vincoli ci portiamo dietro. La riscrittura è una scelta da motivare, anche quando l’IA rende più facile cominciarla.
2. Conservare l’audit in una forma rileggibile
I report erano raccolti in audit_update/. La struttura descritta nel lavoro iniziale comprendeva:
01_overview.md: funzioni e scopo del modulo.02_hooks.md: hook usati e comportamento collegato.03_database.md: tabelle, dati e relazioni.04_ui.md: interfacce e form.05_dependencies.md: moduli e componenti esterni.06_notes_migration.md: rischi, scelte da valutare e verifiche mancanti.
I nomi dei file aiutavano a ritrovare le informazioni. Per un altro progetto possono cambiare. Quello che deve restare comprensibile è da dove arriva un’osservazione, quale comportamento descrive e dove manca ancora una risposta.
3. Rivedere l’analisi prima di usarla
Gli agenti aiutavano a leggere e a rivedere il materiale. Un secondo passaggio poteva trovare un errore del primo, oppure riprenderne la stessa interpretazione sbagliata. Per questo la revisione deve confrontarsi con codice, documentazione e prove del comportamento.
La documentazione ufficiale dei moduli PrestaShop e i requisiti della versione di destinazione servono anche a decidere quali regole mettere nel progetto. Una lista di tecnologie copiata da un audit vecchio può essere un altro pezzo da correggere.
4. Preparare istruzioni e piano di lavoro
In AGENTS.md avevamo distinto i compiti di analisi, architettura, sviluppo e revisione. Le istruzioni indicavano obiettivi e vincoli; il piano organizzava i passaggi da affrontare.
Se nasce un repository nuovo, l’audit e le istruzioni possono entrarci come contesto iniziale. I riferimenti al codice precedente vanno comunque conservati: servono per controllare ciò che il nuovo modulo deve fare.
Il contesto va poi aggiornato. Il lavoro che oggi faccio con Repo Forge riguarda proprio questa manutenzione: quando cambia il progetto, le istruzioni e le decisioni devono continuare a descriverlo.
5. Provare ciò che abbiamo costruito
Audit, istruzioni e piano rendono il lavoro più facile da seguire. La compatibilità e il funzionamento richiedono ancora verifiche sul modulo e sull’ambiente di destinazione.
Per il singolo intervento sceglierei prove che coprano installazione, percorsi funzionali, lettura e scrittura dei dati, dipendenze e condizioni in cui il modulo può fallire. Gli esiti devono restare collegati alla versione provata. Non basta una revisione del testo per dichiarare quei controlli eseguiti.
Due cose da chiarire
È un tool pronto da installare? Qui è documentato un metodo di lavoro. Nell’articolo originario avevo ipotizzato una CLI chiamata ps-migrate; era una possibile evoluzione, non la descrizione di un tool distribuito.
Il metodo garantisce una migrazione riuscita? Aiuta a organizzare analisi, sviluppo e controlli. Il risultato va dimostrato con le verifiche del progetto, comprese quelle sui passaggi fra moduli e sul sito che li usa.
La scheda di Audit-to-Refactor raccoglie questo percorso. La cosa utile dell’audit è poter tornare a una scelta e ritrovare il motivo per cui l’avevamo fatta. Anche quando, rileggendola, ci accorgiamo che va cambiata.