Dare memoria al software: architettura, documentazione e pattern per l'AI
Quando si introduce l'AI nello sviluppo software, una delle prime difficoltà che emerge riguarda il contesto. Un AI coding agent può analizzare un repository, leggere il codice, individuare dipendenze e comprendere progressivamente come funziona un'applicazione. Ma se ad ogni nuova richiesta deve ripartire da zero, una parte del vantaggio dell'AI viene inevitabilmente persa. E se invece il software potesse raccontare la propria architettura all'AI prima ancora che questa inizi a modificare il codice? È qui che diventano importanti architecture discovery, documentazione tecnica e pattern specifici per l'AI.
Prima di modificare il codice, bisogna conoscere il sistema
Quando si lavora su un software esistente, la prima attività non dovrebbe essere necessariamente scrivere codice. Bisogna capire:
- quali sono i principali componenti;
- come comunicano tra loro;
- dove risiede la logica di business;
- quali database e servizi esterni vengono utilizzati;
- quali sono i punti di ingresso dell'applicazione;
- quali dipendenze sono critiche;
- quali convenzioni vengono utilizzate nel progetto.
Questa attività di architecture discovery può essere fatta analizzando il codice esistente e producendo una rappresentazione strutturata dell'architettura.
Non si tratta semplicemente di creare un diagramma: l'obiettivo è costruire una conoscenza riutilizzabile del sistema.
La documentazione diventa parte del contesto dell'AI
Tradizionalmente la documentazione tecnica è stata spesso considerata qualcosa da aggiornare "quando c'è tempo". Con lo sviluppo assistito dall'AI può assumere un ruolo diverso.
Un documento che descrive l'architettura, le principali decisioni tecniche e le convenzioni del progetto può diventare direttamente parte del contesto utilizzato dall'AI.
Per esempio, invece di chiedere "Aggiungi questa funzionalità" si può fornire all'agent anche il contesto necessario: "Questa applicazione utilizza un'architettura a servizi. La logica di business deve rimanere nei domain service. Gli accessi al database passano attraverso il repository layer. Le API pubbliche utilizzano questo pattern..."
L'AI non deve quindi dedurre ogni volta queste regole analizzando decine o centinaia di file. Le regole vengono dichiarate.
Non tutta la documentazione serve allo stesso modo
Una documentazione utile all'AI non deve necessariamente essere enorme. Anzi, documentazione troppo lunga e poco strutturata può diventare difficile da utilizzare.
È più utile avere informazioni precise e facilmente consultabili:
- Architecture: descrive la struttura generale del sistema, i componenti e le loro relazioni.
- Architecture Decision Records: raccolgono le decisioni architetturali importanti e soprattutto il loro motivo. Non solo "Utilizziamo PostgreSQL", ma "Utilizziamo PostgreSQL perché il dominio richiede transazioni consistenti e query relazionali complesse".
- Coding patterns: descrivono come vengono normalmente implementate determinate funzionalità.
- Business rules: rendono esplicite le regole che altrimenti l'AI dovrebbe cercare nel codice.
- Integration patterns: descrivono come il sistema comunica con API, ERP, CRM, servizi esterni e altri componenti.
Queste informazioni diventano una sorta di mappa del sistema.
Dal codice ai pattern
Un altro passaggio interessante è l'identificazione dei pattern presenti nel software. Analizzando un sistema esistente si possono individuare ricorrenze:
- come vengono create le API;
- come vengono gestiti gli errori;
- come vengono effettuate le validazioni;
- come vengono implementati repository e servizi;
- come vengono gestiti logging e autorizzazioni;
- come vengono strutturati i test.
Questi pattern possono essere descritti e trasformati in istruzioni riutilizzabili.
A quel punto, quando l'AI deve implementare una nuova funzionalità, non deve necessariamente capire da zero come deve essere scritto quel tipo di codice. Può seguire il pattern già adottato dal progetto.
L'obiettivo: evitare il "rileggi tutto il repository"
Questo è probabilmente uno dei vantaggi più interessanti. Immaginiamo un progetto che contiene centinaia di migliaia di righe di codice.
Per aggiungere una nuova funzionalità, un agent potrebbe dover esplorare:
repository → componenti → dipendenze → implementazioni simili → convenzioni → codice da modificare
Se una parte di questa conoscenza è già stata estratta e strutturata, il processo può diventare:
architettura → regole → pattern → implementazione
Il codice rimane la fonte definitiva per il comportamento effettivo del sistema, ma la documentazione permette all'AI di arrivare molto più rapidamente nei punti giusti.
Non significa sostituire il codice con la documentazione. Significa evitare di utilizzare il codice ogni volta come unica fonte per ricostruire il contesto.
Una sorta di "memoria tecnica" del progetto
Possiamo vedere questo insieme di informazioni come una memoria tecnica del software. Non è una memoria generica: è composta da conoscenze specifiche.
- Come è fatto il sistema?
- Perché è stato progettato in questo modo?
- Quali regole devono essere rispettate?
- Quali pattern devono essere utilizzati?
- Quali errori devono essere evitati?
Questa memoria può accompagnare gli AI agent durante l'intero ciclo di sviluppo. E soprattutto può evolvere insieme al software.
Quando cambia un'architettura, cambia la documentazione. Quando viene introdotto un nuovo pattern, viene aggiunto. Quando una decisione tecnica viene modificata, viene registrata.
Architecture discovery e AI possono diventare un processo continuo
Questo porta a un modello interessante per i sistemi software esistenti.
- Fase 1 - Discovery: l'AI analizza il codice e identifica struttura, dipendenze, componenti e pattern.
- Fase 2 - Documentazione: le informazioni vengono trasformate in documentazione tecnica strutturata.
- Fase 3 - Standardizzazione: i pattern ricorrenti e le decisioni architetturali vengono formalizzati.
- Fase 4 - AI-assisted development: gli agent utilizzano questa conoscenza per implementare nuove funzionalità.
- Fase 5 - Aggiornamento: le modifiche significative al software aggiornano anche la conoscenza architetturale.
In questo modo la documentazione non è più qualcosa che descrive semplicemente il software dopo che è stato costruito. Diventa parte dell'infrastruttura necessaria per continuare a costruirlo con l'AI.
Il vero problema non è far leggere più codice all'AI
La tentazione, quando l'AI sbaglia, è spesso quella di darle più codice. Ma non sempre è la soluzione: a volte il problema non è la quantità di informazioni, ma la loro organizzazione.
Un agent che deve leggere migliaia di file per capire come funziona un'applicazione sta ricostruendo una conoscenza che il team potrebbe aver già esplicitato.
La sfida diventa quindi costruire un contesto tecnico riutilizzabile. È un passaggio importante nello sviluppo software assistito dall'AI: da "facciamo leggere all'AI il nostro codice" a "facciamo conoscere all'AI come è fatto e come deve essere evoluto il nostro software."
Ed è probabilmente questo uno degli elementi che permetteranno agli AI coding agent di lavorare in modo sempre più efficace anche su sistemi complessi e di lunga durata.
Leggi anche gli altri articoli della serie: