Come costruire una software factory con Claude Code che rilascia funzionalità mentre dormi

Ecco la traduzione in italiano, seguendo tutte le linee guida fornite.

Pensavo di usare l'IA per programmare.

In realtà stavo solo scrivendo più velocemente.

Ecco la differenza — e il sistema a 7 agenti che ha cambiato tutto.

Salva questo. Ti farà risparmiare mesi.

IL PROBLEMA DI CUI NESSUNO PARLA

Il loop che sembra produttivo ma non lo è:

→ Chiedi a Claude di creare una funzionalità → Genera codice → Qualcosa si rompe → Incolli l'errore → Lo corregge → Qualcos'altro si rompe → Chiedi di nuovo

Giorno 1: sembra magia.

Giorno 30: passi più tempo a supervisionare l'IA di quanto ne passassi a scrivere codice.

La stessa logica appare in 3 punti diversi.

Claude si è dimenticato la convenzione che hai impostato due settimane fa.

Le nuove funzionalità rompono quelle vecchie.

I test sono assenti o superficiali.

Ti svegli e realizzi: l'IA non sta fallendo.

È il tuo flusso di lavoro che fallisce.

Il problema reale è strutturale.

Quando scrivi "crea questa funzionalità" in Claude Code, stai chiedendo a una singola sessione IA di essere:

→ Analista di prodotto → Architetto → Sviluppatore backend → Sviluppatore frontend → Ingegnere dei test → Revisore del codice

Tutto insieme.

Nella stessa conversazione confusionaria.

Ipotesi sbagliate nel piano diventano modelli di database sbagliati.

Modelli di database sbagliati diventano API sbagliate.

API sbagliate diventano interfacce utente sbagliate.

Quando te ne accorgi, l'errore si è già diffuso ovunque.

Questo si chiama "vibe coding" (programmare a sensazione).

E ha un tetto massimo ben definito.

IL CAMBIO DI PARADIGMA: DAL VIBE CODING A UNA FABBRICA DI SOFTWARE

Cosa cambia davvero tutto:

I veri team di ingegneria non lavorano in un'unica grande conversazione.

Persone diverse gestiscono compiti diversi:

→ Qualcuno chiarisce il problema dell'utente → Qualcuno pensa all'architettura → Qualcuno costruisce l'API → Qualcuno costruisce l'interfaccia utente → Qualcuno pensa ai casi limite → Qualcuno revisiona

Quando comprimi tutto questo in una singola sessione IA, gli errori si accumulano silenziosamente.

La soluzione è suddividere il lavoro tra agenti specializzati.

Ogni agente riceve: → Un compito specifico → La propria finestra di contesto pulita → Solo gli strumenti di cui ha realmente bisogno → Regole rigide su cosa non può toccare

Il risultato: una fabbrica di software.

Uno sviluppatore + sette agenti focalizzati = un team coordinato.

Ecco i sette agenti che lo fanno funzionare.

I 7 AGENTI

Agente 1: Il Ricercatore del Codebase

L'errore più grande che gli sviluppatori fanno con l'IA?

Chiedere codice come prima mossa.

L'IA accetta il prompt, fa supposizioni per colmare le lacune e inizia a generare.

È così che si insinuano progetti sbagliati.

Il Ricercatore del Codebase risolve questo problema.

Il suo unico compito: ispezionare il codebase e spiegare come funzionano le cose — prima che venga scritta una singola riga di codice.

Cosa fa: → Mappa i file pertinenti e i loro ruoli → Documenta i pattern esistenti da seguire → Trova funzionalità simili già costruite → Segnala i rischi (fusi orari, multi-tenancy, logica di retry) → Elenca quali test dovranno essere aggiornati

Cosa non può fare: → Modificare file (accesso sola lettura) → Eseguire comandi che modificano lo stato → Fare supposizioni — chiede invece

Strumenti: Solo Lettura, Grep, Glob.

La regola: esplora prima di costruire, ogni singola volta.

Il Ricercatore viene eseguito per primo. Sempre.

Agente 2: Lo Scrittore di Storie (User Story)

