Architettura a 3 livelli:codice pulito dall'AI

L'AI genera codice disordinato perché il tuo progetto non ha un'architettura, non perché l'AI sia scadente. Un'architettura a 3 livelli risolve il problema. Se le dai tre livelli chiari (componenti per la UI, servizi per la logica di business, un livello dati per il database) e fai i prompt un livello alla volta, la stessa AI produce codice pulito, testabile e scalabile. Ho costruito oltre 3M di righe così.

Ecco il pattern, perché funziona e l'esatta sequenza di prompt.

Il problema: l'AI senza struttura crea il caos

Chiedi all'AI di costruire una funzionalità. Ti dà del codice. Lo incolli. Una settimana dopo il tuo codebase è un disastro: chiamate al database sparse ovunque, logica di business mescolata alla UI, codice copiato e incollato dappertutto, impossibile da testare, si rompe quando provi a scalare.

Il problema non è l'AI. È la tua architettura.

L'AI genera ciò che le chiedi. Ma senza un'architettura chiara mescola le responsabilità, crea pattern incoerenti e non riesce a mantenere la struttura del tuo codebase: ogni prompt crea nuovo caos. L'AI non conosce la tua architettura. Devi guidarla tu.

La soluzione: un'architettura a 3 livelli

Immagina la tua app come una pila di tre piani. I componenti in alto: solo UI. I servizi in mezzo: logica di business. Il livello dati in basso: database e API. Ogni piano parla sempre e solo con quello immediatamente sotto. Quando l'AI sa su quale livello sta lavorando, genera codice pulito.

