Urazuke — il corso. Manuale con compiti pratici, gradino per gradino, fino all'applicazione in produzione

Autore: Pablo Kuschniroff, assistito da Claude Code. Versione 2, 18 ottobre 2026. È un documento di lavoro del progetto Urazuke: lo correggerò con la prima coorte che lo userà. Questa è la versione italiana; lo spagnolo è la fonte della verità. È scritto in linguaggio di tutti i giorni, e ogni sigla o espressione strana sta nel glossario del documento principale (ESCALERA_METODOLOGICA.md). Quando cito un caso reale lo faccio con un segno [Ref. N] che porta al documento delle referenze; il manuale resta pulito e il dettaglio, a un clic. Il repository pubblico del metodo è github.com/pkuschnirof/urazuke.

Prima di cominciare

Per chi è questo corso

Per chi vuole costruire software con l'intelligenza artificiale e vuole che quel software venga usato davvero, da gente vera, per mesi. Non è un corso di programmazione: non imparerai un linguaggio né un framework. Non è nemmeno un corso di "prompt": non imparerai trucchi perché il modello scriva meglio. È un corso di metodo: cosa fare in che ordine, cosa chiedere al modello in ogni momento, cosa deve consegnarti, e come sapere — senza leggere codice — che ciò che ti ha consegnato è completo.

Ti serve se sei una di queste persone:

• Hai un'attività, uno studio, una piccola società di consulenza, e vuoi il tuo sistema senza assumere un team di sviluppo.
• Sei un consulente o un freelance dell'automazione e i tuoi clienti ti chiedono "qualcosa di più" di un robot.
• Sai programmare, ma vuoi che il modello faccia il lavoro pesante e tenerti le decisioni.
• Hai già "vibecodato" qualcosa, ha funzionato due settimane, e al mese tre ti è crollato.

Non ti serve se ciò che vuoi è un prototipo per la demo di venerdì. Per quello ci sono strumenti più rapidi, e questo metodo ti sembrerà lento. Il metodo è per ciò che deve continuare a funzionare dopo la demo.

Cosa avrai alla fine

Un'applicazione tua, in produzione, con: test che si sono visti fallire prima di passare; prove end to end di tutti i flussi; deployment riproducibile con rollback; configurazione e segreti fuori dal repository; le decisioni di business scritte con la data; un albero semantico del sistema e la specifica dettagliata di ogni cosa costruita, nelle sue voci in sospeso; lucchetti su tutto ciò che addebita, invia o cancella; tre manuali che una persona può seguire senza IA; un audit fatto da un agente diverso da quello che ha costruito; e una retrospettiva con i numeri. Questo è ciò che qui chiamo "production grade": non è che funzioni, è che si può sostenere.

E avrai qualcos'altro, che è ciò che davvero ti porti a casa: il riflesso di non credere al modello senza prove, e di sapere esattamente quale prova chiedergli a ogni passo.

Di cosa hai bisogno

1. Uno strumento di IA per programmare. Uno qualunque che possa leggere e scrivere file nel tuo repository ed eseguire comandi: Claude Code, Cursor, Codex CLI, Gemini CLI, Forge. Il metodo non dipende da quale; il documento principale ha una tabella di dove va ogni artefatto in ogni strumento. In questo manuale dico "l'agente" per riferirmi a quello che usi.
2. Un account su GitHub (o equivalente) e nozioni minime di cos'è un repository, un commit e un push. Se non le hai, dedicaci un pomeriggio prima di cominciare; qualunque tutorial introduttivo basta. Non serve altro.
3. Un progetto. L'ideale è che sia tuo: un sistema di cui hai bisogno o che un cliente ti ha chiesto, con utenti che lo useranno. Se non ne hai uno, usa il progetto guida che descrivo sotto; è pensato per passare per i ventiquattro gradini senza saltarne nessuno. Se ciò che hai è un sistema che esiste già e bisogna correggere o far crescere, questa prima parte ti insegna il metodo su un progetto nuovo, e la parte 2 del corso ti insegna a normalizzarlo prima, con un secondo progetto guida ereditato.
4. Tempo. Il corso ha ventiquattro lezioni, una per gradino, e un ordine che ti dice in quale tappa cade ogni cosa (vedi "L'ordine del corso"). Non ti do scadenze, di proposito: il metodo è un processo, non una promessa di velocità, e quanto dura ogni tappa lo mette la dimensione del tuo progetto. Quello che ti do è l'ordine, e quello non si negozia.
5. Un proprietario del dominio con tempo per decidere. Se il progetto è tuo, sei tu. Se è di un cliente, è il cliente, e deve sapere che dovrà rispondere a domande per tutto il progetto. Questo punto non è negoziabile: senza un proprietario che decida, decide il modello, e lì il metodo si rompe.

Come si segue il corso

Ogni lezione ha la stessa struttura:

• Cosa devi capire: il concetto, spiegato come si spiega a una persona.
• Il compito: passo per passo, con il prompt esatto che darai all'agente (in inglese, perché i modelli seguono le istruzioni con più precisione in inglese; ciascuno ha la sua traduzione, e sotto è spiegato cosa gli stai chiedendo) e cosa fare con ciò che ti restituisce. Prima di ogni prompt c'è un blocco che dice "Prima di inviare il prompt": i file e gli input che devi aver fatto tu, con le tue mani, prima di incollarlo. Non saltarlo: il prompt nomina quei file, e se non esistono o sono vuoti, l'agente se li inventerà o te li chiederà.
• La verifica di completezza: la lista di domande che ti fai su ciò che l'agente ha consegnato, senza aprire il codice. Se una dà "no", la lezione non è finita.
• La consegna: il file o la prova che deve esistere alla fine.
• Errori tipici: ciò che succede a quasi tutti la prima volta.
• Nel progetto guida: come si vede questa lezione applicata al progetto di esempio.

Una regola per tutto il corso: non avanzare al gradino successivo con una verifica in "no". La tentazione del "dopo lo sistemo" è esattamente ciò che il metodo esiste per evitare. Se un gradino non si sale completo, quello successivo si costruisce sulla sabbia.

L'ordine del corso: quando si fa ogni cosa

Il documento principale ha, nella sua Parte B, la linea del tempo completa del metodo. Qui la traduco nell'ordine del corso per il progetto guida. Sono tappe, non settimane: ciascuna dura quanto il tuo progetto chiede, e ciò che non è negoziabile è l'ordine e, soprattutto, cosa succede tra una lezione e l'altra.

Se il tuo progetto è più grande, ciò che cresce sono le tappe 2 e 3 (più blocchi), non la 1 né la 4 e la 5. E se a un certo punto ti ritrovi a fare infrastruttura nella tappa 3, o a eseguire la batteria end to end per la prima volta nella tappa 5, torna all'ordine: qualcosa è stato saltato.

Il progetto guida: "Turnera"

Se non hai un progetto tuo, usa questo. È piccolo, ma ha tutto ciò che serve perché nessuno dei ventiquattro gradini sia per finta: utenti reali, dati personali, messaggi che escono nel mondo, e soldi.

L'attività. Un ambulatorio (può essere uno studio, un parrucchiere, un'officina: qualunque posto che dà appuntamenti). Oggi gli appuntamenti si annotano su un quaderno e si confermano via WhatsApp a mano. Si perdono appuntamenti perché la gente si dimentica, ci sono doppi appuntamenti perché due persone hanno annotato su quaderni diversi, e nessuno sa quanti appuntamenti sono stati cancellati il mese scorso.

Cosa vogliono. Un'agenda web dove le due receptionist e i tre professionisti vedano gli appuntamenti; promemoria automatici 24 ore prima, via WhatsApp o email; la possibilità di chiedere una caparra tramite link di pagamento per certi appuntamenti; e un paio di numeri a fine mese (quanti appuntamenti, quante assenze, quante caparre).

Il proprietario. La responsabile dell'ambulatorio. Ha criterio sull'attività (sa quali appuntamenti richiedono caparra, con quanto anticipo si può cancellare, cosa si dice a un paziente che è mancato tre volte) e ha quindici minuti al giorno per rispondere a domande. Non programma, e non leggerà codice.

I numeri che solo lei conosce. Circa quaranta appuntamenti al giorno, duecentocinquanta giorni all'anno. Circa tre messaggi per appuntamento (conferma, promemoria, a volte riprogrammazione). I dati dei pazienti si conservano cinque anni. Il picco è il lunedì mattina, con le due receptionist che caricano contemporaneamente. E una domanda a cui lei non sa rispondere e che conta: se questo funziona, lo venderanno ad altri ambulatori? (La risposta cambia il dimensionamento di dieci volte.)

Ciò che ha conseguenze. Inviare un promemoria (se si manda due volte, dà fastidio; se si manda al numero sbagliato, è un problema di privacy). Addebitare una caparra (soldi). Cancellare un appuntamento (irreversibile per il paziente che lo perde). Cancellare un paziente (dati personali).

I casi d'uso che nomina la responsabile, così come li dice lei: "carico un appuntamento", "cerco un paziente", "cancello un appuntamento", "al paziente arriva il promemoria", "gli chiedo la caparra", "vedo quanti appuntamenti ci sono stati questo mese". Sono sei; saranno i flussi end to end.

Con questo basta per cominciare. Tutto il resto lo chiederà l'agente, ed è parte dell'esercizio che lo chieda.

Fase di avvio: lezioni da 0 a 4

Queste cinque lezioni si fanno una volta per progetto, nella tappa 1, prima di scrivere funzionalità. Sono quelle che danno più tentazione di saltare ("voglio vedere qualcosa che funziona"), e sono quelle che costa più caro saltare. Falle di seguito, e solo dopo apri il ciclo.

Lezione 0 — Questo progetto si può affrontare così?

Cosa devi capire. Il metodo non serve per qualunque progetto, e saperlo prima di cominciare è la prima decisione di qualità. Ci sono due condizioni senza le quali non funziona: che ci sia un repository standard dove lasciare la prova (X1), e che le schermate si possano operare da programma per provare end to end, dalla schermata fino al backend (X2). Se una qualsiasi delle due manca, l'agente non potrà verificarsi da solo, e allora finirai per leggere codice tu, che è proprio ciò che il metodo promette di evitare. Entrambe le ho tratte da progetti che ho rifiutato Ref. 46. Poi ci sono criteri che pesano (se c'è un proprietario con tempo, se l'errore ha conseguenze, se si può provare in un ambiente a parte, ecc.), che sto ancora calibrando.

Per il progetto guida le due condizioni sono soddisfatte: è un progetto nuovo (non c'è legacy) e lo costruiremo con un'interfaccia web operabile da programma. Per un progetto tuo, questa lezione può finire in "non va", e quello è un risultato valido del corso.

Il compito.

1. Incollagli questo prompt:

Gli stai chiedendo di leggere i due file, di valutare se la rilevazione basta e di chiedere ciò che manca prima di rispondere (questa clausola si ripete in tutti i prompt del corso; è il cuore del metodo), di compilare la scheda dicendo da dove viene ogni risposta, e di non decidere: la decisione è tua.

2. Rispondi alle sue domande. Se non te ne ha fatta nessuna, diffida e chiedigli cosa ha supposto.
3. Quando ti presenta la scheda, leggila e decidi.

4. Incollagli il prompt di chiusura:

Verifica di completezza. Apri docs/ELIGIBILITY.md e chiediti: i due escludenti hanno una risposta esplicita e una fonte? C'è qualche criterio a cui si è risposto con "probabilmente"? (Se c'è, l'agente doveva chiedere.) La decisione ha data e nome? Le condizioni, se ci sono, si possono verificare? Ci sono le domande che ha fatto e le tue risposte?

Consegna. docs/ELIGIBILITY.md, di una pagina.

Errori tipici. Scrivere la rilevazione "completa" perché l'agente non chieda: ti perdi l'esercizio e, peggio, ti abitui a fare il lavoro del modello. Rispondere "va" con cinque condizioni: è un "non va" travestito. E il più comune: saltare la lezione perché "è ovvio che va". L'ovvio è ciò che non si scrive, e ciò che non si scrive è ciò su cui poi si discute.

Nel progetto guida. L'agente dovrebbe chiedere, come minimo, se l'interfaccia sarà web o mobile (perché X2 dipende da questo), se c'è un sistema precedente anche solo un Excel, e quale canale di messaggi si userà (WhatsApp ha requisiti che l'email non ha). La scheda finisce in "va", con una condizione ragionevole: avere il canale di messaggi definito prima del gradino 14.