La maggior parte delle funzionalità fallisce non perché il codice era sbagliato.

Ma perché il problema non è mai stato definito chiaramente.

Lo Scrittore di Storie trasforma un'idea approssimativa di funzionalità in una vera user story prima che vengano prese decisioni tecniche.

Input che riceve: → La tua descrizione approssimativa della funzionalità → I risultati del Ricercatore

Cosa produce:

Una user story:"Come [ruolo], voglio [comportamento], in modo da [risultato]."

Criteri di accettazione:Affermazioni che un test può verificare direttamente. Percorso principale. Percorsi di errore. Regole di business.

Casi limite:Confini, retry, preoccupazioni relative al multi-tenancy.

Fuori ambito:Cosa NON viene esplicitamente costruito.

Domande aperte:Cose che non sa veramente — non fa mai supposizioni.

Cosa non può fare: → Inventare regole di business → Scrivere codice o progetti tecnici → Andare avanti se qualcosa non è chiaro

Strumenti: Solo Lettura.

La regola: leggi questa storia e approvala prima che accada qualsiasi altra cosa.

Questo è il checkpoint umano che salva tutto ciò che viene dopo.

Agente 3: Lo Scrittore di Specifiche Tecniche

Una volta approvata la storia, lo Scrittore di Specifiche la trasforma in un briefing tecnico.

Questo è il progetto che ogni agente di costruzione segue.

Input che riceve: → La tua user story approvata → I risultati del Ricercatore → Le regole CLAUDE.md del tuo progetto

Cosa produce:

→ Modifiche al modello dati (campi, tipi, migrazioni) → Flusso di background / flusso di processo → Modifiche alle API (endpoint, forme richiesta/risposta) → Modifiche al frontend (componenti, pagine, hook) → Test richiesti (successo, fallimento, casi limite) → Rischi e domande aperte → Ogni file che verrà modificato

Cosa non può fare: → Modificare alcun file → Inventare nuova infrastruttura — la segnala esplicitamente invece → Saltare considerazioni sull'isolamento tenant o sui fusi orari → Lasciare domande senza risposta

Strumenti: Solo Lettura, Grep, Glob.

La regola: questo briefing è il secondo checkpoint umano.

Lo leggi e lo approvi prima che un singolo file venga toccato.

Se vedi "memorizza gli ID in memoria" — questa è la tua bandiera rossa.

Catturala ora. Non dopo che 10 file sono stati modificati.

Agente 4: Il Costruttore Backend

Ora inizia la costruzione.

Il Costruttore Backend implementa la parte backend della funzionalità — e solo la parte backend.

Input che riceve: → Briefing tecnico approvato → Risultati del Ricercatore → CLAUDE.md del tuo progetto

Cosa costruisce: → Route API → Servizi e logica di business → Accesso al database e migrazioni → Job in background → Test unitari per tutto ciò che scrive

