Scoperta dell'Architettura con IA: Come Funziona
L'anno scorso ho ereditato un codebase senza alcuna documentazione. 200.000 righe di codice distribuite su 15 servizi, scritte da un team che nel frattempo se n'era andato. Il mio compito era capire il sistema abbastanza bene da aggiungere una nuova integrazione di pagamento. L'azienda stimava che ci sarebbero volute 2-3 settimane solo per mappare l'architettura.
Quell'esperienza e il motivo per cui ho costruito la funzionalita di scoperta con IA di Archyl. E ora, dopo aver passato mesi a lavorare con modelli linguistici di grandi dimensioni per analizzare codice, voglio condividere cosa funziona davvero, cosa no, e perche la scoperta dell'architettura con IA e potente ma non magica.
Il Problema della Scoperta Manuale
Prima di immergerci nell'IA, riconosciamo perche ne abbiamo bisogno.
Quando mi sono trovato di fronte a quel codebase non documentato, il mio processo di scoperta e stato cosi:
Settimana 1: Fare grep nel codice cercando parole chiave. Trovare i punti di ingresso principali. Disegnare qualche riquadro su una lavagna. Rendermi conto che avevo frainteso i confini dei servizi. Cancellare e ridisegnare.
Settimana 2: Intervistare l'unico ingegnere che e in azienda da abbastanza tempo da ricordare qualcosa. Meta di quello che dice contraddice quello che ho trovato nel codice. Si scopre che le cose sono cambiate ma nessuno ha aggiornato il suo modello mentale.
Settimana 3: Finalmente sentire di capire il sistema abbastanza da poter fare modifiche. Creare documentazione che giuro di mantenere aggiornata. (Spoiler: non l'ho fatto.)
Questo processo e lento, soggetto a errori e non scala. Ogni nuovo membro del team attraversa la stessa dolorosa scoperta. La documentazione diventa obsoleta nel giro di mesi.
Come Funziona Davvero la Scoperta con IA
Quando colleghi un repository ad Archyl e avvii la scoperta, ecco cosa succede sotto il cofano:
Fase 1: Scansione del Repository
Per prima cosa, costruiamo una mappa del tuo codebase. Questa non e ancora IA — e una semplice scansione del file system:
- Elencare tutti i file e le directory
- Identificare i file di configurazione (package.json, go.mod, docker-compose.yml)
- Trovare i punti di ingresso (funzioni main, file index, route API)
- Costruire un grafo delle dipendenze dagli import
Questo ci da lo scheletro. Sappiamo quali file esistono e come si referenziano tra loro. Ma non capiamo ancora cosa fanno.
Fase 2: Analisi a Blocchi
Qui entrano in gioco gli LLM, e qui le cose si complicano.
I modelli linguistici moderni hanno limiti di contesto. GPT-4 puo gestire circa 128K token, Claude arriva a 200K. Sembra molto, ma un codebase di medie dimensioni li supera facilmente. Quindi non possiamo semplicemente scaricare l'intero codebase in un prompt e chiedere "cos'e questo?"
Invece, dividiamo il codebase in pezzi digeribili:
- Raggruppare i file per directory o modulo
- Inviare ogni blocco all'LLM con il contesto sulla sua posizione nel progetto
- Chiedere al modello di identificare: Di cosa e responsabile questo codice? Quali pattern usa? Con quali sistemi esterni interagisce?
Le risposte tornano come dati strutturati — JSON che descrive sistemi, container e componenti con le loro relazioni.
Fase 3: Aggregazione e Riconciliazione
Questa e la parte piu difficile, e dove ho speso la maggior parte del mio tempo di sviluppo.
Ogni analisi di blocco ci da una vista parziale. Il blocco del servizio utenti conosce il database utenti. Il blocco pagamenti conosce Stripe. Ma nessuno dei due conosce il quadro completo.
Dobbiamo riconciliare queste viste parziali:
- Unire entita duplicate ("UserDB" e lo stesso di "users_database"?)
- Inferire relazioni tra blocchi (il servizio ordini chiama il servizio utenti, ma sono stati analizzati separatamente)
- Risolvere conflitti (un blocco dice che usiamo PostgreSQL, un altro dice MySQL — qual e giusto?)
Questa riconciliazione usa un'altra analisi LLM, piu euristiche basate su pattern comuni. E imperfetta. A volte l'IA sbaglia. Per questo la scoperta produce suggerimenti che gli umani revisionano, non documentazione definitiva.
Fase 4: Generazione del Modello C4
Infine, mappiamo le entita scoperte sugli elementi del modello C4:
- Sistemi esterni (API di terze parti, database che non gestiamo)
- Container (le nostre unita distribuibili)
- Componenti (moduli principali all'interno dei container)
- Relazioni (chi chiama chi, quali dati fluiscono dove)
Il risultato e un insieme di bozze di diagrammi C4 che catturano la comprensione dell'IA della tua architettura.
Cosa l'IA Indovina Bene
Dopo aver eseguito la scoperta su decine di codebase durante lo sviluppo, ecco cosa mi ha impressionato:
Rilevamento dello Stack Tecnologico
Gli LLM sono notevolmente bravi nell'identificare quali tecnologie usa un progetto. Riconoscono pattern di framework, idiomi di librerie e formati di file di configurazione. Quando GPT vede un'annotazione @Controller, sa che stai usando Spring. Quando vede fiber.New(), sa che stai usando Go Fiber.
Rilevamento dei Confini dei Servizi
Nelle architetture a microservizi, l'IA identifica in modo affidabile i confini dei servizi. Capisce che il codice in /services/user/ e probabilmente un servizio separato da /services/order/. Riconosce i file Docker Compose come indicatori della topologia dei servizi.
Riconoscimento di Pattern Comuni
L'IA ha visto milioni di codebase nei suoi dati di addestramento. Riconosce pattern di repository, strutture MVC, architetture event-driven e configurazioni di API gateway. Quando il tuo codice segue pattern comuni, l'IA li identifica rapidamente.
Scoperta di Integrazioni Esterne
Ogni costante di chiave API, URL webhook o importazione di SDK e un indizio sulle integrazioni esterne. L'IA cattura la maggior parte di queste, costruendo un'immagine dei servizi di terze parti da cui il tuo sistema dipende.
Cosa l'IA Sbaglia
Ecco dove ho dovuto impostare aspettative realistiche:
Logica di Dominio Personalizzata
L'IA non capisce il tuo dominio di business. Puo dire che hai una funzione processOrder, ma non sa cosa significa "elaborare un ordine" nel contesto specifico del tuo business. Potrebbe identificare erroneamente lo scopo dei componenti specifici del dominio.
Architetture Insolite
Se la tua architettura non segue pattern comuni, l'IA ha difficolta. Un sistema di plugin personalizzato, una struttura di cartelle non convenzionale o un framework fatto in casa la confonderanno. L'IA si aspetta che le app Rails assomiglino ad app Rails.
Dipendenze Nascoste
Non tutte le dipendenze sono esplicite nel codice. Forse il tuo servizio richiede una versione specifica di Redis che esiste solo in produzione. Forse c'e un container sidecar che l'IA non vede mai. Le dipendenze a runtime sono spesso invisibili all'analisi statica.
Percorsi di Codice Obsoleti
L'IA non sa quale codice e attivamente usato rispetto a quale e cruft legacy che nessuno tocca da anni. Potrebbe mettere in evidenza un servizio deprecato che e ancora nel codebase ma non e piu deployato.
Far Funzionare Meglio la Scoperta con IA
Attraverso tentativi ed errori, ho trovato modi per migliorare la precisione della scoperta:
Fornire Contesto
Prima di avviare la scoperta, parla all'IA del tuo sistema. "Questa e una piattaforma di e-commerce con elaborazione pagamenti" da al modello un quadro di riferimento. Senza contesto, sta tirando a indovinare alla cieca.
Partire dalla Struttura
Se hai una documentazione esistente — anche solo un README con uno schizzo approssimativo dell'architettura — forniscila. L'IA la usa come riferimento per guidare la sua analisi.
Revisionare Incrementalmente
Non eseguire la scoperta sull'intero codebase in una volta. Inizia con un servizio. Revisiona e correggi i risultati. Poi espandi al servizio successivo. Le correzioni che fai informano le analisi future.
Fidarsi Ma Verificare
Tratta i suggerimenti dell'IA come un punto di partenza, non come la risposta definitiva. L'IA potrebbe essere accurata all'80%. Devi verificare l'altro 20%. Clicca sui link al codice sorgente, conferma che le relazioni hanno senso e correggi gli errori.
I Dettagli Tecnici
Per chi e curioso dell'implementazione:
Strategia di Chunking
Usiamo il chunking semantico invece di blocchi a dimensione fissa. Un blocco e tipicamente un modulo, un servizio o un albero di directory. Questo mantiene il codice correlato insieme, migliorando la comprensione dell'IA.
Ingegneria dei Prompt
I prompt si sono evoluti significativamente. Le prime versioni producevano descrizioni verbose e narrative. I prompt attuali richiedono output strutturato con campi specifici. Usiamo esempi few-shot per dimostrare il formato atteso.
Concorrenza
I codebase grandi hanno migliaia di file. L'elaborazione sequenziale richiederebbe un'eternita. Analizziamo i blocchi in parallelo, con limiti di concorrenza configurabili per evitare i limiti di frequenza delle API.
Selezione del Modello
Diversi modelli hanno diversi punti di forza. GPT-4 produce analisi piu accurate ma costa di piu. Claude e migliore nel seguire requisiti di output strutturato. Supportiamo entrambi, piu modelli locali via Ollama per team che non possono inviare codice ad API esterne.
Il Futuro della Scoperta con IA
Quello che abbiamo oggi e la versione 1. Ecco verso cosa sto lavorando:
Scoperta Continua
Invece di un'analisi una tantum, monitorare il codebase continuamente. Quando il codice cambia, aggiornare automaticamente i diagrammi rilevanti. Rilevare la deriva architetturale prima che diventi un problema.
Comprensione Piu Profonda
L'analisi attuale e principalmente strutturale. Le versioni future potrebbero comprendere il comportamento: "Questo endpoint valida l'input, chiama il servizio di pagamento e poi invia un'email di conferma." Diagrammi di sequenza generati dal codice.
Analisi Cross-Repository
La maggior parte delle organizzazioni ha piu repository. La scoperta dovrebbe capire come si collegano — quali servizi nel repo A chiamano servizi nel repo B.
Punteggio di Confidenza
Non tutte le scoperte sono ugualmente certe. Stiamo aggiungendo punteggi di confidenza cosi sai quali suggerimenti esaminare piu attentamente.
Conclusione
La scoperta dell'architettura con IA non e magia. E uno strumento che accelera le parti noiose della comprensione di un codebase richiedendo comunque il giudizio umano per le parti sfumate.
Quando oggi eseguo la scoperta su quel codebase di 200K righe, ottengo una bozza di diagramma architetturale in 10 minuti invece di 3 settimane. Non e perfetto — devo ancora revisionare e correggere. Ma e un punto di partenza drasticamente migliore di una lavagna vuota.
Se stai annegando in codice non documentato, prova la scoperta con IA. Approcciala con aspettative realistiche: non capira il tuo dominio di business, potrebbe non cogliere pattern insoliti e richiede sicuramente una revisione umana. Ma ti portera all'80% del percorso in una frazione del tempo.
Vuoi saperne di piu? Consulta la nostra introduzione al modello C4 che la scoperta con IA genera, o leggi perche la documentazione dell'architettura e importante.