Lezione 1 — Il patto di convivenza

Cosa devi capire. L'agente arriva a ogni sessione senza memoria della precedente. È come un collaboratore nuovo ogni mattina. Il patto di convivenza è ciò che gli dici il primo giorno e ciò che rileggerà tutti i giorni: come lavori, cosa non tolleri, che livello di autonomia gli dai. Senza patto, gli ripeterai le stesse cose a ogni sessione, e ogni volta un po' diverse. Io l'ho scritto per la prima volta dopo due settimane passate a ripetermi Ref. 1.

Le sei regole minime hanno ciascuna un fallimento alle spalle: "il mio tempo è sacro" evita che ti consulti per ogni dettaglio; "zero debito" evita il "dopo lo sistemo"; "perimetro esatto" evita che "già che c'è" ti aggiunga cose; "documentazione nello stesso commit" evita i manuali vecchi; "mai riportare come fatto ciò che non è verificato" evita il "fatto" che non lo era; "parla la mia lingua" evita che ti risponda in inglese perché il prompt era in inglese.

Il compito.

1. Incollagli questo prompt:

Gli stai chiedendo le sei regole con il fallimento che ciascuna evita, regole proprie segnate come proposte perché tu le accetti o le respinga, e che ti faccia domande su di te.

2. Rispondi alle sue domande. Leggi le proposte: accetta quelle che ti servono, respingi quelle che no, sempre con una ragione di una riga.

3. Chiudi con:

Se non c'è ancora un file di progetto (lo fai nella lezione 2), ne creerà uno minimo con quell'istruzione; va bene.

Verifica di completezza. Ci sono le sei regole, ciascuna con il fallimento che evita? Ce n'è qualcuna scritta come aspirazione ("cercare di…")? Il file di progetto ordina di leggerlo all'inizio di ogni sessione? Ti ha fatto almeno una domanda su come lavori?

Consegna. docs/WORKING_AGREEMENT.md con data e versione, agganciato al file di progetto.

Errori tipici. Accettare venti regole perché suonano tutte bene: nessuno ne rispetta venti; sei o otto si rispettano. Lasciare una regola che dica che l'agente può cambiare il patto: no. E il più silenzioso: non provare mai se lo legge. Nella lezione 2 vedrai come.

Nel progetto guida. Una regola propria che l'agente di solito propone per Turnera, e che vale la pena accettare: "non mando mai un messaggio reale a un paziente da un ambiente che non sia la produzione; in test, i messaggi vanno in una casella finta". È il gradino 14 che si affaccia presto.

Lezione 2 — La definizione del progetto, l'albero semantico e la lettura obbligatoria

Cosa devi capire. Il file di progetto (PROJECT.md, o CLAUDE.md, o il nome che usa il tuo strumento) è la mappa che l'agente legge all'inizio di ogni sessione. Deve essere corto: cos'è il sistema, per chi, cosa NON è, i moduli, le decisioni prese con la data, e l'ordine di leggere il patto. Ciò che è successo ogni giorno non va lì: va nello stato vivo (docs/STATUS.md) e nel registro delle voci in sospeso. Uno dei miei sistemi ha lasciato crescere questo file fino a più di novemila righe; in quello stato, non lo legge nessuno, e nemmeno il modello Ref. 41.

Ma la mappa ha un secondo pezzo, ed è quello che fa più lavoro: l'albero semantico. È il sistema scomposto come un albero: i domini al primo livello, e sotto ciascuno i suoi attori, i suoi processi (i casi d'uso che hai nominato nell'acquisizione, con attore, innesco, passi, risultato ed eccezioni), le sue entità con i loro attributi e i loro stati, le sue schermate e le sue integrazioni esterne. È il modello di dominio dell'ingegneria dei requisiti di sempre, messo in forma di albero perché il modello lo legga. Da ogni nodo penderanno le voci in sospeso e le decisioni che lo toccano. Il suo valore è doppio: dà all'agente il contesto esatto del nodo che toccherà, e dà a te un modo per verificare, senza leggere codice, che il sistema che l'agente capisce è quello che il business ha chiesto. Se l'albero ha uno stato che il business non ha mai nominato, il modello l'ha inventato, e lo vedrai prima che ci costruisca sopra.

La sezione "cosa NON è" resta la più importante e quella che tutti lasciano vuota. Ciò che non è scritto è ciò che il modello inventerà quando si troverà davanti a un buco.

Il compito.

1. Incollagli:

Gli stai chiedendo di chiedere prima di redigere, un file di progetto corto con la sezione "cosa non è", l'albero semantico con la sua struttura completa e con i nodi inferiti segnati, e lo stato vivo in un altro file.

2. Leggi PROJECT.md per intero. Deve starci in cinque minuti. Correggi ciò che non è vero o non è tuo.
3. Percorri l'albero semantico come se fossi il cliente. Guarda ogni nodo segnato come inferito e confermalo o correggilo. Cerca attori che mancano, stati di entità che il business non usa, schermate che non hai chiesto.

4. Chiudi con:

5. La prova di lettura. Chiudi la sessione dell'agente e aprine una nuova. Senza dirgli altro, chiedigli: "Cosa non deve fare questo sistema? E da quale nodo dell'albero pende la schermata dell'agenda?". Se ti risponde con ciò che dicono PROJECT.md e l'albero, l'aggancio funziona. Se ti risponde qualunque altra cosa, non sta leggendo la mappa: controlla come il tuo strumento carica il file di progetto.

Verifica di completezza. PROJECT.md si legge in cinque minuti? Dice cosa NON fa il sistema? L'albero ha tutti gli attori che tu conosci, e ogni entità ha gli stati che il business usa, né più né meno? Hai confermato o corretto tutti i nodi inferiti? Ogni decisione ha la data e chi l'ha presa? L'agente ha chiesto qualcosa prima di redigere? Lo stato vivo è in un altro file? Ha superato la prova di lettura?

Consegna. PROJECT.md (massimo trecento righe), docs/SEMANTIC_TREE.md con i nodi confermati, docs/STATUS.md, e la prova di lettura superata.

Errori tipici. Incollare in PROJECT.md tutta la specifica che già avevi: è il programma, non la specifica. Lasciare "cosa non è" vuoto. Accettare l'albero senza percorrerlo: il modello inferisce stati e schermate con una naturalezza che fa paura, e ogni nodo inventato è funzionalità che costruirà senza che nessuno gliel'abbia chiesta. E non fare la prova di lettura: è l'unico modo per sapere che il gradino 1 e il 2 stanno agendo e non solo esistendo.

Nel progetto guida. In "cosa NON è" di Turnera dovrebbero esserci, come minimo: non è un sistema di cartella clinica (non conserva dati medici), non è un gateway di pagamento (usa un link di pagamento di un fornitore, non elabora carte), e non manda messaggi di marketing (solo conferme e promemoria). L'albero ha un dominio "Agenda" con gli attori receptionist e professionista, i processi "caricare appuntamento", "cancellare appuntamento" e "cercare paziente", le entità Appuntamento (con stati in attesa, confermato, cancellato, assente) e Paziente, e le schermate "agenda del giorno" e "scheda del paziente"; un dominio "Messaggi" con il processo "inviare promemoria", l'entità Messaggio e l'integrazione con il fornitore di WhatsApp; e un dominio "Pagamenti" con "chiedere caparra" e l'integrazione con il fornitore di pagamenti. Se l'agente ti aggiunge uno stato "riprogrammato" all'appuntamento, chiedigli da dove l'ha preso: la responsabile non l'ha nominato. Forse serve, forse no; lo decidi tu, non lui.

Lezione 3 — Dimensionare prima di progettare l'architettura