• Livello 1: componenti (solo UI). Cosa ci appartiene: logica di visualizzazione, interazioni dell'utente, routing, layout. Cosa no: chiamate al database, logica di business, validazione, permessi. Un cattivo componente va a prendere gli utenti dal database al proprio interno, filtrandoli per stato lungo la strada. Un buon componente chiede a un hook gli "utenti attivi", mostra uno skeleton di caricamento mentre aspetta e renderizza la lista. Questo è tutto il suo lavoro.
• Livello 2: servizi (logica di business). Cosa ci appartiene: recupero dei dati, validazione, permessi, regole di business, trasformazioni dei dati. Cosa no: qualunque cosa che renderizzi, o lo stato specifico di un componente. Un UserService conosce le regole (serve un'organizzazione, quali filtri si applicano, cosa succede in caso di errore) ed è l'unico posto in cui quelle regole vivono.
• Livello 3: dati (database e API). Query al database, chiamate API, integrazioni esterne. Si accede solo tramite i servizi, mai direttamente dai componenti.

Come fare i prompt all'AI con questo pattern

Il modo sbagliato è un solo prompt: "Costruisci una funzionalità di gestione utenti". Il risultato è tutto in un unico componente: chiamate al database, validazione, UI, tutto mescolato. Il modo giusto sono tre prompt, dal basso verso l'alto, uno per livello:

1. Prima il servizio: "Genera un UserService con metodi per leggere, creare, aggiornare ed eliminare utenti. Includi validazione e gestione degli errori."
2. Poi l'hook: "Crea un hook useUsers che avvolga lo UserService con la cache."
3. Per ultimo il componente: "Costruisci un componente UserList che usi l'hook useUsers. Mostra gli stati di caricamento e gestisci gli errori."

Risultato: codice pulito e separato, ogni livello concentrato sulla propria responsabilità. Chiedere tutto in una volta è l'errore numero uno: l'AI genera codice misto con tutti i livelli aggrovigliati. Un livello alla volta, costruendo dal basso.

Il libroThe Solopreneur RevolutionLuis Gonçalves su come costruire un'attività da solopreneur con l'IA mentre sei ancora dipendente.Scopri il libro →

Funziona con qualsiasi stack

Stesso pattern, strumenti diversi:

Hai già del codice disordinato? La migrazione in 5 passi

1. Trova tutte le chiamate al database. Cerca nei tuoi componenti le chiamate dirette a database e API.
2. Crea i servizi. Sposta tutto l'accesso ai dati in classi di servizio: la query che viveva dentro un componente ora vive in un metodo del servizio, con gestione degli errori.
3. Crea gli hook. Avvolgi ogni servizio con il livello di data fetching del tuo framework, così i componenti ottengono cache e stati di caricamento gratis.
4. Aggiorna i componenti. Sostituisci il pattern del fetch dentro il componente con una singola chiamata a un hook.
5. Fatti aiutare dall'AI. Prompt: "Fai il refactoring di questo componente per usare il pattern hook. Sposta la logica del database in un servizio." L'AI migrerà ogni pezzo.

Il vantaggio si vede subito nei test: i servizi si testano senza alcuna UI, gli hook si testano come sottili wrapper e i componenti si testano con l'hook simulato. Livelli puliti = test facili.

Perché funziona

Senza livelli, l'AI genera componenti monolitici, duplica la logica tra i file e produce codice difficile da testare, difficile da mantenere e che si rompe quando scala. Con i livelli, l'AI genera codice mirato per ciascun livello, la logica è centralizzata nei servizi, ogni livello si testa in modo indipendente, e scala fino a milioni di righe.

Ho costruito oltre 3M di righe di codice così. Funziona. Questa è l'esatta architettura dietro FIKR Space: oltre 3M di righe, 964 tabelle di database, 5 prodotti integrati, costruiti con Claude, in produzione. I due errori da evitare: saltare i servizi ("uso direttamente gli hook con il database": la logica di business negli hook è difficile da testare e impossibile da riutilizzare) e i componenti obesi ("metto la validazione nei componenti": non puoi riutilizzarla né testarla senza la UI).

Prima di rilasciare, esegui la checklist: nessun import del database nei componenti, tutta la logica di business nei servizi, i componenti gestiscono solo la UI, gli hook avvolgono i servizi, i servizi sono testabili senza UI, gestione degli errori in tutti i livelli. Questo pattern è il pilastro 2 de i cinque pilastri del software di produzione, e una volta che i livelli esistono, i prompt strutturati come il metodo PRP diventano molto più affidabili, perché ogni prompt ha una casa ovvia.

12 settimaneLa carriera aziendale non è mai stata il pianoCandidati al Solopreneur Accelerator.Candidati ora →

Domande frequenti

Devo capire il codice per usare l'architettura a 3 livelli?

Devi capire la mappa, non le strade. Sapere che UI, logica di business e accesso ai dati sono tre piani separati, e che ogni prompt ne riguarda esattamente uno, basta per dirigere l'AI nel modo giusto. L'architettura è uno strumento di comunicazione tra te e l'AI, e dirigere è la tua metà del lavoro.

3 livelli sono troppi per un piccolo MVP?

No, perché il costo è quasi zero e l'alternativa si accumula. Tre prompt invece di uno al giorno 1 sono minuti di lavoro in più; separare le chiamate al database da cinquanta componenti al sesto mese sono settimane. Il pattern scala verso il basso fino a un progetto da weekend e verso l'alto fino a milioni di righe: l'ho usato a entrambi gli estremi.

Cosa va in un servizio e cosa in un hook?

Le regole vanno nel servizio; l'impianto idraulico nell'hook. Se è una decisione di business (cosa conta come valido, chi è autorizzato, come si calcola un valore) appartiene al servizio. Se riguarda la consegna dei dati allo schermo (cache, flag di caricamento, refetch) appartiene all'hook. Quando hai dubbi, mettilo nel servizio: i servizi sono più facili da testare e riutilizzare.

Come faccio rispettare i livelli all'AI in automatico?

Scrivi la regola nelle istruzioni permanenti del progetto: i componenti non importano mai il client del database, tutto l'accesso ai dati passa dai servizi, gli hook avvolgono i servizi. Poi fai in modo che ogni prompt nomini il suo livello ("crea un metodo di servizio per…"). L'AI segue l'architettura che è davvero scritta, mai quella che hai in testa.