Cosa non può fare: → Toccare componenti React, pagine o hook lato client (questo è compito dell'Agente 5) → Inventare nuove dipendenze senza istruzioni → Modificare file al di fuori dell'ambito concordato → Fermarsi senza eseguire typecheck, lint e la suite di test

Dopo aver finito, restituisce un riepilogo: → Ogni file aggiunto o modificato → Ogni helper o pattern esistente riutilizzato → Qualsiasi regola CLAUDE.md che sarebbe stata utile

Strumenti: Lettura, Modifica, Scrittura, Bash — limitati alle sole cartelle backend.

La separazione è il punto.

Il Costruttore Backend non può rompere accidentalmente il frontend. Mai.

Agente 5: Il Costruttore Frontend

Il Costruttore Frontend implementa la parte UI — e solo la parte UI.

Legge prima il riepilogo del Costruttore Backend.

Questo è importante.

Consuma l'API esattamente come l'ha prodotta il backend.

Non inventa nuovi endpoint.

Se la forma dell'API non è adatta all'UI, segnala la discrepanza come feedback — non come una toppa.

Input che riceve: → Briefing tecnico approvato → Risultati del Ricercatore → Riepilogo del Costruttore Backend (il contratto API)

Cosa costruisce: → Componenti e pagine React → Hook e stato lato client → Stati di caricamento e di errore → Test dei componenti e unitari per tutto ciò che scrive

Cosa non può fare: → Toccare servizi, route API, worker o migrazioni (questo è compito dell'Agente 4) → Inventare endpoint o forme di risposta → Aggiungere dipendenze senza istruzioni → Fermarsi senza eseguire typecheck, lint e la suite di test

Strumenti: Lettura, Modifica, Scrittura, Bash — limitati alle sole cartelle frontend.

Due costruttori.

Due finestre di contesto pulite.

Zero possibilità che uno rompa il lavoro dell'altro.

Agente 6: Il Verificatore dei Test

Entrambi i costruttori hanno scritto test unitari per il proprio codice.

Questo non basta.

Il Verificatore dei Test fa una sola cosa: dimostrare che la funzionalità fa effettivamente ciò che la user story diceva dovesse fare.

Scrive test di accettazione.

Non test unitari.

Test di accettazione.

Questi testano la funzionalità dall'esterno — nel modo in cui un utente reale la sperimenterebbe.

Input che riceve: → User story approvata (con tutti i criteri di accettazione) → Briefing tecnico approvato → Riepiloghi di entrambi i costruttori

Cosa produce: → Un file di test di accettazione che copre ogni criterio di accettazione → Un rapporto: quali criteri sono stati superati, quali falliti, quali non possono essere coperti adeguatamente

Cosa non può fare: → Modificare alcun codice backend o frontend → Inventare workaround per criteri non testabili → Segnare un criterio come coperto se non lo è veramente

Se un test fallisce: la funzionalità non soddisfa la storia.

Segnala esattamente quale criterio è fallito.

Non modifica il codice.

Questo torna al costruttore giusto.

Strumenti: Lettura, Modifica, Scrittura (solo file di test), Bash.

La regola: non hai una funzionalità finché i test di accettazione non vengono superati.

Agente 7: Il Validatore dell'Implementazione

Questo è l'agente che cattura tutto ciò che tutti gli altri si sono persi.

Il Validatore confronta l'implementazione corrente con la storia e il briefing approvati — e riporta le lacune.

Non aggiusta mai nulla.

Dice solo la verità.

Ogni controllo che esegue, ogni volta:

→ Criteri di accettazione della storia non ancora implementati → Percorsi di errore senza copertura di test → Problemi di sicurezza: controlli di autenticazione mancanti, lacune nell'isolamento tenant, segreti nei log, errori grezzi esposti ai client → File modificati al di fuori dell'ambito concordato → Pattern incoerenti con CLAUDE.md o il codice esistente → Logica duplicata che dovrebbe riutilizzare helper esistenti → Preoccupazioni relative a fusi orari o multi-tenancy dal briefing che sono state tranquillamente saltate

L'output è sempre raggruppato per gravità:

Critico — da risolvere prima del merge Importante — da risolvere preferibilmente prima del merge Minore — basato su opinioni, decisione del revisore

Ogni riscontro include il percorso del file e il numero di riga.

Se non c'è nulla di sbagliato, lo dice chiaramente.

Non inventa problemi per sembrare accurato.

Strumenti: Solo Lettura, Grep, Glob.

Questo agente è il motivo per cui la fabbrica è affidabile.

Un compito auto-corretto è senza valore.

Un validatore che vede solo ciò che è su disco — non come è stato scritto — è onesto.

COME FUNZIONA LA CATENA

Il flusso completo — un prompt dà il via a tutto:

Apri Claude Code e scrivi:

"Crea promemoria fatture per le fatture non pagate da più di 7 giorni."

Ecco cosa succede senza che tu scriva altro:

Passo 1 → Ricercatore mappa il tuo codice per fatture, pagamenti ed email. Restituisce file pertinenti, pattern esistenti, rischi.

Passo 2 → Scrittore di Storie produce la user story e i criteri di accettazione.

⏸ PAUSA: Leggi e approvi la storia.

Passo 3 → Scrittore di Specifiche trasforma la storia approvata in un briefing tecnico.

⏸ PAUSA: Leggi e approvi il briefing.(Cattura quell'errore "memorizza gli ID in memoria" proprio qui.)

Passo 4 → Costruttore Backend implementa il servizio, la route API, il job BullMQ e i test unitari. Restituisce: file modificati, pattern riutilizzati, tutti i test verdi.

Passo 5 → Costruttore Frontend legge il riepilogo API del Costruttore Backend, costruisce il tile dell'interfaccia di amministrazione e il pulsante di promemoria, scrive i test dei componenti. Tutti i test verdi.

Passo 6 → Verificatore dei Test scrive test di accettazione per tutti e sei i criteri di accettazione. Rapporto: 7 superati, 1 fallito — il trigger manuale non controlla la proprietà del tenant.

Passo 7 → Validatore lo trova. Lo segnala come Critico con percorso file e numero di riga.

→ Ciclo di ritorno al Costruttore Backend. Correzione applicata. Tutti gli 8 test di accettazione superati. Validatore eseguito di nuovo. Pulito.

⏸ PAUSA: Revisioni e apri la PR.

Tre checkpoint umani.

Tutto il resto funziona da solo.

LE FONDAMENTA: PRIMA CHE GLI AGENTI FUNZIONINO, SERVE QUESTO

CLAUDE.md — la memoria che sopravvive a ogni sessione:

Ogni volta che apri Claude Code, parte con memoria zero.

CLAUDE.md risolve questo problema.

È un file Markdown nella root del tuo repository che viene caricato automaticamente a ogni sessione.

Qui vivono i fatti permanenti del progetto:

→ Il tuo stack (Next.js App Router, Node.js, Prisma, BullMQ, Resend) → I tuoi comandi (npm run dev, npm test, npx prisma migrate dev) → Regole di architettura ("La logica di business vive nei servizi. Le route API rimangono snelle.") → Cosa non fare ("Non aggiungere cron — usa BullMQ. Non loggare i payload di pagamento grezzi.") → Puntatori a documentazione più approfondita (docs/billing.md, docs/architecture.md)

Mantienilo tra 100 e 300 righe.

Ogni volta che l'IA commette un errore che ti sorprende, chiediti: una regola in CLAUDE.md avrebbe prevenuto questo?

Aggiungi la regola.

In poche settimane, il tuo CLAUDE.md diventa una registrazione di ogni supposizione sbagliata dell'IA — e le tue sessioni miglioreranno notevolmente.

La deriva del contesto — il killer silenzioso:

La maggior parte delle sessioni di Claude Code non fallisce in modo drammatico.

Derivano.

Un'ipotesi sbagliata entra nel contesto.

Il modello continua a costruirci sopra.

Chiedi a Claude di creare la gestione degli abbonamenti.

Lui progetta: Utente → Abbonamento.

Tu ricordi: gli abbonamenti appartengono all'azienda, non all'utente.

Se dici solo "no, gli abbonamenti appartengono alle aziende" — Claude applica una toppa.

Ora hai sia user.subscriptionId che company.subscriptionId sparsi in giro.

Regola:

→ Piccolo refuso? Correggilo direttamente. → Ipotesi architetturale sbagliata? Butta via la conversazione e ricomincia da capo con l'ipotesi corretta integrata nel primo prompt.

Una sessione pulita con il modello mentale giusto batte una sessione rattoppata ogni volta.

I RISULTATI: COSA CAMBIA REALMENTE

Prima della fabbrica:

→ Loop del vibe coding: prompt → genera → errore → toppa → ripeti → Il contesto della sessione si riempie di rumore → Le ipotesi sbagliate si accumulano in funzionalità rotte → Un ingegnere può fare solo una cosa alla volta → Ogni funzionalità aspetta che la persona giusta sia disponibile

Dopo la fabbrica:

→ Catena strutturata: ricerca → storia → briefing → costruisci → verifica → convalida → Ogni agente riceve una finestra di contesto pulita con solo ciò di cui ha bisogno → Le ipotesi sbagliate vengono catturate all'approvazione del briefing — non dopo 10 file → Un ingegnere rilascia una fetta verticale completa: backend, frontend, test, convalida → La migliore conoscenza del team vive negli agenti — non intrappolata nelle persone

Il vero cambiamento:

Lo specialista dei pagamenti costruisce un agente per l'integrazione dei pagamenti.

Ora ogni ingegnere del team può rilasciare una funzionalità che tocca la fatturazione.

Senza aspettare.

Senza passaggio di consegne.

I pattern dei componenti del lead frontend vivono nell'agente costruttore frontend.

I controlli CI dell'ingegnere DevOps vivono in un hook.

I casi limite del lead QA vivono nelle regole del verificatore dei test.

Conoscenza esperta, condivisa come agenti.

Non intrappolata nella disponibilità.

COME COSTRUIRE IL TUO QUESTO WEEKEND

Checklist di configurazione in 8 passi:

1. Installa Claude Code → code.claude.com

2. Crea la struttura delle cartelle: → .claude/agents/ → .claude/skills/feature-factory/ → .claude/skills/build-with-tests/ → .claude/hooks/

3. Scrivi il tuo CLAUDE.md (100–300 righe: stack, comandi, regole di architettura, lista delle cose da non fare)

4. Crea i 7 agenti usando il comando /agents in Claude Code. Descrivi il ruolo di ogni agente. Claude scrive il file. Tu lo revisioni e lo fai commit.

5. Crea la skill orchestratrice della fabbrica di funzionalità (feature-factory). Chiedi a Claude di scriverla — legge i tuoi 7 file degli agenti e collega la catena.

6. Crea la skill build-with-tests. Descrive come il tuo team costruisce: abbina i pattern esistenti, scrivi i test insieme al codice, esegui typecheck alla fine.

7. Aggiungi un hook pre-commit. Blocca i commit che includono file .env, .key, .pem o secrets.json. Richiede 5 minuti. Previene disastri.

8. Esegui una funzionalità reale attraverso l'intera catena. Scegli qualcosa di piccolo. Osserva dove inciampa. Aggiungi regole. La fabbrica si sintonizza da sola.

Tempo totale: 2–3 ore.

Poi lancia qualche funzionalità.

Dopo 3-4, la fabbrica conosce il tuo codebase.

Passerai meno tempo a supervisionare.

Più tempo a decidere cosa costruire dopo.

I 7 AGENTI — RIFERIMENTO VELOCE

→ Ricercatore — mappa il codice prima che venga costruito qualsiasi cosa (Sola Lettura) → Scrittore di Storie — trasforma un'idea in user story con criteri di accettazione (Sola Lettura) → Scrittore di Specifiche — trasforma la storia in briefing tecnico (Sola Lettura) → Costruttore Backend — costruisce API, servizi, job, test unitari (solo cartelle backend) → Costruttore Frontend — costruisce componenti, pagine, hook, test UI (solo cartelle frontend) → Verificatore dei Test — scrive test di accettazione basati sulla user story (solo file di test) → Validatore — confronta l'implementazione con la storia e il briefing, riporta le lacune (Sola Lettura)

3 checkpoint umani:→ Approva la storia → Approva il briefing → Approva la PR

Tutto il resto funziona da solo.

La maggior parte degli sviluppatori che usa Claude Code sta ancora facendo vibe coding.

Prompt → generare → rattoppare → sperare.

Non è sbagliato.

È solo un tetto.

La fabbrica non ti rimuove dal processo.

Ti rimuove dalle parti che non hanno bisogno di te.

Rimani nel loop dove il tuo giudizio conta:

Questo è il problema giusto? Questo è il progetto giusto? È sicuro da rilasciare?

Gli agenti gestiscono tutto il resto.

Questa è la differenza tra usare l'IA come una tastiera più veloce —

e usare l'IA come un team coordinato.

Se questo è stato utile:

→ Ripubblica per condividerlo con la tua rete → Segui @sairahul1 per altri approfondimenti come questo → Metti un segnalibro — ti servirà per fare riferimento ai 7 agenti

Scrivo di IA, creazione di prodotti e sistemi che funzionano mentre tu dormi.