Cosa devi capire. Ci sono decisioni che, prese male, costano settimane: quale database, se le chiamate al database sono sincrone o asincrone, quante persone possono usare il sistema contemporaneamente. E tutte dipendono da numeri che solo il business ha: quanti appuntamenti al giorno, quanti messaggi per appuntamento, quanti anni si conserva. Il modello non può inferire quei numeri; può inferire ciò che ne deriva (righe all'anno, dimensione a cinque anni). Per questo il prompt gli impone di distinguere dati primari da derivati, e di chiedere i primari che mancano invece di stimarli. Quando il modello stima un dato primario, lo fa con la stessa faccia sicura di quando calcola; e non hai modo di distinguerli dal tono. A me non averlo fatto in tempo è costato un'intera tappa di reingegnerizzazione Ref. 15.

C'è inoltre un tipo di decisione che conviene prendere sempre: le asimmetriche, economiche se avanzano e carissime se mancano. L'esempio canonico è fare l'interfaccia con il database asincrona dal primo giorno anche se il primo database è un file: se non cambi mai database, è avanzato un await; se cambi, ti sei risparmiato di riscrivere tutto.

Il compito.

1. Incollagli:

Gli stai chiedendo: distinguere primari da derivati; chiederti i primari che mancano o sono in "supposto", e non stimarli mai; calcolare il derivato con il conto in vista; lo scenario "per dieci"; tre opzioni con il costo di passare dall'una all'altra; e che non scelga.

2. Se ti chiede i "supposti", bene: quello era l'esercizio. Procurati i numeri (chiedi al proprietario, conta nel quaderno) e daglieli. Se non te li ha chiesti e ha calcolato lo stesso, fermati e chiedigli cosa ha fatto con i supposti: è un fallimento del gradino e conviene vederlo ora.
3. Leggi le tre opzioni. Rifai un conto a mano (per esempio, righe all'anno della tabella più grande): deve darti lo stesso. Scegli.

4. Chiudi con:

Verifica di completezza. C'è qualche dato primario con fonte "supposto" o senza fonte? Ogni dato derivato mostra il conto, e ti torna se lo rifai? Ci sono tre opzioni e una scelta con una ragione? Dice cosa succede "per dieci"? Le decisioni asimmetriche sono scritte? Ti ha fatto domande?

Consegna. docs/SIZING.md.

Errori tipici. Completare la rilevazione con numeri inventati da te perché l'agente non chieda (è lo stesso errore della lezione 0, ed è peggio qui perché quei numeri decidono l'architettura). Scegliere l'opzione "più potente" per sicurezza: il costo di migrare sta nella tabella proprio perché tu scelga la più piccola che regga il "per dieci". E non scrivere le decisioni asimmetriche: se non sono scritte, nella lezione 4 l'agente non le rispetterà.

Nel progetto guida. Primari: 40 appuntamenti/giorno × 250 giorni = 10.000 appuntamenti/anno; 3 messaggi per appuntamento = 30.000 messaggi/anno; 5 anni di conservazione; picco di due receptionist simultanee. Il "per dieci" è la domanda se si vende ad altri ambulatori: 100.000 appuntamenti e 300.000 messaggi all'anno. Le tre opzioni tipiche: un file SQLite (basta per un ambulatorio per anni, non regge il per dieci con più persone che scrivono), PostgreSQL fin dall'inizio (regge tutto, costa un po' più di infrastruttura), o SQLite adesso con l'interfaccia asincrona e una migrazione prevista a PostgreSQL (l'asimmetrica). Per il corso scegliamo la terza: è quella che insegna di più.

Lezione 4 — Lo scheletro con i suoi cancelli

Cosa devi capire. Prima che il sistema faccia qualcosa di utile, deve partire, provarsi e distribuirsi vuoto. Sembra una perdita di tempo ("distribuire cosa, se non c'è niente?") ed è il contrario: il cammino verso la produzione è parte del prodotto, e l'unico modo per sapere che funziona è percorrerlo quando ancora non c'è niente da perdere. In uno dei miei sistemi il deployment è arrivato un mese dopo l'avvio ed è costato cinque voci in sospeso di seguito Ref. 32; con lo scheletro distribuito nell'avvio, quei cinque colpi si sarebbero presi a vuoto.

Questa lezione è, inoltre, dove si fa tutta l'infrastruttura e la catena di integrazione e deployment del progetto. Non la toccherai più fino alla lezione 15, e nel frattempo costruirai tutta la funzionalità sopra di essa. Per questo occupa la maggior parte della tappa 1.

I cancelli sono le condizioni per passare da una tappa all'altra ("la batteria è in verde", "il deployment in test ha funzionato"). Scriverli adesso, anche se sembrano ovvi, è ciò che poi permette di dire "questo non passa" senza discutere.

Il compito.

1. Incollagli:

Gli stai chiedendo di verificare gli accessi prima di cominciare, la lista esatta di ciò che è uno scheletro, i cancelli scritti, uno screenshot reale dell'ambiente di test, e il divieto di aggiungere funzionalità.

2. Questo compito è lungo e avrà andirivieni: credenziali che mancano, un servizio che chiede di confermare l'email, ecc. È normale. Ciò che non è normale è che ti dica "fatto" senza lo screenshot dell'ambiente di test.
3. Quando ti mostra lo screenshot, apri tu l'URL nel tuo browser. Si deve vedere la stessa cosa. È il primo sguardo umano sul sistema, ed è una pietra miliare.

4. Chiudi con:

Verifica di completezza. Hai aperto tu l'URL dell'ambiente di test e visto la schermata vuota? C'è un link a un'esecuzione di integrazione continua in verde? Il deployment è stato eseguito due volte e la seconda non ha rotto nulla? I cancelli hanno ciascuno una condizione verificabile? C'è qualche funzionalità che non hai chiesto?

Consegna. Il repository con lo scheletro, l'integrazione continua in verde, l'URL dell'ambiente di test funzionante, docs/GATES.md, e docs/STATUS.md con i tre comandi.

Errori tipici. Accettare "funziona in locale, il deployment lo vediamo dopo": no, il deployment è lo scheletro. Accettare uno screenshot della macchina dell'agente invece dell'ambiente di test. E lasciare che "già che c'è" ti aggiunga una schermata di login, un menu, un logo: ogni cosa che entra senza voce in sospeso è perimetro che è scappato.

Nel progetto guida. Lo scheletro di Turnera è una pagina web che dice "Turnera — versione 0.0.1" che gira su un URL pubblico di un ambiente di test, un server che risponde "ok" su una rotta di salute, un test di fumo che chiama quella rotta, l'integrazione continua che esegue quel test a ogni push, e il deployment automatico nell'ambiente di test. I cancelli: "batteria in verde per fondere", "ambiente di test in verde per promuovere in produzione", "rollback provato per il primo deployment in produzione". Niente di più. Ed è strano quanto sia soddisfacente vedere quella pagina vuota su un URL reale.

Fase del ciclo: lezioni da 5 a 12

Queste otto lezioni sono quelle che userai a ogni modifica, per tutto il progetto. Si imparano nelle tappe 2 e 3 sui primi due blocchi funzionali, e si praticano fino alla fine. Vanno nell'ordine in cui si fanno con ogni voce in sospeso: aprire un blocco convertendo la richiesta in voci in sospeso specificate, prenderne una, decidere ciò che manca, misurare ciò che c'è da misurare, costruire, provare in rosso e end to end, passare il cancello di qualità, scrivere i casi di prova manuale, aggiornare l'altro lato, e riportare separando il verificato dal creduto. Alla chiusura del blocco, eseguire i casi di prova manuale tu stesso. Quel riflesso è il metodo.

Per praticarle avrai bisogno di funzionalità reale. Nel progetto guida, il primo blocco è l'agenda di base: vedere gli appuntamenti del giorno, caricare un appuntamento, cancellarlo. Il secondo, pazienti e ricerca. Niente messaggi né pagamenti ancora; quello viene dopo i lucchetti (lezione 14).

Lezione 5 — Il piano sono le voci in sospeso, e la specifica dettagliata vive in ciascuna

Cosa devi capire. Non c'è un "piano" da una parte e una "lista di compiti" dall'altra: la lista delle voci in sospeso è il piano. Ma ci sono altre due idee, e sono quelle che distinguono questo metodo da una lista di cose da fare qualunque.

La prima: la specifica dettagliata vive in ogni voce in sospeso. Nel metodo classico c'era un documento di specifica dei requisiti, lungo, che invecchiava prima di essere finito. Qui si scompone: ogni voce porta il nodo dell'albero semantico da cui pende, la storia utente o il caso d'uso che la origina con le parole del cliente, la descrizione dettagliata, le regole di business applicabili con la loro decisione e la loro data, i dati che entrano ed escono, le schermate coinvolte, i casi limite, i criteri di accettazione nella forma "dato, quando, allora", e come si verifica. Leggere la specifica di una voce in sospeso è il punto più vicino a leggere codice a cui arriverai, ed è esattamente la distanza giusta: è lì che tu ti accorgi che l'agente ha capito un'altra cosa, prima che costruisca.

La seconda: le voci in sospeso chiuse sono documentazione. Quando una voce si chiude, resta con la sua specifica, la decisione che l'ha originata, la prova con cui è stata chiusa, il commit e la data. La coda delle voci chiuse è lo storico funzionale del sistema, e da lì escono il diario delle modifiche e le sezioni nuove del manuale. E la regola d'oro per l'agente: ciò che compare fuori dalla lista si annota come voce nuova, con la sua specifica, non si fa.

Il compito.

1. Incollagli:

Gli stai chiedendo di convertire la richiesta in voci verificabili, di chiedere quando la richiesta non permette di scriverne una verificabile, la specifica completa di ciascuna campo per campo, il nodo dell'albero da cui pende, le regole di business con la loro decisione o segnate come mancanti, i criteri di accettazione che poi saranno il copione del test, e un ordine con la sua ragione.

2. Rispondi alle domande (per Turnera chiederà, per esempio, cos'è "il giorno": quello di oggi, o uno qualsiasi che si scelga?; cancellare cancella o marca?). Quelle domande sono decisioni di business; nella lezione 6 vedrai dove si scrivono.
3. Leggi la specifica di ogni voce in sospeso come se fossi il cliente. Questo è il compito più importante della lezione, e quello che dà più tentazione di saltare. Descrive ciò che hai chiesto, con le tue parole? I criteri di accettazione sono quelli che useresti tu per dire "va bene"? C'è un caso limite che tu conosci e non c'è? Pende dal nodo giusto? Correggi prima che si costruisca qualsiasi cosa.

4. Aggiungi al patto di convivenza la routine di ogni sessione. Incollagli:

5. Adesso sì, comincia a costruire. Chiedigli di prendere la prima voce in sospeso. Da qui in poi, ogni sessione comincia con "quale voce prendi e perché", e ogni chiusura lascia la voce documentata.

Verifica di completezza. Leggi la specifica di una voce a caso: ha tutti i campi, e descrive ciò che hai chiesto tu? Ogni voce pende da un nodo dell'albero che riconosci? Ciascuna dice come si verifica? Ci sono regole segnate "mancante, chiesta" che non ti hanno chiesto? Ci sono voci chiuse senza prova né commit? Quelle chiuse conservano la loro specifica e la loro documentazione di chiusura? Prendi tre commit a caso: citano la loro voce? È comparso nel codice qualcosa senza voce?

Consegna. docs/PENDING.md con il primo blocco specificato, la routine nel patto, e la prima voce in corso.

Errori tipici. Accettare specifiche di una riga: l'agente le ha scritte per adempiere, e inventerà ciò che manca nel momento di costruire. Non leggere le specifiche: è l'unico momento in cui puoi intercettare un malinteso prima che costi. Lasciare che l'agente chiuda voci senza prove perché "l'ho già visto funzionare". Lasciare che chiuda senza documentare: sei mesi dopo nessuno sa perché il sistema fa quello che fa. E quello che costa di più correggere: lasciare che faccia "una cosina in più" fuori dalla lista. La prima volta che glielo lasci fare, hai perso il perimetro esatto.

Nel progetto guida. Il primo blocco di Turnera sono circa sei voci in sospeso, che pendono dal dominio "Agenda" dell'albero: PND-001 vedere gli appuntamenti di un giorno; PND-002 caricare un appuntamento con paziente, professionista, data e ora; PND-003 impedire due appuntamenti dello stesso professionista alla stessa ora; PND-004 cancellare un appuntamento (marcare, non cancellare: decisione della lezione 6); PND-005 cercare un paziente per nome o telefono; PND-006 la registrazione di un paziente con i dati minimi. La specifica di PND-003, per esempio, dice: nodo Agenda → processo "caricare appuntamento" → entità Appuntamento; storia: "non possono esserci due appuntamenti dello stesso professionista alla stessa ora, mi è successo due volte con il quaderno" (parole della responsabile); regola: "doppio appuntamento solo se il professionista l'ha abilitato" (decisione in sospeso, chiesta); dati: professionista, data, ora di inizio, durata; schermata: modulo di caricamento; casi limite: appuntamenti che si sovrappongono parzialmente, appuntamenti di durata diversa; criteri di accettazione: "dato un appuntamento del Dott. A alle 10:00, quando provo a caricarne un altro del Dott. A alle 10:00, allora la schermata avvisa e il database non lo salva"; verifica: test end to end del modulo più query al database. Questa è una specifica.

Lezione 6 — Le decisioni si scrivono accanto al codice

Cosa devi capire. Il modello, quando trova un buco nelle regole di business, lo riempie. Non si ferma a chiedere; completa con ciò che gli sembra più probabile, con la stessa naturalezza con cui scrive il resto. Per questo questa lezione non è "scrivi le decisioni" ma "esigi che si fermi e chieda quando ne manca una". E quando decidi, la decisione si scrive con le tue parole testuali, il tuo nome e la data, nel commit, nella specifica della voce in sospeso e in un registro. Io lo faccio dal primo sistema Ref. 29; sei settimane dopo, quando qualcuno chiederà "perché cancellare non cancella?", la risposta è scritta ed è tua.

Il compito.

1. Aggiungi al patto la routine delle decisioni. Incollagli:

Gli stai chiedendo di fermarsi davanti a una regola non scritta, di chiedere con raccomandazione e alternativa (perché tu possa decidere in dieci secondi), di registrare le tue parole testuali nei tre posti, e quando non rispondi di scegliere la più reversibile e segnarla.

2. Continua a costruire le voci del blocco. Ogni volta che ti chiede una regola di business, decidi e rispondi con il formato di chiusura.

3. Incollagli:

4. Fai la prova contraria, una volta, di proposito: lascia una domanda senza risposta per una sessione e guarda cosa fa. Deve scegliere la più reversibile e segnarla "per omissione". Se ha scelto ciò che gli pareva e non l'ha segnato, è un fallimento del gradino: correggilo nel patto.

Verifica di completezza. Apri tre commit che toccano regole di business: citano chi ha deciso e quando? La regola sta anche nella specifica della voce? Ci sono decisioni "per omissione" senza conferma? C'è qualche regola nel sistema che non riconosci come tua? Le frasi sono testuali o "migliorate"?

Consegna. docs/DECISIONS.md che cresce, con almeno cinque decisioni del primo blocco, e i commit e le voci in sospeso che le citano.

Errori tipici. Rispondere alle domande via chat e non esigere che restino scritte: alla terza sessione nessuno se le ricorda più. Lasciare che l'agente "migliori" le tue parole: una regola parafrasata è una regola diversa. E il più grave: scoprire in produzione una regola che nessuno ha deciso. Quando succede (succederà), non è un bug: è un fallimento del gradino 6, e si corregge nel patto, non solo nel codice.

Nel progetto guida. Decisioni tipiche del primo blocco di Turnera: "cancellare marca l'appuntamento come cancellato e salva chi e quando; non si cancella nulla"; "un professionista non può avere due appuntamenti alla stessa ora, ma sì due pazienti in un appuntamento doppio se il professionista l'ha abilitato"; "il telefono del paziente è obbligatorio; l'email no". Ciascuna con la data e con il nome della responsabile, e ciascuna incollata nella specifica della voce in sospeso che ne aveva bisogno.

Lezione 7 — Misurare prima di costruire, con uno strumento che a sua volta si verifica

Cosa devi capire. Il modello produce affermazioni con un numero ("ci sono circa 120 query di quel tipo") e suonano esattamente uguali quando sono misurate e quando sono stimate. Tu non puoi distinguerle dal tono. L'unico modo è esigere lo strumento: "con cosa l'hai misurato? mostrami il comando". La regola del gradino è che nessun numero che decide qualcosa esce da un'impressione: esce da un misuratore che vive nel repository, che ha un test che lo verifica contro un caso noto, e che tu puoi eseguire.

E c'è qualcos'altro, che ho imparato a suon di colpi ed è il motivo per cui ho tardato a formalizzare questa regola che davo per ovvia: anche i misuratori mentono. In uno dei miei sistemi, un misuratore dava zero perché non vedeva una parte del codice, e un altro diceva 27 quando erano 44 Ref. 35, Ref. 36. Per questo l'audit in due direzioni: dal codice alla misura (tutto ciò che dovrebbe essere contato è contato?) e dalla misura al codice (tutto ciò che è contato esiste davvero?).

In un progetto piccolo, "misurare" è modesto: contare quante query fa una schermata al caricamento, quanto ci mette il report mensile, quanti messaggi sono stati mandati ieri. Non serve un cricchetto né un budget per percorso. Ciò che serve sì è che il numero abbia un comando dietro.

Il compito.

1. Incollagli:

Gli stai chiedendo il misuratore nel repository, il test del misuratore, di chiedere ciò che gli manca invece di approssimare, di marcare l'approssimato, il numero con il comando, l'audit in due direzioni, e l'ordine: prima misurare, poi proporre.

2. Esegui tu il comando che ti ha dato. Deve darti lo stesso numero. Non serve che tu capisca lo script; sì che lo esegua.
3. Se l'ipotesi era vera e l'agente propone di sistemarlo, chiedigli un budget.

4. Incollagli:

Così, se qualcuno rimette il ciclo tra tre mesi, la batteria lo rileva.

5. Aggiungi al patto la regola cinque, per quando un piano porta numeri:

Verifica di completezza. Hai eseguito il misuratore e ti ha dato lo stesso risultato? Ha un test, contro quale caso noto? C'è qualche numero nel rapporto senza misuratore dietro? L'approssimato è marcato? C'è un budget con test?

Consegna. Un misuratore nel repository con il suo test, un numero con il suo comando e la data in docs/STATUS.md o nella voce in sospeso, e (se serviva) un budget protetto da un test.

Errori tipici. Accettare il numero senza eseguire il comando: metà del valore di questa lezione sta nel fatto che lo esegua tu. Un misuratore che dà zero: non è quasi mai zero; quasi sempre non sta vedendo qualcosa. E lasciare che l'agente "sistemi mentre misura": l'ordine è il metodo.

Nel progetto guida. Il misuratore di Turnera è uno script che carica un giorno con 10, 50 e 200 appuntamenti in un database di test, apre l'agenda di quel giorno contando le query, e scrive i tre numeri. Il test del misuratore verifica che con 0 appuntamenti conti esattamente le query di base (diciamo, 2). Se c'era il ciclo, i numeri sono 12, 52 e 202; si sistema, diventano 3, 3 e 3, e il budget resta a 4 con un test che fallisce se l'agenda fa più di 4 query per qualunque quantità di appuntamenti.

Lezione 8 — I test come lucchetti, provati in rosso, e le prove end to end

Cosa devi capire. Questa è la lezione centrale del corso. Di un test che non hai mai visto fallire non sai se prova qualcosa. Il modello scrive il codice e il test nella stessa sessione, con la stessa comprensione: se ha capito male la richiesta, il test prova ciò che ha capito, e passa. L'unico modo economico per sapere che il test guarda ciò che conta è vederlo in rosso contro il codice vecchio: se anche il codice di prima della modifica lo passa, il test non distingue il prima dal dopo, e allora non serve. Per questo la richiesta non è "scrivi test" ma "mostrami il rosso, poi il verde, poi la regressione". Il caso che lo mostra meglio è quello dei contatori che non coincidevano Ref. 26.

E la seconda idea, che è importante quanto la prima: le prove end to end. Un test che verifica dalla schermata (clicca, digita, legge) e controlla l'effetto nel backend (la riga è rimasta, lo stato è cambiato) è quello che sostituisce la tua lettura del codice. I criteri di accettazione della voce in sospeso ("dato, quando, allora") sono il suo copione. E si eseguono tre volte, a tre scale: il flusso toccato, con ogni voce; tutti i flussi che esistono, alla chiusura di ogni blocco; e tutti i flussi con la versione esatta, prima di ogni deployment in produzione. Se fai solo la terza, arrivi alla fine con un sistema che nessuno ha provato end to end per settimane.

Il compito.

1. Aggiungi al patto la routine delle prove. Incollagli:

Gli stai chiedendo il test guidato dai criteri di accettazione, il rosso dimostrato come ricevuta (il comando, la versione, i numeri e il codice di uscita, perché tu possa eseguirlo di nuovo), il verde, la regressione delle voci vicine, la prova end to end del flusso con l'effetto nel backend, niente simulazioni proprio di ciò che si prova, e di chiedere ciò che manca invece di simularlo.

2. Prendi la voce del doppio appuntamento (PND-003 in Turnera, o l'equivalente nel tuo progetto: una regola che impedisce qualcosa). Chiedigli di chiuderla con la routine. Leggi il rapporto: deve esserci un output in rosso con i numeri ("1 su 1 fallisce contro la versione senza la regola"), poi il verde, e la prova end to end: un browser controllato da programma che apre la schermata, prova a caricare il doppio appuntamento, legge l'avviso, e controlla nel database che non è stato salvato.
3. Se ti dice che non può provare end to end perché la schermata non si può operare da programma, fermati: è X2 che fallisce, e va sistemato adesso (aggiungere identificatori agli elementi della schermata) prima di proseguire.

4. Incollagli:

5. Alla chiusura del blocco, quando le sei voci sono chiuse, esegui la batteria completa.

6. Incollagli:

7. E dopo di questo, usa il sistema tu. Apri l'ambiente di test e fai ciò che farebbe la receptionist: carica un appuntamento, prova il doppio appuntamento, cancella, cerca. Ciò che ti dà fastidio, ciò che non capisci, ciò che sta dove non dovrebbe: annotalo come voce in sospeso. Questo momento trova ciò che nessun test trova.

Verifica di completezza. Il rapporto mostra il rosso, con i numeri? La regressione è stata eseguita nella stessa sessione, con i numeri? La prova end to end verifica anche il backend? C'è qualche parte simulata proprio dove sta la modifica? Il commit dice "provato in rosso"? Alla chiusura del blocco: ci sono tutti i flussi nella batteria end to end? Hai usato il sistema tu e annotato ciò che hai trovato?

Consegna. Almeno tre voci in sospeso chiuse con la routine completa (rosso, verde, regressione, end to end), la batteria completa end to end del blocco in verde, e le voci in sospeso uscite dalle tue prove umane.

Errori tipici. Accettare "i test passano" senza numeri e senza rosso. Accettare che la batteria si "acceleri" sostituendo le prove end to end con simulazioni. Lasciar passare un "non si può provare" senza aprire la voce in sospeso. E chiudere il blocco senza usarlo tu: lo sguardo umano non si delega.

Nel progetto guida. Il rosso del doppio appuntamento si vede così: l'agente toglie temporaneamente la regola, esegue il test, e l'output dice che il test è fallito perché il secondo appuntamento è stato salvato. Rimette la regola, esegue, verde. Poi la regressione: i test di PND-001 e PND-002 sono ancora in verde. E quello end to end: un browser controllato da programma carica il modulo, preme "salva", legge il messaggio "quell'orario è già occupato", e una query al database conferma che c'è un solo appuntamento a quell'ora. Alla chiusura del blocco, la batteria end to end percorre i tre flussi che esistono (vedere il giorno, caricare, cancellare), e la responsabile carica dieci appuntamenti di prova e scopre che l'ora si sceglie con un menu a tendina scomodo. Voce in sospeso nuova. Quando vedrai quel rapporto per la prima volta, capirai a cosa serve tutto il metodo.

Cosa è cambiato il 19 ottobre 2026 (D-037). Nel primo blocco di un progetto nuovo non c'è codice precedente: il test nuovo fallisce perché il modulo non esiste, e quel rosso non prova nulla. Da quel giorno, quando la versione precedente non ha il modulo, il rosso si prova per mutazione: l'agente pianta di proposito un difetto nella funzione appena scritta, mostra il test in rosso contro quel difetto (la ricevuta porta il diff), lo annulla e mostra il verde. In Forge, un rosso che dice solo "il file non si carica" non chiude più l'elemento in sospeso. Un mutante per elemento; i test di mutazione su tutta la base restano il rinforzo opzionale della lezione 9.

Lezione 9 — Qualità del codice verificata dalla macchina

Cosa devi capire. Tu non leggi il codice, e va bene; ma il codice esiste e qualcuno lo manterrà. Se nessuno lo legge, lo deve guardare una macchina: un linter (come il correttore ortografico di un elaboratore di testi, ma per il codice), un formattatore (un solo stile per tutto), limiti di dimensione dei file e delle funzioni, limiti di complessità (quanti percorsi ha una funzione), rilevamento di codice duplicato e morto, e la copertura dei test con un cricchetto (quella di oggi è il pavimento di domani). Tutto nell'integrazione continua, in rosso quando viene violato. Io l'ho fatto in tutti i miei progetti; un audit mi ha restituito un componente di più di duemila righe perché nessun limite l'aveva fermato Ref. 41.

1. Incollagli il prompt iniziale del contratto del gradino 9 (in docs/peldanos/), con i tuoi limiti nei buchi.
2. Leggi docs/CODE_QUALITY.md. Ci sarà una lista di ciò che oggi fallisce; decidi cosa si sistema subito (una voce in sospeso per ciascuno) e cosa si tollera con una data, e scrivilo nello stesso file.

3. Aggiungi al patto la routine del gradino 9, avvolta in "Add this routine to docs/WORKING_AGREEMENT.md:" come le altre.
4. Chiedigli di inserire apposta, in un ramo, una funzione di cento righe e una variabile senza uso: la catena deve andare in rosso per entrambe le cose.

Verifica di completezza. L'ultima esecuzione della catena ha la qualità in verde? La prova del ramo è andata in rosso? Ci sono eccezioni al linter, e ciascuna ha la sua ragione scritta? La copertura di oggi è maggiore o uguale a quella di ieri?

Consegna. Il cancello di qualità nella catena, docs/CODE_QUALITY.md con limiti e valori, e la routine nel patto.

Errori tipici. Lasciare che l'agente "disattivi questa regola perché è troppo severa" senza che passi da te. Alzare un limite perché passi. E confondere la copertura con la qualità: la copertura conta i test, il rosso della lezione 8 dice se provano qualcosa.

Rinforzo opzionale. Quando il blocco è chiuso, il contratto del gradino 9 ha un terzo prompt, quello dei test di mutazione: uno strumento rompe il codice di proposito, una piccola modifica alla volta, e conta quanti di quegli errori vengono catturati dai test. È la misura che la copertura non dà, e quella che risponde all'obiezione che l'agente può fingere il rosso. In Turnera lo facciamo alla chiusura del secondo blocco, solo sulle righe cambiate.

Nel progetto guida. La prima esecuzione di Turnera dà rosso su tre cose: il modulo dell'appuntamento ha una funzione di 70 righe (si spezza in due: voce in sospeso), ci sono due copie del formato della data (una sola, nel server: voce in sospeso), e la copertura è al 61 %. Il cricchetto resta a 61 e sale con ogni voce in sospeso. Alla chiusura del blocco, 74 %.

Lezione 10 — I casi di prova manuale si scrivono insieme alla funzionalità

Cosa devi capire. Tutte le prove che abbiamo visto fin qui le scrive e le esegue il modello, e provano ciò che il modello ha capito. Manca la prova che fa una persona con i suoi occhi e le sue mani, seguendo un copione: un caso di prova manuale, con precondizione, passi, risultato atteso e una tabella per annotare ogni esecuzione. Il copione lo scrive l'agente insieme a ogni voce in sospeso, a partire dai criteri di accettazione; lo esegui tu (o la responsabile) alla chiusura di ogni blocco, prima del primo deployment e dopo ogni deployment; e ciò che fallisce torna nel ciclo come voce in sospeso correttiva, con le tue parole. È lo sguardo umano con copione, ed è la chiusura del circuito del grafico del processo: l'esecuzione manuale reimmette requisiti.

1. Aggiungi al patto la routine del gradino 10 (nel contratto, "Routine di ogni voce in sospeso"), avvolta come le altre. Da adesso, ogni voce in sospeso che tocca una schermata si chiude con il suo caso.
2. Chiedigli di scrivere i casi delle voci in sospeso già chiuse del blocco. Prendine uno a caso e seguilo tu nell'ambiente di test senza chiedergli niente: se hai dovuto chiedere, il caso non è scritto per una persona; faglielo riscrivere.
3. Alla chiusura del blocco, esegui tutti i casi del blocco tu, a mano, e annota in ciascuno la data, il tuo nome, passato o fallito, e l'osservazione. Ciò che ti dà fastidio e non entra in nessun caso, annotalo alla fine del file.

4. Incollagli il prompt di esecuzione del contratto del gradino 10. Ogni fallimento deve tornare come voce in sospeso correttiva con le tue parole.

Verifica di completezza. Hai potuto seguire un caso senza chiedere? Ogni voce in sospeso chiusa che tocca una schermata ha il suo caso? Ogni caso dice cosa verificare dall'altro lato dello schermo? L'esecuzione ha data e nome in ogni caso? Ogni fallimento ha la sua voce in sospeso con le tue parole?

Consegna. docs/MANUAL_TESTS.md con un caso per flusso del blocco, la prima esecuzione registrata, e una voce in sospeso per ogni fallimento.

Errori tipici. Lasciare che l'agente marchi i casi come eseguiti. Casi che sono il test automatico in prosa. E sistemare i fallimenti sul momento, senza voce in sospeso: si perdono le tue parole e la traccia di cosa si ripete.

Nel progetto guida. I casi del primo blocco di Turnera sono sei: vedere l'agenda del giorno, caricare un appuntamento, tentare un sovrappuntamento, cancellare, cercare un paziente, registrare un paziente. Nella prima esecuzione ne falliscono due: quello di cancellare (l'agenda non si aggiorna finché non si ricarica la pagina; osservazione della responsabile: "pensavo che non si fosse cancellato") e quello di cercare (con due pazienti dello stesso cognome ne mostra uno solo). Due voci in sospeso correttive, con le sue parole. Il menu a tendina scomodo dell'ora, che nessun test ha visto, compare come osservazione sparsa.

Lezione 11 — Simmetria tra produttore e consumatore, e il registro degli anti-pattern

Cosa devi capire. Quando cambi un capo del sistema (il server, il database, un robot), l'altro capo (la schermata, un contatore, un report) deve cambiare nello stesso commit. Se no, divergono, e l'utente vede un numero da una parte e un altro dall'altra Ref. 26. Il principio che lo evita è semplice da enunciare e difficile da sostenere: ogni lista ha un solo proprietario. Gli stati possibili di un appuntamento, le colonne di un report, le cause per cui qualcosa aspetta: le definisce una sola parte (il produttore) e le altre le leggono da lì Ref. 27. L'albero semantico è il primo posto in cui quelle liste si dichiarano. Appena ci sono due copie, una è vecchia; resta solo da sapere quale.

La seconda metà della lezione è il registro degli anti-pattern (GOTCHAS): gli errori che ti sei già mangiato una volta, annotati con il loro odore, la loro causa radice, la loro correzione e come rilevarli prima Ref. 2. L'importante non è annotarli: è aggiungere la verifica automatica che li rilevi, perché un anti-pattern annotato e non automatizzato si ripete quando cambia la sessione.

Il compito.

1. Chiedigli la mappa dei contratti:

Gli stai chiedendo l'inventario dei contratti con i loro due lati, e che ciò che non vede lo dichiari invece di ometterlo.

2. Aggiungi la routine al patto:

3. Fai la prova della lista: scegli una lista che compare nella schermata (in Turnera, gli stati di un appuntamento: in attesa, confermato, cancellato, assente) e chiedi all'agente di mostrarti dove è definita e dove viene letta. Se ci sono due definizioni, chiedigli di lasciarne una sola, e che coincida con l'albero semantico.
4. La prima volta che qualcosa si rompe per la seconda volta (succederà), registralo.

5. Incollagli:

Verifica di completezza. Scegli un contratto della mappa: ogni consumatore lo legge dal produttore o ha la propria copia? C'è un numero che compare in due schermate e danno lo stesso risultato? Gli stati delle entità coincidono tra il codice e l'albero semantico? Ogni voce di GOTCHAS ha le quattro parti? Si è ripetuto qualcosa che era già annotato?

Consegna. docs/PRODUCER_CONSUMER_MAP.md, la routine nel patto, e docs/GOTCHAS.md (anche se parte con una sola voce).

Errori tipici. Fare la mappa una volta e non guardarla più: deve crescere con ogni contratto nuovo. Annotare anti-pattern come aneddoti ("una volta è successo che…") senza la parte "come rilevarlo prima". E il classico: lo stesso testo di uno stato scritto a mano nel server e nella schermata; il giorno che uno cambia, l'altro resta.

Nel progetto guida. La mappa di Turnera ha, all'inizio, quattro o cinque contratti: la lista degli stati dell'appuntamento (la definisce il server, la leggono la schermata e il report mensile); la tabella degli appuntamenti (la scrive il caricamento, la leggono l'agenda del giorno e il report); la tabella dei pazienti; e, più avanti, la coda dei messaggi (la scrive l'agenda, la legge chi invia). Il primo GOTCHA di solito è di date: l'agenda mostrava l'appuntamento nel giorno sbagliato perché il server salvava in un fuso orario e la schermata mostrava in un altro. Odore: "l'appuntamento delle 23 compare domani". Causa radice: due fusi orari. Correzione: uno solo, nel server. Rilevamento: un test con un appuntamento alle 23:30.

Lezione 12 — Verifica onesta e rapporto proporzionato

Cosa devi capire. Se tu non leggerai codice, il rapporto dell'agente deve essere affidabile, e questo non succede da solo. Il modello è stato addestrato per essere utile e completo, e un rapporto che dice "questo non l'ho potuto verificare" sembra meno utile di uno che dice "fatto". Allora bisogna chiedergli esplicitamente le cattive notizie, i punti ciechi e ciò che non ha fatto. Se non glielo chiedi, non te lo dà; non perché lo nasconda, ma perché non lo considera parte della risposta. A me hanno riportato un errore di autenticazione con la dicitura "success" Ref. 43.

La struttura che lo rende onesto sono tre blocchi: verificato (con la prova accanto), creduto (ciò che pensa che funzioni e perché non l'ha provato), e punti ciechi (ciò che non può vedere da dove si trova). E una regola: le cattive notizie per prime.

Il compito.

1. Aggiungi al patto la routine del rapporto:

2. Chiedigli di chiudere la prossima voce in sospeso e leggi il rapporto con la lista di verifica qui sotto. La prima volta, quasi di sicuro, il blocco "punti ciechi" sarà vuoto. Chiedigli: "cosa non puoi vedere da dove ti trovi?". Deve esserci qualcosa (il tuo browser, l'ambiente di produzione, i dati reali). Se insiste che niente, insisti tu.
3. Pratica l'"è ancora rotto". Chiedigli qualcosa di piccolo, verifica nell'ambiente di test, e se per qualunque ragione non vedi la modifica (è comune: il deployment tarda, o non è stato fatto), digli "è ancora rotto".

4. Incollagli:

La metà degli "è ancora rotto" sono correzioni che stanno nel repository e non nel posto dove tu guardi Ref. 45. Questa clausola ti fa risparmiare ore.

Verifica di completezza. Ci sono i tre blocchi? Hai scelto un'affermazione di "verificato" a caso e ha la sua prova accanto, e l'hai potuta riprodurre? Copre ogni voce di ciò che hai chiesto? Le cattive notizie sono all'inizio? Ha detto "fatto" e basta qualche volta?

Consegna. La routine nel patto e tre rapporti consecutivi con i tre blocchi, uno dei quali con un punto cieco reale.

Errori tipici. Leggere solo il blocco "verificato" e saltare gli altri due: gli altri due sono quelli che ti proteggono. Accettare "dovrebbe funzionare" dentro "verificato": quello è "creduto" travestito. E abituarsi a rapporti sempre più lunghi: un rapporto gonfiato sta coprendo qualcosa con il volume.

Nel progetto guida. Un buon rapporto di chiusura di PND-004 (cancellare un appuntamento) in Turnera: "VERIFICATO: il test di cancellazione passa (1/1, provato in rosso contro la versione che cancellava fisicamente); regressione 6/6; end to end del flusso 'cancellare' in verde, con la riga marcata nel database; nell'ambiente di test, l'appuntamento 17 del 3 novembre risulta cancellato da 'reception1' alle 10:42 (screenshot). CREDUTO: il report mensile conterà bene le cancellazioni, ma non l'ho provato perché il report è PND-011 e ancora non esiste. PUNTI CIECHI: non posso vedere come appare lo stato 'cancellato' sul cellulare della receptionist; provalo tu."

Fase di uscita in produzione: lezioni da 13 a 20

Queste otto lezioni sono quelle che trasformano "funziona" in "si può sostenere", e si fanno una volta, in ordine, quando i primi due blocchi sono costruiti con il ciclo e provati da te nell'ambiente di test, e prima che il sistema agisca sul mondo (mandi messaggi, addebiti) o abbia utenti reali. Nel progetto guida, è il momento di aggiungere i promemoria e la caparra, e per questo la lezione 14 (lucchetti) va prima di costruire quelle funzionalità, non dopo. Le quattro di qualità operativa (da 16 a 19) sono quelle che io facevo senza nominarle; se sei alle prime armi, ogni contratto di quelle lezioni ha un paragrafo "Se sei alle prime armi" che spiega le sue parole nel linguaggio di tutti i giorni; leggilo prima della lezione.

Lezione 13 — L'audit periodico come input del piano

Cosa devi capire. Ogni tanto bisogna guardare il sistema intero con occhi freschi, e ciò che si vede non va in un rapporto che si archivia: va nella lista delle voci in sospeso. La parte importante è "occhi freschi": chi fa l'audit non deve essere chi ha costruito, perché ne condivide le supposizioni. Un modello che ha costruito un modulo "sa" che la password scritta nel codice era provvisoria; un modello che lo vede per la prima volta la riporta per ciò che è. Così si sono trovate due porte di amministratore che il costruttore aveva lasciato in un giorno Ref. 40. Non serve un'altra azienda: basta un'altra sessione, con un altro file di istruzioni, che non abbia partecipato.

Il compito.

1. Incollagli:

Gli stai chiedendo sola lettura, di dichiarare ciò che non ha potuto verificare invece di approvarlo per omissione, tutto il codice e non un campione, ogni rilievo con posizione, rischio, prova e priorità, voti per dimensione, e i P0 già come voci in sospeso proposte.

2. Leggi il rapporto. Scegli due rilievi e chiedi all'auditor di mostrarti la prova (il comando, la riga). Deve poterlo fare.

3. Torna alla sessione del costruttore e incollagli:

4. Ripeti questa lezione prima del primo deployment in produzione (lezione 15) e, poi, ogni uno o due mesi.

Verifica di completezza. Il rapporto dice cosa NON ha potuto verificare? Due rilievi a caso hanno file, riga e prova riproducibile? Ogni P0 ha la sua voce in sospeso aperta? I voti si potranno confrontare con il prossimo audit? L'audit l'ha fatto una sessione diversa da quella che ha costruito?

Consegna. docs/AUDIT_[data].md e le voci in sospeso P0/P1 aperte.

Errori tipici. Fare l'audit con la stessa sessione che ha costruito: confermerà le proprie supposizioni. Accettare un rapporto senza nessun P0 in un sistema di più di un mese: non è quasi mai vero. E archiviare il rapporto senza aprire le voci in sospeso: lì l'audit non è servito a niente.

Nel progetto guida. Il primo audit di Turnera di solito trova: dati dei pazienti nel log (telefoni stampati quando si inviano messaggi: P0); la ricerca dei pazienti per nome senza indice (P1, si noterà a 5.000 pazienti); il modulo dell'appuntamento che non valida che la data sia futura (P1); e qualche dipendenza con una vulnerabilità nota (P1). Quattro voci in sospeso nuove, tutte con file e riga.

Lezione 14 — Fail-closed, lucchetti e zero danno silenzioso

Cosa devi capire. Il software, per default, davanti al dubbio va avanti: se la validazione fallisce, il codice continua; se il servizio non risponde, si assume che tutto vada bene. È "fail-open", come una porta che si apre quando va via la luce. Il metodo inverte il default: davanti al dubbio, no. Ogni azione con conseguenze (addebitare, inviare, cancellare, approvare) porta un lucchetto, ha una via del ritorno scritta, e ogni automazione nuova parte in modalità di prova, registrando ciò che avrebbe fatto, finché tu non la abiliti. I lucchetti che ho messo nel mio primo sistema sono il modello Ref. 28.

Questa lezione va prima di costruire le funzionalità che agiscono sul mondo. In Turnera, prima dei promemoria e della caparra, che sono il terzo blocco.

Il compito.

1. Incollagli:

Gli stai chiedendo di confrontare ciò che il business ha detto con ciò che il codice fa (lì compaiono le azioni che nessuno ricordava), di chiedere le differenze, e per ogni azione la reversibilità, il lucchetto e la via del ritorno, con la regola del fail-closed scritta.

2. Conferma lucchetto per lucchetto, con il proprietario.

3. Chiudi con:

4. Adesso apri il terzo blocco (i promemoria, la caparra) con la lezione 5, costruiscilo con il ciclo completo delle lezioni da 5 a 12, e lascialo in modalità di prova. Guarda per qualche giorno il registro di "avrebbe mandato" prima di abilitare l'invio reale.

Verifica di completezza. Ogni azione che addebita, invia, approva o cancella è nella tabella? Ogni lucchetto ha il suo test in rosso? Ogni azione irreversibile ha una via del ritorno scritta? Le automazioni nuove sono partite in modalità di prova e hai visto il registro prima di abilitarle?

Consegna. docs/LOCKS.md, un test per lucchetto provato in rosso, e le automazioni in modalità di prova con il loro registro.

Errori tipici. Abilitare l'invio reale "per provare con un messaggio al mio telefono": la modalità di prova esiste proprio per quello. Un lucchetto che si salta con un parametro "per i test": quel parametro resterà impostato in produzione. E non guardare il registro di "avrebbe fatto": è l'unica finestra per vedere un errore prima che arrivi a un paziente.

Nel progetto guida. La tabella dei lucchetti di Turnera: inviare promemoria (non reversibile; lucchetto: idempotenza per appuntamento, un solo invio per appuntamento e canale, limite di 200 al giorno, modalità di prova per prima; ritorno: nessuno, per questo il limite); addebitare la caparra (reversibile con rimborso; lucchetto: conferma esplicita della receptionist, importo fissato dal professionista; ritorno: rimborso tramite il provider di pagamento); cancellare un appuntamento (irreversibile per il paziente; lucchetto: conferma e registrazione di chi; ritorno: ricreare l'appuntamento); cancellare un paziente (irreversibile; lucchetto: doppia conferma, solo la responsabile, e solo se non ha appuntamenti futuri; ritorno: nessuno, per questo doppia). Ogni lucchetto con un test che mostra che, senza il lucchetto, l'azione avveniva.

Lezione 15 — Integrazione continua, ambienti, segreti e deployment come parte del prodotto

Cosa devi capire. Arrivare in produzione deve essere un pacchetto riproducibile: i test girano una volta, il deployment impacchetta e carica soltanto, la configurazione vive nel server e non nel repository, c'è una procedura per promuovere da test a produzione che si può eseguire due volte, e il rollback è provato (un rollback che non è mai stato provato non esiste). A me i test eseguiti tre volte per commit hanno bruciato la quota di integrazione continua Ref. 39. Sui segreti, una regola senza eccezioni: un segreto che si è visto in una chat, in un log o in un commit non è più un segreto; si ruota, e basta Ref. 42.

Hai già buona parte di questo dallo scheletro (lezione 4): l'integrazione continua e il deployment in test. Questa lezione lo completa verso la produzione.

Il compito.

1. Incollagli:

Gli stai chiedendo gli accessi prima di cominciare, i test una sola volta per commit, il deployment che impacchetta soltanto, la configurazione fuori, la promozione ripetibile, il rollback provato, il lucchetto contro i segreti, e la documentazione per una persona.

2. Prima del primo deployment in produzione, fai l'audit della lezione 13 se non l'hai fatto, ed esegui la batteria completa end to end di tutti i flussi con la versione esatta che promuoverai (il prompt di chiusura del blocco della lezione 8).

3. Aggiungi al patto la routine del deployment:

4. Fai il primo deployment in produzione, con il sistema ancora senza utenti reali. E poi prova il rollback: chiedigli di tornare alla versione precedente e di mostrarti che sta girando, e poi di tornare a quella nuova.
5. Se in qualche momento del corso hai incollato un segreto nella chat (una chiave API, una password), ruotalo.

6. Incollagli:

Verifica di completezza. Quante volte gira la batteria per commit? (una; chiedi il link). C'è qualche valore reale di configurazione nel repository? (chiedigli la ricerca vuota). Potresti seguire docs/DEPLOYMENT.md da solo? Il rollback è stato provato, quando, con quale prova? È stato ruotato ogni segreto comparso nella chat? Sai quanta quota di integrazione continua ti resta?

Consegna. L'integrazione continua una volta per commit, il deployment che impacchetta soltanto, docs/DEPLOYMENT.md, il rollback provato, il lucchetto anti-segreti attivo, e il sistema che gira in produzione (ancora senza utenti).

Errori tipici. Il deployment "a mano, veloce, perché è una modifica piccola": le modifiche piccole rompono la produzione perché nessuno le prova. Il file di esempio della configurazione con valori che sembrano reali (lo sono). E non provare il rollback fino al giorno in cui ti serve.

Nel progetto guida. Per Turnera, l'integrazione continua esegue la batteria (una trentina di test a questo punto, inclusi i sei flussi end to end) a ogni push; il deployment in test è automatico alla fusione in main; la promozione in produzione è un comando che impacchetta la versione che sta in test e la carica, con la configurazione (la chiave del provider di messaggi, quella del provider di pagamento, la URL del database) in un file di ambiente nel server che non sta nel repository. Il rollback è lo stesso comando con la versione precedente. E il lucchetto anti-segreti è una verifica a ogni commit che rifiuta qualunque cosa che sembri una chiave.

Lezione 16 — Osservabilità e tracciabilità, con livello configurabile

Cosa devi capire. Quando qualcosa fallirà in produzione, vorrai sapere cosa è successo senza aprire il codice e senza che l'agente "controlli": cercare un numero e far comparire la storia completa di quell'azione, dalla schermata al database. Questo è un registro strutturato con un identificatore di correlazione. E vorrai alzare il dettaglio di ciò che il sistema scrive, per un minuto, mentre indaghi, senza rifare il deployment: questo è il livello configurabile. La tracciabilità è l'altra metà: ogni azione con conseguenza (ha incassato, ha inviato, ha cancellato) resta in una lista che l'applicazione non può modificare, con chi, quando e cosa. Senza questo, l'agente residente della lezione 23 opera alla cieca e i monitoraggi delle lezioni 21 e 22 non hanno niente da guardare Ref. 16.

1. Incollagli il prompt iniziale del contratto del gradino 16 (in docs/peldanos/), tale e quale.
2. Quando ti mostra l'identificatore di una richiesta reale, cercalo tu nei registri dell'ambiente di test: deve comparire nella schermata, nel backend, nel database e nella chiamata al provider di messaggi.
3. Alza tu il livello a debug, fai un'azione, guarda, riabbassalo. Se hai dovuto fare il deployment, non è salito.
4. Cerca "Giovanni" (o qualunque nome di prova) nei registri: non ci deve essere.

5. Aggiungi al patto la routine del gradino 16 (nel contratto, "Routine"), avvolta in "Add this routine to docs/WORKING_AGREEMENT.md:" come le altre.

Verifica di completezza. Hai seguito tu un identificatore attraverso tutti gli strati? Hai cambiato il livello senza fare il deployment? C'è qualche dato personale nei registri? La cancellazione di un appuntamento in test è rimasta nell'audit con chi e quando? docs/OBSERVABILITY.md ti basta per trovare un registro da solo?

Consegna. Registri strutturati con livello configurabile, l'identificatore propagato, l'audit delle azioni con conseguenza, docs/OBSERVABILITY.md, e la routine nel patto.

Errori tipici. Accettare dei "log" che ogni modulo scrive in modo diverso. Lasciare la produzione su debug "per ora". E che l'identificatore non arrivi al processo notturno dei promemoria, che è proprio dove gli incidenti si perdono.

Nel progetto guida. L'identificatore di "cancellare l'appuntamento 17" compare nel clic, nel server, nella riga marcata nel database e nell'email al professionista. L'audit dice "reception1 ha cancellato l'appuntamento 17 alle 10:42 dall'agenda del giorno; esito: ok". La responsabile alza il livello a traccia per vedere perché un promemoria ha tardato, lo trova, e lo riabbassa.

Lezione 17 — Ottimizzazione dello strato di persistenza, misurata prima e dopo

Cosa devi capire. Il database è dove i sistemi muoiono lentamente: bene con cento appuntamenti, male con centomila. Un indice è come quello di un libro: senza di esso, il database legge l'intera tabella per trovare un appuntamento. Un ciclo N+1 è fare cento query per mostrare cento appuntamenti invece di una. Questa lezione applica la lezione 7 al database: misurare ogni query con un misuratore con test, cambiare ciò che i numeri dicono, misurare di nuovo sugli stessi dati, e lasciare un budget con test perché non torni Ref. 18, Ref. 37. Non è riscrivere il database né cambiare motore: quella era la lezione 3.

1. Incollagli il prompt iniziale del contratto del gradino 17.
2. Leggi la lista delle modifiche proposte come la responsabile leggerebbe una lista di lavori dell'ambulatorio: capisci cosa guadagna ciascuna e che rischio ha? Approva o rifiuta una per una. Rifai un conto a mano (righe al mese della tabella degli appuntamenti).

3. Incollagli il prompt di chiusura del contratto del gradino 17, con la lista approvata.
4. Esegui tu un misuratore prima e dopo, con i due comandi che ti ha dato.

Verifica di completezza. Le tue esecuzioni coincidono con la tabella di docs/PERSISTENCE.md? Resta qualche query che legge una tabella intera in un flusso critico? Ogni tabella ha la sua retention scritta? I budget hanno un test (chiedigli di superarne uno e di mostrarti il rosso)?

Consegna. I misuratori con test, docs/PERSISTENCE.md con prima e dopo, i budget con test, e la batteria in verde.

Errori tipici. Misurare con i dieci record dello scheletro. Accettare "meglio migrare a un altro database". E migliorare un numero rompendo il foglio mensile che leggeva quella tabella: è mancata la mappa.

Nel progetto guida. L'agenda del giorno faceva una query per appuntamento (il ciclo della lezione 7): 52 query per 50 appuntamenti diventano 3. La ricerca dei pazienti per nome leggeva la tabella intera: un indice la fa scendere da 800 millisecondi a 4 con diecimila pazienti. Retention: i messaggi si archiviano dopo un anno; gli appuntamenti, mai. Budget: 4 query per l'agenda, con test.

Lezione 18 — Scansione e soluzione delle vulnerabilità

Cosa devi capire. Una vulnerabilità è un difetto che qualcuno può usare per entrare, rubare dati o far fare al sistema ciò che non deve. L'audit (lezione 13) le cerca con criterio, ogni tanto; questa lezione le cerca a macchina, tutto il tempo, in quattro strati: le dipendenze (pezzi di altri che il tuo sistema usa, con i loro difetti noti pubblicati), il codice (analisi statica), i segreti nella storia del repository, e la configurazione del server. E una regola: aggiornare una dipendenza è una modifica, e passa dal ciclo; "ho alzato la versione per chiudere il rilievo" senza regressione è il modo più comune di rompere la produzione di venerdì Ref. 41, Ref. 23.

1. Incollagli il prompt iniziale del contratto del gradino 18, con il tuo criterio nel buco.
2. Leggi docs/SECURITY_[data].md. Scegli due rilievi e chiedigli la prova. Dice cosa NON ha scansionato?

3. Incollagli il prompt di chiusura del contratto del gradino 18.
4. Chiedigli di mettere apposta, in un ramo, una dipendenza con vulnerabilità nota: la catena deve andare in rosso.

Verifica di completezza. L'ultima esecuzione della scansione è in verde e di che data è? Ogni P0 ha la sua voce in sospeso chiusa con prova? La scansione è un cancello in docs/GATES.md? Sai quando gira la prossima scansione programmata?

Consegna. La scansione in quattro strati nella catena e con un calendario, docs/SECURITY_[data].md, docs/SECURITY.md, i P0 e i P1 sistemati, il cancello.

Errori tipici. Una scansione "pulita al primo colpo" in un sistema di più di un mese: è mancato uno strato. Dieci dipendenze aggiornate in un commit. Un P0 "accettato" senza voce in sospeso né data.

Nel progetto guida. La scansione di Turnera trova: una dipendenza del generatore di PDF con una vulnerabilità nota (P1, si aggiorna con regressione ed end to end); l'header che impedisce di incorporare l'agenda in un altro sito, assente (P1, una riga di configurazione, con test); una chiave di prova del provider di pagamenti nella storia del repository (P0: si ruota, anche se è di prova); e una porta del database aperta al mondo sul server di test (P0: si chiude). La scansione resta come cancello e gira il lunedì.

Lezione 19 — Prove di rendimento in volume e punto di rottura

Cosa devi capire. La lezione 3 ha dimensionato con i conti; questa li verifica con il sistema in esecuzione. Una prova di carico simula molti utenti alla volta. Si guardano il rendimento (azioni al secondo), la latenza (quanto ci mette ogni azione; la mediana e il percentile 95, che è ciò che vedono quelli che si lamentano) e il tasso di errore, al volume atteso e al "per dieci". E poi si alza il carico finché qualcosa non si rompe: il punto di rottura non è "diventa lento" ma "le connessioni al database si sono esaurite a 180 utenti". Quel numero è il più utile della fase, perché da lì escono le soglie di allerta della lezione 21 Ref. 12, Ref. 44.

1. Incollagli il prompt iniziale del contratto del gradino 19, con i flussi e la tolleranza nei buchi.
2. Leggi docs/PERFORMANCE_[data].md con la tolleranza accanto: l'agenda del giorno rientra in due secondi al volume atteso? E al per dieci? Cosa si è rotto per primo e a quale carico?
3. Decidi con la responsabile fino a quale volume si sistemano i colli di bottiglia adesso: se pensano di venderlo ad altri ambulatori, il "per dieci" è adesso; se no, con una data.

4. Incollagli il prompt di chiusura del contratto del gradino 19.
5. Esegui tu lo script al volume atteso con il comando che ti ha dato: i numeri si devono somigliare.

Verifica di completezza. La schermata più usata rientra nella tolleranza, o c'è una voce in sospeso con il numero? Il punto di rottura dice cosa si è rotto e a quale carico? Le soglie di docs/PERFORMANCE.md stanno sotto il punto di rottura e sopra l'atteso? La prova è un cancello e la prima esecuzione è archiviata?

Consegna. Lo script di carico con test, docs/PERFORMANCE_[data].md, docs/PERFORMANCE.md con soglie e cancello, e una voce in sospeso per ogni collo di bottiglia.

Errori tipici. "Regge il per dieci senza problemi" senza punto di rottura: non ha alzato abbastanza il carico. Uno script che colpisce l'API e non la schermata. Sistemare colli di bottiglia durante la prova, "già che c'ero".

Nel progetto guida. Al volume atteso, l'agenda risponde in 300 millisecondi; al per dieci, in 1,4 secondi; l'invio notturno di 400 promemoria ci mette 50 secondi. Il punto di rottura: a 180 utenti concorrenti si esaurisce il pool di connessioni (10) e le azioni cominciano a fallire. Soglie: allerta se l'agenda supera 1,5 secondi o se le connessioni in uso superano 7. Voce in sospeso: l'invio notturno a lotti di 50, perché la responsabile vuole davvero venderlo.

Lezione 20 — Documentazione viva e manuali che una persona può seguire senza IA

Cosa devi capire. Il sistema deve potersi usare, mantenere e ripristinare senza l'agente e senza di te. Il criterio per il manuale di ripristino è concreto: deve poterlo seguire una persona di fiducia che non programma, alle tre del mattino, con il sistema giù e l'agente senza connessione. Se un passo dice "consultare lo sviluppatore", è incompleto. E siccome rigenerare la documentazione con un modello è gratis, la regola diventa "nello stesso commit": ogni modifica che tocca ciò che l'utente vede, ciò che l'operatore fa o come si distribuisce, aggiorna il manuale nello stesso commit. I manuali che ho scritto per il mio primo sistema con quel criterio sono il modello Ref. 24.

E una fonte che hai già: le voci in sospeso chiuse. Se hai documentato ogni chiusura come chiede la lezione 5, il manuale utente non si scrive da zero: si monta a partire dalle voci che si sono chiuse, blocco per blocco, e il diario delle modifiche esce direttamente da esse.

Il compito.

1. Aggiungi la routine al patto:

2. Incollagli:

Gli stai chiedendo i tre manuali con screenshot reali, il criterio delle tre del mattino per quello di ripristino, di chiedere ciò che solo il business sa invece di lasciare buchi, e data e versione.

3. La prova reale: dai il manuale di ripristino a qualcuno che non programma (il proprietario, un familiare) e chiedigli di seguire la sezione "è andato giù" nell'ambiente di test. Dove si blocca, bisogna sistemare il manuale.
4. Dopo la prossima modifica di schermata, verifica che il commit abbia toccato il manuale utente.
5. E adesso i test di accettazione: il proprietario usa il sistema intero nell'ambiente di test, con dati realistici, seguendo i sei flussi, prima che entri il primo utente reale. Ciò che trova sono voci in sospeso; con quelle chiuse, il sistema è accettato.

Verifica di completezza. Uno screenshot a caso coincide con l'ambiente di test di oggi? Qualcuno che non programma è riuscito a seguire la sezione "è andato giù"? L'ultimo commit che ha cambiato una schermata ha toccato il manuale? Il diario delle modifiche ha una voce per ogni voce in sospeso chiusa? Ci sono buchi tipo "[completare]"? Ogni manuale dice per quale versione vale? Il proprietario ha fatto i test di accettazione su tutti i flussi?

Consegna. I tre manuali con data e versione, la prova con una persona fatta, e i test di accettazione chiusi.

Errori tipici. Generare i manuali una volta e non mettere la routine nel patto: dopo due mesi hanno screenshot di schermate che non esistono più. Un manuale di ripristino che comincia con "apri una sessione con l'agente". E non fare la prova con una persona: è l'unica verifica che vale.

Nel progetto guida. Il manuale utente di Turnera ha sei schermate con screenshot, montate a partire dalle voci in sospeso chiuse dei tre blocchi; quello di manutenzione spiega dove sta ogni modulo e come eseguire la batteria; e quello di ripristino dice, in ordine, con i comandi: come sapere se il sistema è giù, come riavviarlo, come tornare alla versione precedente, come ripristinare il database dall'ultimo backup (che si fa tutte le notti: anche questo esce da questa lezione), e chi chiamare. La responsabile l'ha seguito nell'ambiente di test e si è bloccata su "ripristinare il database" perché il comando dava per scontata una cartella che lei non aveva; si è sistemato il manuale.

Fase di esercizio: lezioni da 21 a 23

Queste tre lezioni cominciano con il primo deployment in produzione e non finiscono: i due monitoraggi si montano con esso e girano da soli da allora, e la retrospettiva chiude ogni tappa e torna allo 0 per la successiva.

Lezione 21 — Monitoraggio di risorse e rendimento, con rapporto ciclico

Cosa devi capire. La lezione 19 dice come si comporta il sistema un giorno; la produzione è tutti i giorni, con i dati che crescono. Monitorare è guardare a macchina, tutto il tempo, l'uso delle risorse (processore, memoria, disco, connessioni, quota del provider di messaggi) e il tempo di risposta di ogni funzione e di ogni query, e avvisare quando qualcosa esce dal range: sopra una soglia (quelle della lezione 19) o molto diverso dalla linea base (ciò che dava prima). Un'*allerta* avvisa sul momento; il rapporto ciclico si legge con calma ogni settimana o ogni mese. Due regole: un'allerta che nessuno legge è un difetto dell'allerta; e una soglia non si alza per far tacere un'allerta senza una ragione misurata e scritta Ref. 37, Ref. 39.

1. Incollagli il prompt iniziale del contratto del gradino 21, con il canale, il ciclo e lo scostamento nei buchi.
2. Chiedigli di superare una soglia apposta in test: ti deve arrivare l'allerta dal canale.
3. Leggi il primo rapporto: ogni evento fuori range deve avere una causa o una proposta.

4. Aggiungi al patto la routine del gradino 21, avvolta in "Add this routine to docs/WORKING_AGREEMENT.md:".

Verifica di completezza. Ti è arrivata l'allerta provocata? Il rapporto ha ogni scostamento con causa o proposta? C'è una voce in sospeso per ogni scostamento che hai deciso di affrontare, con il numero come criterio? Qualche soglia è salita dalla lezione 19, e con quale ragione? Il rapporto guarda la quota del provider di messaggi?

Consegna. Raccolta con storia, allerte, il rapporto ciclico, docs/MONITORING.md, la routine nel patto.

Errori tipici. Allerte tutti i giorni che nessuno legge. Tre rapporti di fila che dicono "tutto normale". Una soglia alzata "perché smetta di avvisare". Dati personali conservati "per diagnosticare".

Nel progetto guida. Il primo rapporto mensile di Turnera dice: disco al 40 %, memoria stabile, l'agenda del giorno a 320 millisecondi di mediana (linea base), la ricerca dei pazienti salita da 4 a 9 millisecondi (la tabella cresce; dentro il range), e la quota di messaggi al 60 % (proposta: avvisare all'80 %). Uno scostamento: il rapporto mensile della responsabile ci ha messo 11 secondi il giorno 1 (proposta: precalcolarlo di notte; voce in sospeso).

Cosa è cambiato il 19 ottobre 2026 (D-039). La misurazione che riconvalida il dimensionamento porta la sua finestra verificabile: il primo e l'ultimo record letti dal database, non un numero scritto a mano. Nella pratica, 30.000 righe di tre anni passate come se fossero di uno hanno aperto un falso allarme. Una finestra scritta a mano è segnata come tale nel report e si limita ad avvisare.

Lezione 22 — Monitoraggio degli errori e rapporto ciclico

Cosa devi capire. Un sistema in produzione produce errori che nessuno segnala: la receptionist che ha visto la schermata bianca ed è tornata a provare, il processo notturno che si è interrotto. Questa lezione li cattura nei tre posti dove si nascondono (il backend, i processi e il browser), li raggruppa (mille volte lo stesso errore è una voce con un contatore), avvisa di quelli nuovi e di quelli che crescono, e produce un rapporto con il tasso di errore per flusso (su cento appuntamenti caricati, quanti sono falliti). Due regole: nessun errore senza voce in sospeso, e non esiste l'"errore noto" senza una voce in sospeso che dica perché si tollera e fino a quando Ref. 43, Ref. 22.

1. Incollagli il prompt iniziale del contratto del gradino 22, con il canale, il ciclo e il numero nei buchi.
2. Provoca tu un errore nel browser, in test (una data impossibile nel modulo dell'appuntamento, per esempio): deve comparire nella cattura con il tuo identificatore, e ti deve arrivare l'allerta se è nuovo.

3. Aggiungi al patto la routine del gradino 22, avvolta come le altre.
4. Con il primo rapporto: apri le voci in sospeso correttive degli errori nuovi, ciascuna con la sua riproduzione, e chiudile con la routine della lezione 8 (il test che lo riproduce in rosso).

Verifica di completezza. Il tuo errore provocato è arrivato alla cattura, all'allerta e al rapporto? C'è qualche errore ricorrente senza voce in sospeso né ragione con data? Un errore "sistemato" del rapporto ha il test in rosso nella sua voce in sospeso? Il tasso di errore per flusso c'è, ed è confrontato con il periodo precedente? Ci sono dati personali nella cattura?

Consegna. La cattura centralizzata e raggruppata, le allerte, il rapporto ciclico con il tasso per flusso, docs/MONITORING.md completo, la routine nel patto, e una voce in sospeso per ogni errore.

Errori tipici. "Zero errori in un mese" con utenti reali: la cattura non vede il browser o i processi. Un errore con mille occorrenze e il commento "noto, non influisce". Errori che si "sistemano" riavviando. E leggere il rapporto degli errori senza incrociarlo con quello delle risorse: la query lenta dell'uno è il timeout dell'altro.

Nel progetto guida. Il primo rapporto di Turnera ha tre errori: uno nel browser (l'agenda fallisce se il nome del professionista ha un apostrofo; 14 volte; voce in sospeso, test in rosso), uno nel processo notturno (il provider di messaggi ha restituito un errore una notte; 1 volta; voce in sospeso per riprovare con registro), e uno "noto" del nipote nel foglio mensile (voce in sospeso con data: si sostituisce con il rapporto della lezione R2 nella parte 2). Tasso di errore: 0,3 % in "caricare appuntamento", 0 % negli altri.

Cosa è cambiato il 19 ottobre 2026 (D-038). La cattura degli errori separa per fonte: gli errori del sistema e quelli degli strumenti che lo osservano (il pannello, l'agente residente, il monitoraggio stesso) vanno in sezioni distinte del report, e solo quelli del sistema aprono elementi in sospeso. Nella pratica, il primo report ciclico ha aperto sei "bug" che erano lo strumento che parlava con un server spento.

Lezione 23 — L'agente dentro il sistema, e la retrospettiva con i numeri

Cosa devi capire. Due cose chiudono il ciclo. La prima è opzionale: lasciare l'agente residente in produzione, con perimetro limitato, per diagnosticare e dare supporto senza che tu ci sia Ref. 13. La regola che lo ordina è che agisce a nome di qualcuno: la sua credenziale è associata a una persona responsabile, e tutto ciò che fa resta registrato a nome di quella persona; non è un account anonimo, è un dipendente con un capo. La seconda è obbligatoria: la retrospettiva con i numeri. Cosa è costato, quante voci in sospeso, quali hanno fatto più giri, che incidenti ci sono stati e in quale gradino cadono, e almeno una modifica proposta alla scala. Una retrospettiva che non cambia niente non è stata una retrospettiva; quella che mi ha portato a eliminare un'intera squadra di agenti è il modello Ref. 6.

Il compito (agente residente, se serve).

1. Incollagli:

Gli stai chiedendo la mappa prima di operare, che i buchi della mappa li dichiari, tre livelli di perimetro perché tu ne scelga uno, e la credenziale a nome di una persona.

2. Scegli il livello (per cominciare, sempre il primo: sola lettura e diagnosi).

3. Chiudi con:

Il compito (retrospettiva, sempre).

4. Incollagli:

Gli stai chiedendo numeri con fonte, ogni incidente mappato su un gradino (un incidente che non cade in nessuno è un gradino che manca), di chiederti i numeri che non ha, e una proposta concreta di modifica alla scala.

5. Leggi la proposta di modifica. Se ti sembra valida, mandala al repository di Urazuke come proposta di miglioramento (vedi CONTRIBUTING.md): è il modo in cui il metodo impara da ogni progetto.

Verifica di completezza. La mappa dice cosa NON può vedere l'agente? Hai visto nel log che un'azione fuori dal perimetro viene rifiutata? La credenziale agisce a nome di una persona? La retrospettiva ha numeri con fonte, o aggettivi? Ogni incidente cade in un gradino? C'è almeno una proposta concreta di modifica?

Consegna. docs/RESIDENT_AGENT.md (se serve) e docs/RETROSPECTIVE_[data].md.

Errori tipici. Dare all'agente residente un livello alto "perché possa risolvere tutto": comincia dalla sola lettura e sali quando ci sono prove. Una retrospettiva che dice che è andato tutto bene: non va mai tutto bene; è scritta per te, non per il metodo. E non mandare la proposta di modifica: il gradino 23 si chiude quando la scala cambia, non quando il documento si scrive.

Nel progetto guida. La retrospettiva di Turnera, in un corso tipico: una quarantina di ore dell'allievo, ventotto voci in sospeso, quelle che hanno fatto più giri sono state quelle dei messaggi (fusi orari e il provider di WhatsApp); due incidenti, uno nel gradino 11 (lo stato "assente" esisteva nella schermata e non nel server, e nemmeno nell'albero semantico) e un altro nel 15 (un deployment in produzione con la configurazione di test, rilevato dalla verifica end to end dopo il deployment). Proposta di modifica: che la routine di deployment del gradino 15 esiga di mostrare la differenza di configurazione tra test e produzione prima di promuovere, non solo "cosa cambia".

La lista di uscita in produzione

Quando le ventiquattro lezioni sono fatte, il sistema soddisfa questa lista. È la definizione operativa di "production grade" in Urazuke, e si può usare come lista di verifica finale, con il proprietario, senza aprire il codice:

1. C'è una scheda di idoneità con decisione, data e nome (P0).
2. C'è un patto di convivenza che l'agente legge in ogni sessione, e si è provato che lo legge (P1, P2).
3. Il file di progetto si legge in cinque minuti e dice cosa NON è il sistema; c'è un albero semantico confermato dal proprietario, e ogni voce in sospeso pende da un nodo (P2).
4. C'è un dimensionamento con dati primari con fonte, derivati con il conto, e lo scenario "per dieci" (P3).
5. Lo scheletro è stato distribuito vuoto nell'avvio, con la catena di integrazione e deployment, e il deployment è stato eseguito due volte (P4).
6. Ogni modifica ha la sua voce in sospeso con specifica dettagliata, e ogni voce chiusa conserva la sua specifica e la sua prova: è la documentazione di ciò che è stato fatto (P5).
7. Ogni regola di business ha proprietario, data e parole testuali, nel commit, nella voce in sospeso e nel registro (P6).
8. Ogni numero che ha deciso qualcosa ha un misuratore con test che tu puoi eseguire (P7).
9. Ogni test importante si è visto in rosso prima del verde; ogni flusso ha la sua prova end to end che verifica il backend dalla schermata; la batteria completa è stata eseguita alla chiusura di ogni blocco e prima della produzione (P8).
10. La qualità del codice si verifica a macchina a ogni commit, è un cancello, e la copertura non è mai scesa (P9).
11. Ogni funzionalità ha i suoi casi di prova manuale, scritti per una persona; sono stati eseguiti alla chiusura di ogni blocco e nell'accettazione, con data e nome; ogni fallimento è tornato come voce in sospeso (P10).
12. Ogni lista ha un solo proprietario; c'è una mappa produttore/consumatore; c'è un registro degli anti-pattern con verifica automatica (P11).
13. Ogni rapporto separa verificato, creduto e punti ciechi (P12).
14. C'è stato almeno un audit da parte di una sessione diversa, e i suoi P0 sono voci in sospeso (P13).
15. Ogni azione con conseguenze ha un lucchetto con test in rosso e via del ritorno; le automazioni sono passate per la modalità di prova (P14).
16. I test girano una volta per commit; la configurazione è fuori dal repository; il rollback è stato provato; nessun segreto vive nel repository né nella chat senza essere ruotato (P15).
17. I registri sono strutturati, con livello configurabile senza deployment, con un identificatore che segue ogni azione dalla schermata al database; le azioni con conseguenza restano in un audit immutabile; nessun dato personale nei registri (P16).
18. Le query reali sono state misurate al volume atteso, corrette con prima e dopo, e ci sono budget con test per percorso critico (P17).
19. La scansione delle vulnerabilità gira a ogni push e con un calendario, è un cancello, e non c'è nessun P0 aperto (P18).
20. C'è una prova di carico con test, eseguita al volume atteso e al "per dieci", con il punto di rottura scritto e le soglie derivate da esso (P19).
21. Ci sono tre manuali con data e versione, montati dalle voci in sospeso chiuse; una persona che non programma ha seguito quello di ripristino; il proprietario ha fatto i test di accettazione su tutti i flussi (P20).
22. L'uso delle risorse e i tempi di risposta sono sorvegliati con allerte e rapporto ciclico, e ogni scostamento ha una causa o una voce in sospeso (P21).
23. Gli errori si catturano nel backend, nei processi e nel browser, si raggruppano, si riportano per ciclo con il tasso per flusso, e nessuno resta senza voce in sospeso (P22).
24. C'è una retrospettiva con i numeri e una proposta di modifica alla scala (P23).

Se tutte e ventiquattro danno "sì", il sistema è pronto per entrare in esercizio. Se qualcuna dà "no", sai già quale gradino risalire.

E poi: la parte 2, il progetto ereditato

Questa prima parte insegna il metodo su una cartella vuota perché è il modo più chiaro di impararlo. Ma nella vita reale quasi mai ti danno una cartella vuota: ti danno un sistema che gira già e ti chiedono "sistema questo" oppure "aggiungici quello". La parte 2 del corso prende lo stesso ambulatorio su un'altra linea del tempo, con un'applicazione che gli ha fatto un nipote in un'estate e che nessuno capisce per intero, e insegna il tratto di normalizzazione del percorso evolutivo-correttivo: otto lezioni per recuperare gli input che il metodo dà per scontati, costruire la cintura di sicurezza e ordinare il debito, e due in più per correggere il primo bug e costruire la prima funzionalità nuova con il metodo completo.

Allegato A — Come valutare (per chi tiene il corso o si autovaluta)

Una griglia di valutazione semplice, per lezione, con tre livelli:

• Non salito: manca la consegna, o qualche verifica di completezza dà "no".
• Salito: la consegna esiste e tutte le verifiche danno "sì".
• Salito con prova di criterio: in più, l'allievo sa raccontare un caso in cui l'agente ha fatto qualcosa di sbagliato in quella lezione (ha supposto, inventato, riportato di più) e come l'ha rilevato. Questo è l'obiettivo reale del corso: non l'artefatto, ma il riflesso.

Ciò che non si valuta: la qualità del codice. Nessuno la legge. Si valuta la qualità della prova.

Allegato B — Adattamento del corso a ogni strumento

I prompt sono gli stessi in qualunque strumento. Ciò che cambia è dove vanno le routine che nel corso si aggiungono a docs/WORKING_AGREEMENT.md:

• In Claude Code, le routine vanno nel CLAUDE.md del progetto (o si include il patto da lì), e si leggono da sole in ogni sessione.
• In Cursor, vanno in .cursor/rules/, come regole sempre attive.
• In Codex CLI o Gemini CLI, in AGENTS.md o GEMINI.md nella radice.
• In Forge, il patto e le routine sono dottrine, i prompt di gradino si iniettano da soli all'attraversamento di ogni cancello, il registro delle voci in sospeso è nativo e l'albero semantico è il grafo di conoscenza del progetto. Il corso con Forge è lo stesso corso con meno copia e incolla.

La prova di lettura della lezione 2 vale per tutti: se una sessione nuova non sa cosa NON fa il sistema, lo strumento non sta caricando il file in cui hai messo il patto.

Allegato C — Ciò che questo manuale ancora non ha

• Una coorte che l'abbia seguito. L'ordine delle tappe, gli errori tipici e il progetto guida sono scritti a partire dai miei tre sistemi, non da allievi. La prima coorte li correggerà (e questo è, letteralmente, il gradino 23 applicato al corso).
• I pesi dei criteri di idoneità (lezione 0), che sto calibrando.
• Un esempio completo di docs/PENDING.md del progetto guida, con le ventotto voci in sospeso specificate e chiuse, perché un allievo veda com'è la documentazione di ciò che è stato fatto alla fine di un progetto.