I contratti di gradino

Un file per gradino. Hanno tutti lo stesso scheletro, e ce l'hanno di proposito, perché tu possa confrontarli e perché, col tempo, il riflesso di leggerli diventi automatico: l'intestazione con la fase, il quando, la forma e la dimensione (obbligatorio o proporzionale); a cosa serve; (1) il contesto richiesto, nominato in forma generica; (2) i prompt, in inglese, ciascuno preceduto da un blocco "Prima di inviare il prompt" (i file e gli input che devi avere pronti tu prima di incollarlo, con il loro contenuto e il loro stato minimo), seguito dalla sua traduzione e, sotto, dalla spiegazione di cosa sto chiedendo al modello e perché ogni clausola è lì; (3) il risultato atteso, con le sue caratteristiche; (4) la verifica di completezza, che fai senza leggere codice; (5) i segnali d'allarme, i sintomi di un gradino salito male.

I prompt in inglese sono un unico pezzo, identico nelle otto versioni del documento; node build/build.mjs li estrae in prompts/ e verifica che nessuna traduzione li abbia alterati. La traduzione che accompagna ogni prompt è perché tu lo capisca; al modello si incolla l'inglese.

Li ho scritti a partire da ciò che ho fatto in tre sistemi che oggi sono in produzione, non li ho ancora eseguiti così come sono. Il primo progetto che li userà dall'inizio alla fine ne correggerà diversi; fa parte del gradino 23. Quando un contratto cita un caso reale, lo fa con una marca [Ref. N] che rimanda al documento delle referenze; la procedura resta pulita e il dettaglio è a un clic.

Fasi: avvio si sale una volta per progetto; ciclo si ripete a ogni modifica; esercizio quando il sistema è già vivo. Il 23 torna allo 0 per il progetto successivo. La linea del tempo completa, con ciò che succede tra un gradino e l'altro, è nella Parte B del documento principale. I nomi dei file restano in spagnolo in tutte le lingue perché gli strumenti di build li riconoscano.

Passo 0 — Questo progetto si può affrontare così? (contratto del gradino)

Fase: avvio. Quando: una sola volta, prima di aprire il repository e prima di qualunque altra cosa. Forma: conversazione: l'agente valuta e chiede; tu decidi. Dimensione: obbligatorio in ogni progetto, per quanto piccolo. Stato: i criteri escludenti X1 e X2 sono chiusi; i criteri che pesano (da D1 a D10) li sto ancora calibrando e li marco come ipotesi.

A cosa serve

Non infilarti in un progetto in cui il metodo non può funzionare. Se l'agente non potrà verificarsi da solo end to end, o se non c'è un proprietario del dominio che decida, il metodo degrada a "programmare con l'IA" e tu finisci per leggere codice. Questo gradino è la porta d'ingresso: si attraversa una volta, e se non si attraversa, meglio saperlo prima che dopo.

E un'idea di fondo che voglio che tu abbia chiara: il metodo non serve per qualunque progetto, e questo non è un difetto. Un metodo che promette di servire per tutto non sta dicendo niente. Ciò che questo gradino fa è mettere il confine per iscritto, perché la decisione di entrare o non entrare sia una decisione e non una speranza. I due criteri escludenti vengono da progetti che ho rifiutato, non da quelli che ho accettato Ref. 46.

1. Contesto richiesto

Quello che segue è la lista generica. I file concreti che devi avere pronti prima di ogni prompt, con il loro contenuto e il loro stato minimo, stanno nella sezione 2, nel blocco "Prima di inviare il prompt" che precede ciascuno.

Nominato in forma generica; l'agente valuta se basta e chiede ciò che manca.

• Rilevazione della richiesta: cosa vuole il cliente, per chi, e cosa succede oggi senza il sistema.
• Rilevazione tecnologica: che tecnologia c'è o si propone, se esiste un sistema precedente, se quel sistema ha un repository e come è gestito.
• Rilevazione di testabilità: se le schermate si possono eseguire da programma e se ogni elemento dell'interfaccia è accessibile con i suoi diversi metodi (clic, digitazione, lettura dello stato), in modo che un test percorra la schermata e verifichi l'effetto nel backend.
• Chi è il proprietario del dominio e quanto tempo ha per decidere.
• Che conseguenza ha un errore (soldi, salute, esercizio, niente).
• Ambienti e accessi: se ci sarà un ambiente di test, se l'agente può accedervi, se c'è una produzione consultabile in sola lettura.

2. Prompt

I prompt sono in inglese, che è la lingua in cui i modelli seguono le istruzioni con più precisione e meno token. Ciascuno porta la sua traduzione (nell'HTML, con un pulsante), e sotto la spiegazione di cosa gli sto chiedendo e perché ogni clausola è lì. Al modello si incolla l'inglese.

Iniziale:

Cosa gli sto chiedendo: che legga i due input (la rilevazione e la scheda dei criteri); che prima di rispondere valuti se la rilevazione basta e, se non basta, chieda invece di supporre (questa è la clausola centrale di tutti i prompt del metodo); che compili la scheda con la fonte di ogni risposta, perché dopo si possa rintracciare; che marchi gli escludenti in verde o in rosso; e che non decida, perché l'idoneità la decido io. L'ultima riga gli chiede di rispondere nella mia lingua, perché il prompt è in inglese ma la conversazione non ha motivo di esserlo.

Di chiusura:

Cosa gli sto chiedendo: che lasci la decisione scritta con data e proprietario (gradino 6), con le condizioni se ci sono, e con la traccia di domande e risposte, che è la prova che non ha supposto niente.

3. Risultato atteso

Un file docs/ELIGIBILITY.md (o il nome che usa il tuo progetto), di una pagina, con:

• Data e chi ha deciso.
• I due criteri escludenti con la loro risposta e la loro fonte:
• X1: c'è un repository accessibile e gestito in modo standard (o il progetto è nuovo).
• X2: l'interfaccia si può eseguire da programma e ogni elemento è accessibile con i suoi diversi metodi, con verifica dell'effetto nel backend.
• I criteri che pesano, ciascuno con risposta, fonte e peso (quando il peso sarà calibrato).
• La decisione: va, non va, o va con condizioni, e le condizioni scritte.
• Le domande che l'agente ha fatto e le risposte, perché resti la traccia.

4. Verifica di completezza (la fai tu, senza leggere codice)

• I due escludenti hanno risposta esplicita e fonte? Se uno è in rosso, la decisione è "non va" o ha una condizione che lo risolve?
• C'è qualche criterio con risposta "suppongo di sì" o "probabilmente"? Se c'è, il gradino non è salito: l'agente doveva chiedere.
• La decisione è scritta con data e con nome?
• Le condizioni (se ci sono) sono verificabili? ("Avere accesso in lettura alla produzione prima del gradino 3" sì; "che il cliente collabori" no.)

5. Segnali d'allarme

• L'agente ha compilato la scheda intera senza fare una sola domanda. O la rilevazione era perfetta (non lo è mai) o ha supposto.
• La decisione è "va con condizioni" e le condizioni sono più di tre. Probabilmente è un "non va" che non si vuole dire.
• Al criterio X2 si è risposto "sì, con un po' di lavoro". Se le schermate non si possono operare da programma oggi, quel "po' di lavoro" è il progetto intero.

Passo 1 — Il patto di convivenza (contratto del gradino)

Fase: avvio. Quando: una sola volta, immediatamente dopo l'idoneità; si rivede quando un colpo lo esige. Forma: un solo invio, con un giro di aggiustamento tuo. Dimensione: obbligatorio in ogni progetto. È il gradino più economico di tutti e quello che evita più frustrazione.

A cosa serve

Metti per iscritto, prima della prima riga di codice, come lavorerete tu e l'agente. Sembra una formalità e non lo è: è ciò che evita che l'agente "aiuti" espandendo il perimetro, lasci debito per dopo, o riporti come fatto ciò che crede di aver fatto. Nel mio strumento questo file si chiama SQ.md (standard di qualità); il nome non conta, il contenuto sì.

Pensala così: l'agente è un collaboratore nuovo che arriva ogni mattina senza memoria di ieri. Il patto è ciò che gli dici il primo giorno, e ciò che rileggerà ogni giorno. Se non lo scrivi, dovrai dirglielo ogni volta, e lo dirai diverso ogni volta. Io l'ho scritto per la prima volta quando erano due settimane che ripetevo la stessa cosa in ogni sessione Ref. 1, e niente di quello che ci ho messo era nuovo nell'ingegneria dei sistemi; la novità era doverlo scrivere per qualcuno senza memoria.

1. Contesto richiesto

Quello che segue è la lista generica. I file concreti che devi avere pronti prima di ogni prompt, con il loro contenuto e il loro stato minimo, stanno nella sezione 2, nel blocco "Prima di inviare il prompt" che precede ciascuno.

• Nessuno del progetto: è il primo file.
• Tuo: le tue preferenze di lavoro (lingua, come vuoi che ti si facciano le domande, cosa consideri una perdita del tuo tempo, che livello di autonomia dai all'agente).

2. Prompt

Iniziale:

Cosa gli sto chiedendo: le sei regole minime, ciascuna con il fallimento che evita (è questo che le rende regole e non consigli); che proponga regole proprie del progetto ma le marchi come proposte, perché tu le accetti o le rifiuti; e che chieda ciò che ha bisogno di sapere su di te. Un patto redatto senza una sola domanda è sospetto: l'agente non conosce la persona con cui lavorerà.

Di chiusura:

Cosa gli sto chiedendo: che chiuda il patto con data e versione, e che lo agganci al file di progetto perché venga letto in ogni sessione. Senza quell'aggancio il patto esiste ma non agisce.

3. Risultato atteso

Un file docs/WORKING_AGREEMENT.md (o SQ.md, o CONTRATO.md) con:

• Data e versione.
• Ogni regola numerata, in una o due frasi, con il fallimento che evita.
• Le regole proprie del progetto, marcate come tali.
• Una riga in fondo che dica che l'agente propone modifiche ma non modifica il patto da solo.

E una riga nel file di progetto (PROJECT.md o CLAUDE.md) che ordini di leggerlo all'inizio di ogni sessione.

4. Verifica di completezza

• Ci sono le sei regole minime, ciascuna con il fallimento che evita?
• C'è qualche regola scritta come aspirazione ("cercare di…", "per quanto possibile…")? Se c'è, non serve: le regole si rispettano o no.
• Il file di progetto ordina di leggerlo in ogni sessione?
• L'agente ti ha fatto almeno una domanda su come lavori? Se ha redatto tutto senza chiedere niente, è sospetto: non ti conosce.

5. Segnali d'allarme

• Il patto ha più di venti regole. Nessuno, né umano né modello, rispetta venti regole; se ne rispettano sei o otto.
• Una regola dice "l'agente può modificare questo patto quando lo ritiene necessario". No.
• Due settimane dopo, l'agente fa qualcosa che il patto vieta e nessuno se ne accorge. Il patto non viene letto: controlla l'aggancio nel file di progetto.

Passo 2 — La definizione del progetto, l'albero semantico e la lettura obbligatoria (contratto del gradino)

Fase: avvio. Quando: si scrive una volta, dopo il patto; l'albero semantico e lo stato vivo si mantengono aggiornati per tutto il progetto, con ogni blocco e ogni decisione nuova. Forma: conversazione: l'agente redige, chiede ciò che manca, tu correggi. Dimensione: obbligatorio in ogni progetto. In uno piccolo, il file di progetto può avere cinquanta righe e l'albero semantico venti nodi; ciò che non possono è non esistere.

A cosa serve

Ogni sessione dell'agente parte da zero: non si ricorda di ieri. Dagli una mappa, corta, che gli dica cos'è il progetto, in che stato è e quali decisioni sono già state prese, e obbligalo a leggerla prima di toccare qualunque cosa. Il fallimento che evita è doppio: lavoro da buttare per non aver letto la mappa Ref. 9, e la mappa che cresce fino a diventare illeggibile Ref. 41. La regola pratica: il file di progetto è il programma, non lo storico. Ciò che è successo va da un'altra parte.

La mappa ha due pezzi, e il secondo è quello che fa più lavoro. Il primo è il file di progetto: cos'è il sistema, per chi, cosa NON è, le decisioni prese. Il secondo è l'albero semantico: il sistema scomposto come un albero, con i domini, e sotto ciascuno i suoi attori, i suoi processi (i casi d'uso), le sue entità con i loro stati, le sue schermate e le sue integrazioni; e da ogni nodo pendono le voci in sospeso e le decisioni che lo toccano. L'albero nasce dalla rilevazione che hai fatto con i metodi classici dell'ingegneria dei requisiti (interviste, casi d'uso, modello di dominio), lo costruisce l'agente, lo correggi tu, ed è ciò che dà al modello il contesto esatto del nodo che toccherà senza dover leggere tutto il progetto. Ed è ciò che permette a te di verificare, senza leggere codice, che il sistema che l'agente capisce sia quello che il business ha chiesto.

1. Contesto richiesto

Quello che segue è la lista generica. I file concreti che devi avere pronti prima di ogni prompt, con il loro contenuto e il loro stato minimo, stanno nella sezione 2, nel blocco "Prima di inviare il prompt" che precede ciascuno.

• Rilevazione del business: cosa fa il cliente, chi usa il sistema, che problema risolve, cosa non deve fare. Con le interviste, i casi d'uso o le storie utente che riesci a nominare, e le entità del business con i loro stati, anche se incompleti.
• Il patto di convivenza (gradino 1).
• Se esiste un sistema precedente: accesso in lettura al suo codice o alla sua documentazione.
• Le decisioni già prese, se ce ne sono, anche solo a voce.

2. Prompt

Iniziale:

Cosa gli sto chiedendo: che valuti la rilevazione e chieda prima di redigere; che il file di progetto sia corto (il tetto di trecento righe è arbitrario ma necessario: senza tetto, cresce); che dica esplicitamente cosa il sistema non è, perché ciò che non è detto è ciò che il modello inventerà; che le decisioni abbiano una data; che costruisca l'albero semantico con la struttura completa (domini, attori, casi d'uso con le loro parti, entità con stati e transizioni, schermate, integrazioni), che è il modello di dominio dell'ingegneria dei requisiti messo in forma di albero; che marchi ciò che ha inferito, perché è lì che si nascondono le invenzioni; e che separi lo stato vivo in un altro file, perché la mappa non si trasformi in storico.

Di chiusura:

Cosa gli sto chiedendo: le tue correzioni (soprattutto ai nodi che ha marcato come inferiti), la data, e due regole nuove nel patto: quella che protegge il file di progetto dal diventare storico, e quella che lega ogni voce in sospeso a un nodo dell'albero, che è ciò che mantiene l'albero vivo e ciò che ti permette di rilevare in dieci secondi una voce fuori perimetro.

3. Risultato atteso

• PROJECT.md (o CLAUDE.md): corto, di lettura obbligatoria, con cos'è, per chi, cosa non è, moduli, decisioni con data, e l'ordine di leggerlo insieme all'albero. Massimo trecento righe.
• docs/SEMANTIC_TREE.md: l'albero semantico, con i nodi inferiti marcati finché non li confermi, e, dal primo blocco, le voci in sospeso e le decisioni che pendono dai loro nodi.
• docs/STATUS.md: stato vivo, separato dai precedenti.
• In tutti e tre, una data di ultimo aggiornamento.
• Nel patto, le due regole nuove.

4. Verifica di completezza

• PROJECT.md sta in una lettura di cinque minuti? Se no, è sbagliato: è il programma, non lo storico.
• Dice esplicitamente cosa NON fa il sistema? (Ciò che manca è ciò che l'agente inventerà.)
• Percorri l'albero semantico come se fossi il cliente: ci sono tutti gli attori che conosci? Ogni entità ha gli stati che il business usa, né più né meno? C'è qualche nodo che non riconosci? Quello è un'invenzione: correggilo adesso.
• I nodi inferiti sono marcati? Li hai confermati o corretti tutti?
• Ogni decisione ha una data e chi l'ha presa?
• L'agente ha chiesto qualcosa sul business prima di redigere? Se non ha chiesto niente, controlla cosa ha supposto.
• Lo stato vivo è in un altro file?
• La prova di lettura: chiudi la sessione, aprine una nuova, e chiedigli cosa NON fa il sistema e da quale nodo dell'albero pende la tale schermata. Se risponde con la mappa, l'aggancio funziona.

5. Segnali d'allarme

• Il file di progetto è cresciuto più del 20 % in un mese. Sta entrando qualcosa che non è programma.
• L'agente inizia una sessione proponendo qualcosa che è già stato deciso ed è scritto. Non ha letto la mappa: l'aggancio di lettura obbligatoria è fallito.
• La sezione "cosa non è" è vuota o dice "niente in particolare". Ogni sistema ha dei limiti; se non sono scritti, il modello li attraverserà.
• Ci sono voci in sospeso che non pendono da nessun nodo dell'albero. O l'albero è rimasto vecchio o quelle voci sono fuori perimetro; entrambe le cose vanno guardate.
• Un'entità dell'albero ha uno stato che il business non ha mai nominato. Il modello l'ha inventato perché gli è sembrato logico, e ci costruirà sopra.

Passo 3 — Dimensionare prima di progettare l'architettura (contratto del gradino)

Fase: avvio. Quando: una volta, dopo la definizione e prima di montare lo scheletro; si rifà se il business cambia di scala. Forma: conversazione: l'agente calcola e presenta opzioni; tu scegli. Dimensione: obbligatorio sempre, ma proporzionale: in un progetto piccolo il dimensionamento può essere mezza pagina e una sola decisione ("sta in SQLite per anni"). Ciò che non può è non farsi, perché la domanda "quanto crescerà?" costa cinque minuti e la risposta sbagliata costa settimane.

A cosa serve

Prendi le decisioni strutturali —quale motore di database, se l'interfaccia è sincrona o asincrona, quanta concorrenza— con i numeri e non a gusto. È il gradino che costa più caro saltare, e lo dico con cognizione di causa: in uno dei miei sistemi sono partito con file JSON e quando ho misurato è risultato che avrebbe generato 3,4 milioni di righe all'anno; cambiare l'interfaccia dopo è costato un'intera tappa di reingegnerizzazione Ref. 15.

C'è un punto chiave che vale la pena tenere presente: ci sono dati che solo il business ha (quante entità, quanti eventi per entità, quanti operatori nel picco, quanto bisogna conservare) e il modello non li può inferire. Ciò che può inferire è il derivato. Per questo il prompt gli esige di valutare se i dati primari sono completi e di chiedere quelli che mancano, invece di stimarli con la faccia sicura. Chi sa cosa gli manca per calcolare è il modello, non un modulo da compilare.

E una seconda idea che voglio che tu porti via: le decisioni asimmetriche. Ci sono decisioni che costano pochissimo se le prendi e risultano inutili, e moltissimo se non le prendi e risultano necessarie. L'interfaccia di persistenza asincrona dalla riga uno è l'esempio canonico: se il motore finisce per essere sincrono, è avanzato un await; se finisce per essere asincrono e non l'hai previsto, bisogna riscrivere tutto. Quelle decisioni prendile sempre quando sono economiche, anche se oggi non servono.

1. Contesto richiesto

Quello che segue è la lista generica. I file concreti che devi avere pronti prima di ogni prompt, con il loro contenuto e il loro stato minimo, stanno nella sezione 2, nel blocco "Prima di inviare il prompt" che precede ciascuno.

• Rilevazione dei dati di volumetria del business, nominata così in forma generica: entità principali e loro crescita, eventi per entità, operatori simultanei e orario del picco, tempo di conservazione dei dati, carichi eccezionali (campagne, chiusure), crescita attesa. La rilevazione è per natura incompleta; l'agente valuta e chiede.
• Se c'è un sistema precedente: accesso in lettura al suo database per ricavare numeri reali invece di stime.
• PROJECT.md e l'albero semantico (gradino 2): le entità dell'albero sono quelle da dimensionare.

2. Prompt

Iniziale:

Cosa gli sto chiedendo, clausola per clausola: distinguere primari da derivati (è la distinzione che evita l'invenzione); chiedere i primari che mancano e non stimarli mai; usare numeri reali del sistema precedente quando esiste, con la loro fonte; calcolare il derivato con il conto in vista, perché tu possa rifarlo; lo scenario "per dieci", che è ciò che rivela cosa si rompe per primo; tre opzioni con il costo di migrare tra di esse, perché la decisione non è solo "quale" ma "quanto costa sbagliare"; e che non scelga né scriva codice, perché questo gradino è di decisione, non di costruzione.

Di chiusura:

Cosa gli sto chiedendo: il registro completo, con fonti e conti; quella scelta e la ragione; e le decisioni asimmetriche scritte, perché se restano implicite non si rispettano.

3. Risultato atteso

Un file docs/SIZING.md con:

• Data e chi ha deciso.
• Tabella dei dati primari: valore, fonte (riferito dal business / misurato nel sistema precedente), data. Nessuno con fonte "supposizione".
• Tabella dei dati derivati: valore, da quali primari viene, il conto.
• Lo scenario "per dieci": cosa si rompe per primo.
• Le tre opzioni numerate, con il costo di migrare tra di esse.
• Quella scelta e la ragione, in una o due frasi.
• Le decisioni asimmetriche, elencate.
• Le domande che l'agente ha fatto e le risposte.

4. Verifica di completezza

• C'è qualche dato primario con fonte "supposizione" o senza fonte? Se c'è, il gradino non è salito: l'agente doveva chiederlo.
• Ogni dato derivato mostra da quali primari viene e con quale conto? Puoi rifare un conto a mano e ti torna?
• Ci sono tre opzioni e una scelta con ragione scritta?
• Dice cosa succede se la volumetria si moltiplica per dieci?
• Le decisioni asimmetriche sono scritte, o sono rimaste implicite?
• L'agente ha chiesto? Se ha presentato numeri senza aver fatto una sola domanda, diffida.

5. Segnali d'allarme

• I tre scenari delle opzioni portano alla stessa conclusione. L'agente aveva già scelto e ha montato le altre due per adempiere.
• Un numero derivato ha più precisione dei primari da cui viene ("1.234.567 righe" a partire da "circa 5.000 famiglie"). La precisione è falsa.
• Lo scenario "per dieci" dice "non succede niente". Succede sempre qualcosa; se non l'ha trovato, non l'ha cercato.

Passo 4 — Lo scheletro con i suoi cancelli (contratto del gradino)

Fase: avvio. Quando: una volta, alla chiusura dell'avvio, dopo il dimensionamento e prima di qualunque funzionalità. È qui che si fa tutta l'infrastruttura iniziale e la catena di integrazione e deployment. Forma: un solo invio lungo, con approvazione visiva tua alla fine. Dimensione: obbligatorio in ogni progetto che avrà utenti. In un prototipo usa e getta si può saltare; ma se il prototipo sopravvive (sopravvivono sempre), questo gradino è la prima cosa da pagare.

A cosa serve

Fa' che il sistema parta, si provi e si distribuisca VUOTO prima di avere funzionalità. Scoprire il deployment alla fine è carissimo: in uno dei miei sistemi è arrivato un mese dopo l'avvio ed è costato cinque voci in sospeso di fila Ref. 32. Se lo scheletro si distribuisce nell'avvio, quei colpi si prendono con zero funzionalità in gioco.

L'idea generale dietro: la strada verso la produzione è parte del prodotto, non una pratica della fine. Un sistema che funziona sulla macchina del programmatore e non si può distribuire non è un sistema; è una demo. E l'unico modo di sapere che la strada funziona è percorrerla quando ancora non c'è niente da perdere. Per questo in questo gradino si monta tutto ciò che poi userà il ciclo: il repository con la sua struttura, l'ambiente di test, l'integrazione continua che esegue la batteria a ogni push, e il deployment automatico all'ambiente di test.

1. Contesto richiesto

Quello che segue è la lista generica. I file concreti che devi avere pronti prima di ogni prompt, con il loro contenuto e il loro stato minimo, stanno nella sezione 2, nel blocco "Prima di inviare il prompt" che precede ciascuno.

• docs/SIZING.md (gradino 3): l'opzione scelta definisce lo scheletro.
• Rilevazione degli ambienti: dove girerà (cloud, server proprio), se c'è un ambiente di test e uno di produzione, chi ha accesso, come si distribuisce oggi se c'è qualcosa.
• Le credenziali del posto in cui si distribuirà, anche se è un servizio gratuito.
• Il tipo di progetto: nuovo, correzione o evoluzione di qualcosa di esistente.

2. Prompt

Iniziale:

Cosa gli sto chiedendo: che verifichi di avere gli accessi prima di cominciare (senza quello lo scheletro resta sulla macchina dell'agente); la lista esatta di ciò che è uno scheletro (struttura, avvio, un test, integrazione continua, deployment in test); i cancelli scritti; uno screenshot reale dell'ambiente di test, che è l'unica prova valida che è stato distribuito; e il divieto esplicito di aggiungere funzionalità, perché il modello tende al "già che ci sono" e quello rompe il perimetro esatto.

Di chiusura:

Cosa gli sto chiedendo: lasciare i tre comandi dove la prossima sessione li troverà, e provare che il deployment è ripetibile (eseguirlo due volte senza rompere niente). Quella seconda esecuzione è la prova che la procedura è una procedura e non una fortuna.

3. Risultato atteso

• Il repository con la struttura, il server e la schermata che partono.
• Un test di fumo in verde e la batteria che gira in integrazione continua (con il link all'esecuzione in verde).
• Il deployment all'ambiente di test funzionante, con l'URL, ed eseguito due volte.
• docs/GATES.md: la lista dei cancelli, ciascuno con la condizione per passare.
• Uno screenshot del sistema vuoto che gira nell'ambiente di test.
• docs/STATUS.md aggiornato con i tre comandi (eseguire, testare, distribuire).

4. Verifica di completezza

• Puoi aprire l'URL dell'ambiente di test e vedere la schermata vuota? (Lo fai tu, non l'agente.)
• C'è un link a un'esecuzione di integrazione continua in verde?
• Il deployment è stato eseguito due volte e la seconda non ha rotto niente?
• I cancelli sono scritti con una condizione verificabile ciascuno?
• C'è qualche funzionalità che non hai chiesto? Se c'è, l'agente ha violato il perimetro esatto.

5. Segnali d'allarme

• Lo scheletro "funziona in locale" ma il deployment "lo vediamo dopo". No: il deployment è lo scheletro.
• Lo screenshot è della macchina dell'agente, non dell'ambiente di test. Chiedi l'URL.
• I cancelli dicono cose come "il codice ha buona qualità". Un cancello è una condizione verificabile: "la batteria è in verde", "il deployment in test ha funzionato".

Passo 5 — Il piano sono le voci in sospeso: la specifica dettagliata vive in ciascuna (contratto del gradino)

Fase: ciclo. Quando: il registro si crea all'apertura del primo blocco funzionale, appena finisce l'avvio; ogni blocco nuovo parte convertendo la richiesta del cliente in voci in sospeso specificate; la routine si usa in ogni sessione per tutto il progetto; la documentazione della voce fatta si scrive alla sua chiusura, nella stessa sessione. Forma: un solo invio all'apertura di ogni blocco; poi, routine di ogni sessione. Dimensione: obbligatorio in ogni progetto. È il gradino che rende seguibili tutti gli altri: senza voci in sospeso numerate e specificate non c'è dove appendere né la specifica né la prova.

A cosa serve

Abbi una sola coda di lavoro, con ordine e con cancello, che sia la verità del progetto. Non c'è "piano" da una parte e "compiti" dall'altra: la lista delle voci in sospeso È il piano. Evita la specifica lunga che viene superata in due settimane e resta obsoleta Ref. 17, e il lavoro di cui nessuno sa perché è stato fatto Ref. 7.

Ma c'è di più, ed è ciò che distingue questo gradino da una lista di compiti qualunque. Nel metodo classico esisteva un documento di specifica dei requisiti, lungo, che descriveva tutto ciò che il sistema doveva fare e che invecchiava prima di essere finito. Qui quel documento si scompone: la specifica dettagliata vive in ogni voce in sospeso. Una voce ben scritta 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 interessate, con il prototipo se c'è; i casi limite e le eccezioni; i criteri di accettazione nella forma "dato, quando, allora"; e come si verifica. La somma delle voci in sospeso è la specifica del sistema, e la tracciabilità (requisito → voce → test → commit) non è una matrice a parte: è la voce stessa.

E la terza cosa, che chiude il cerchio: le voci in sospeso chiuse sono documentazione. Quando una voce si chiude, non si cancella né si archivia vuota: resta con la sua specifica, la decisione che l'ha originata, la prova con cui è stata chiusa (i numeri del rosso e del verde, lo screenshot, il numero misurato), il commit e la data. La coda delle voci chiuse è lo storico funzionale del sistema: cosa è stato costruito, perché, quando e come è stato provato. Da lì escono il diario delle modifiche, le sezioni nuove del manuale, e la risposta a "perché il sistema fa questo?" sei mesi dopo.

1. Contesto richiesto

Quello che segue è la lista generica. I file concreti che devi avere pronti prima di ogni prompt, con il loro contenuto e il loro stato minimo, stanno nella sezione 2, nel blocco "Prima di inviare il prompt" che precede ciascuno.

• La richiesta del cliente per il blocco, in prosa, così come la direbbe lui, con le sue ambiguità. Se nell'acquisizione hai fatto casi d'uso o storie utente, meglio: sono l'unità naturale di un blocco.
• L'albero semantico (gradino 2), per appendere ogni voce al suo nodo.
• Gli audit e i rilievi delle prove umane, se ce ne sono già stati.
• PROJECT.md e docs/STATUS.md.

2. Prompt

Per aprire un blocco:

Cosa gli sto chiedendo: che converta la richiesta in voci verificabili e che chieda quando la richiesta non permette di scriverne una verificabile (l'ambiguità si risolve chiedendo, non scegliendo); la specifica completa di ogni voce, campo per campo, che è l'ingegneria dei requisiti classica scomposta in unità piccole; il nodo dell'albero da cui pende, che è ciò che ti permette di rilevare una voce fuori perimetro; le regole di business con la loro decisione o marcate come mancanti, che è l'aggancio con il gradino 6; i criteri di accettazione nella forma classica, che sono il copione del test end to end del gradino 8; e un ordine proposto con la sua ragione, perché tu lo confermi o lo cambi.

Routine di ogni sessione (va nel patto di convivenza):

Cosa gli sto chiedendo: la disciplina di ogni sessione: annunciare cosa si prende e rileggere la specifica (l'agente parte senza memoria, e la specifica è la sua memoria della voce), citare la voce in ogni commit, chiudere con prova, documentare la voce fatta nello stesso registro, e annotare invece di fare ciò che compare fuori dalla lista. Quest'ultima clausola è quella che protegge il perimetro esatto quando il modello "vede qualcos'altro".

3. Risultato atteso

docs/PENDING.md (o lo strumento che usa il tuo progetto) con, per voce:

• Numero, titolo, stato (aperta / in corso / chiusa), data di apertura e di chiusura.
• Il nodo dell'albero semantico.
• La storia o il caso d'uso di origine, con le parole del cliente.
• La specifica dettagliata: descrizione, regole di business con decisione e data, dati, schermate, casi limite, criteri di accettazione, come si verifica.
• Alla chiusura: la prova, il commit, la data, le decisioni prese lungo la strada.

E la routine nel patto di convivenza.

4. Verifica di completezza

• Leggi la specifica di una voce a caso come se fossi il cliente: descrive ciò che hai chiesto, con le tue parole di origine? I criteri di accettazione sono quelli che useresti tu per dire "va bene"? C'è un caso limite che conosci e non c'è?
• Ogni voce pende da un nodo dell'albero? Ce n'è qualcuna appesa a un nodo che non riconosci?
• Ogni voce dice come si verifica? Una voce senza verifica non si può chiudere.
• Ci sono regole di business marcate come "mancante, chiesta" che non ti hanno chiesto?
• Ci sono voci "chiuse" senza prova né commit? Se ci sono, riaprile. 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 che non ha una voce? Lì l'agente è uscito dal perimetro.

5. Segnali d'allarme

• Una voce è "in corso" da più di tre sessioni. O sono tre voci, o è bloccata da una decisione che nessuno ha preso (gradino 6).
• Ci sono più voci chiuse in un giorno che commit quel giorno. Si stanno chiudendo senza prova.
• Le specifiche sono di una riga. L'agente le ha scritte per adempiere, non per costruirci sopra; inventerà ciò che manca nel momento di costruire.
• La lista ha più di cinquanta voci aperte. Non è un piano, è un inventario di ansie: bisogna dare priorità e archiviare.
• Qualcuno chiede perché il sistema fa una certa cosa e la risposta non è in nessuna voce chiusa. La documentazione del fatto non si sta scrivendo.

Passo 6 — Le decisioni si scrivono accanto al codice (contratto del gradino)

Fase: ciclo. Quando: in ogni sessione del ciclo, ogni volta che l'agente si imbatte in una regola di business non scritta o in una biforcazione che cambia ciò che l'utente vede. Di solito sono due o tre per blocco. Anche nell'avvio (gradini 0 e 3) e nell'uscita in produzione (14 e 15). Forma: conversazione breve: l'agente rileva che c'è una decisione, chiede, e la lascia scritta. Dimensione: obbligatorio in ogni progetto. In uno piccolo il registro può essere una tabella di dieci righe; ciò che conta è che le regole di business abbiano un proprietario.

A cosa serve

Fa' che ogni regola di business e ogni decisione strutturale abbia proprietario, data e luogo. Altrimenti, in sei settimane nessuno sa se "approvata più saldo torna in coda" è stata una decisione del cliente o un'idea dell'agente. Ed evita il peggio: l'agente che inventa regole di dominio perché gli sono sembrate ragionevoli.

Questo ha una conseguenza che voglio dire ad alta voce: il modello, quando si trova davanti a un buco nelle regole, lo riempie. Non si ferma; completa con ciò che gli sembra più probabile, e lo fa con la stessa naturalezza con cui scrive il resto. Per questo la routine di questo gradino non è "scrivi le decisioni" ma "fermati e chiedi quando ne manca una". La seconda è la parte difficile, ed è ciò che bisogna esigere nel patto. La pratica di lasciare la regola scritta nel commit, con le mie parole e la data, l'ho imposta alla Mutua Ref. 29, e quella di congelare le decisioni prima di costruire viene dal mio strumento Ref. 5.

1. Contesto richiesto

Quello che segue è la lista generica. I file concreti che devi avere pronti prima di ogni prompt, con il loro contenuto e il loro stato minimo, stanno nella sezione 2, nel blocco "Prima di inviare il prompt" che precede ciascuno.

• La conversazione con il proprietario: è l'unico contesto. L'agente non può decidere regole di business.
• Un luogo concordato dove si scrivono le decisioni: il messaggio del commit, la specifica della voce in sospeso, e un registro docs/DECISIONS.md.

2. Prompt

Routine (va nel patto di convivenza):

Cosa gli sto chiedendo: che si fermi davanti a una regola non scritta o a una biforcazione visibile; che chieda con raccomandazione e alternativa (perché tu decida in dieci secondi, non in dieci minuti); che registri la decisione con le tue parole testuali nei tre posti (il commit, la voce in sospeso, il registro), non con una parafrasi "migliorata"; e, per quando non rispondi, l'opzione più reversibile marcata come "per omissione", che è ciò che permette di proseguire senza che la decisione sparisca.

Di chiusura (ogni decisione):

Cosa gli sto chiedendo: il formato minimo di una decisione: la regola testuale, chi, quando. Tre cose; senza una delle tre non è una decisione registrata.

3. Risultato atteso

• docs/DECISIONS.md: una riga o un paragrafo per decisione, con data, chi ha deciso, la frase testuale, la voce in sospeso o il commit in cui è stata applicata, e se è stata "per omissione".
• Nella specifica di ogni voce in sospeso interessata: la regola con la sua decisione e data.
• In ogni commit che implementa una regola di business: la frase di origine.

4. Verifica di completezza

• Apri tre commit che toccano regole di business: ciascuno cita chi ha deciso e quando?
• Ci sono decisioni "per omissione" senza conferma? Confermale o annullale; non lasciarle.
• C'è qualche regola nel sistema che non riconosci come tua? Se c'è, l'agente l'ha inventata: è un fallimento del gradino, si scrive come voce in sospeso e si rivede.
• Le frasi sono testuali o "migliorate" dall'agente? Devono essere le tue.

5. Segnali d'allarme

• È passata una settimana di lavoro e il registro delle decisioni non è cresciuto. O il lavoro è stato puramente meccanico (raro) o l'agente ha deciso da solo.
• Le decisioni registrate sono tutte redatte con lo stesso stile levigato. Sono parafrasi dell'agente, non le tue parole.
• Un utente del sistema chiede "perché fa questo?" e nessuno trova la decisione.

Passo 7 — Misurare prima di costruire, con uno strumento che a sua volta si verifica (contratto del gradino)

Fase: ciclo. Quando: ogni volta che una voce in sospeso dipende da un numero o da un'ipotesi di causa, PRIMA di costruire. Nell'avvio, il dimensionamento è il primo caso. In un progetto piccolo, "misurare" è contare con un comando e annotare il numero con la data. Forma: un solo invio per misurazione; a volte una conversazione quando l'ipotesi è tua. Dimensione: proporzionale. Il cricchetto e il budget di query sono per sistemi con volume. Ciò che non cambia con la dimensione: nessun numero che decide qualcosa esce da un'impressione.

A cosa serve

Fai in modo che ogni numero che alimenta una decisione esca da un programma con test, e non da una ricerca di testo, da un'impressione, né da "mi sembra che siano un centinaio". E fai in modo che lo strumento stesso venga sottoposto ad audit, perché i misuratori mentono: uno dei miei non vedeva 84 chiamate con il contatore a zero, e un altro diceva 27 quando erano 44 Ref. 35, Ref. 36. Le cinque regole che ho scritto dopo quell'episodio sono: misuratore con guardia; se lo strumento non esiste si costruisce; si fa l'audit in due direzioni; l'approssimato si marca; e chi esegue verifica i numeri di chi ha pianificato.

Questo è il gradino che ho impiegato più tempo a formalizzare, e per una ragione che vale la pena raccontare: davo per scontato che un modello applicasse da solo qualcosa di così basilare nell'ingegneria come "misura prima di toccare". Non lo applica. Il modello è bravissimo a produrre affermazioni con un numero ("ci sono circa 120 cicli di quel tipo") e quelle affermazioni suonano esattamente uguali quando sono misurate e quando sono stimate. Non hai modo di distinguerle dal tono. L'unico modo è esigere lo strumento: "con cosa l'hai misurato? mostrami il comando". Se non c'è comando, è un'impressione, per quanti decimali abbia. Le regole le ho imposte io in sessione, correggendo l'agente, prima che diventassero dottrina Ref. 45.

1. Contesto richiesto

Quello che segue è la lista generica. I file concreti che devi avere pronti prima di ogni prompt, con il loro contenuto e il loro stato minimo, stanno nella sezione 2, nel blocco "Prima di inviare il prompt" che precede ciascuno.

• L'ipotesi, tua o dell'agente: "credo che il problema sia X", "dovrebbero essere un centinaio".
• Accesso a ciò che si vuole misurare: il codice, il database in sola lettura, il log.
• I misuratori che già esistono nel repository, se ce ne sono.

2. Prompt

Iniziale:

Cosa gli sto chiedendo, clausola per clausola: il misuratore nel repository (non un comando sciolto che si perde); il test del misuratore contro un caso noto (la guardia); la clausola di completezza nella sua forma per misurare (chiedere l'accesso, non approssimare in silenzio); marcare l'approssimato con il suo margine; il numero con il comando che lo produce, perché tu possa eseguirlo; l'audit in due direzioni, che è ciò che ha smascherato i miei due misuratori che mentivano; e l'ordine: prima misurare, poi proporre.

Quando c'è un budget:

Cosa gli sto chiedendo: che il budget sia il misurato più poco, non un numero tondo, e che abbia un test che fallisca se viene superato. Così una regressione di prestazioni compare nella batteria e non in produzione Ref. 37.

Quando chi ha pianificato ha dato numeri (regola cinque):

Cosa gli sto chiedendo: che chi esegue non si fidi dei numeri di chi ha pianificato, anche se è lo stesso modello in un'altra sessione. Nel mio caso, tre affermazioni su quattro del piano erano sbagliate; dove c'era uno strumento, il numero era esatto.

3. Risultato atteso

• Il misuratore nel repository (tools/measure_*.py, scripts/meter-*.mjs o simile), con il suo test.
• Il numero, con il comando che lo produce e la data.
• L'audit in due direzioni, scritto in due o tre righe.
• L'approssimato marcato come tale, con il suo margine.
• Se c'è un budget: il valore, il margine, e il test che lo protegge.
• Nel commit: "measured: [number] with [meter]".

4. Verifica di completezza

• Puoi eseguire tu il comando del misuratore e ti dà lo stesso numero? (Lo esegui tu; non serve capirlo, solo eseguirlo.)
• Il misuratore ha un test? Contro quale caso noto?
• C'è qualche numero nel rapporto senza un misuratore dietro? Chiedi da dove è uscito.
• L'approssimato è marcato?
• Se il piano portava numeri, l'agente li ha verificati prima di eseguire e ti ha detto quali non tornavano?

5. Segnali d'allarme

• Un numero è cambiato tra due rapporti senza che il codice cambiasse. Uno dei due non è stato misurato.
• Il misuratore dà zero. Non è quasi mai zero; quasi sempre il misuratore non sta vedendo qualcosa.
• L'agente propone di costruire "mentre misura", per guadagnare tempo. L'ordine è il metodo: prima il numero, poi il piano.

Passo 8 — I test come lucchetti, provati in rosso (contratto del gradino)

Fase: ciclo. Quando: con ogni voce in sospeso, alla sua chiusura: il test in rosso e in verde, la regressione dei vicini e il test end to end del flusso toccato. La batteria completa end to end di tutti i flussi, alla chiusura di ogni blocco e prima di ogni deployment in produzione. Forma: un solo invio; l'agente esegue e riporta, tu leggi il rapporto. Dimensione: obbligatorio in ogni progetto. È il cuore del metodo: se c'è un gradino che non si può negoziare, è questo.

A cosa serve

Un test che non hai mai visto fallire non sai se prova qualcosa. La regola qui non è "scrivi test": è "dimostra che il test va in rosso contro il codice vecchio, e poi in verde con quello nuovo". Evita i test che passano perché non provano niente, e il verde che nasconde un bug Ref. 44.

Perché questo è più importante con un modello che con un programmatore umano: il modello scrive il codice e il test nella stessa sessione, con la stessa comprensione. Se ha capito male la richiesta, il test proverà ciò che ha capito, e passerà. Il rosso contro il codice vecchio è l'unico modo economico di verificare che il test stia guardando ciò che conta: se il codice vecchio lo passa, il test non distingue il prima dal dopo, e allora non serve. Il caso che lo mostra meglio è quello dei contatori che non coincidevano Ref. 26.

C'è un'obiezione seria a questo gradino, e la voglio lasciare scritta perché la useranno contro: lo stesso agente che scrive il test e il codice può fingere il rosso. Uno studio pubblicato nell'agosto del 2026 ha misurato che, quando a un agente si chiede il ciclo "prima il test", a volte salta il rosso, lo racconta senza averlo eseguito, o implementa prima del test perché passi al primo colpo (sta nella Parte F del documento principale, quella dei lavori correlati). La mia risposta ha tre pezzi, e tutti e tre stanno nella scala. Il primo, qui: il rosso non è un racconto, è una ricevuta: il comando esatto, l'identificatore della versione contro cui è stato eseguito, il numero di test che falliscono e il codice di uscita, tutto incollato così com'è uscito, in modo che tu possa eseguirlo di nuovo con un solo comando senza capire cosa fa. Il secondo, nel gradino 13: l'audit da parte di un'altra sessione esegue di nuovo un campione di quelle ricevute. Il terzo, nel gradino 9: i test di mutazione, che piantano errori di proposito e contano quanti ne catturano i test; è l'unica misura che, in quello stesso studio, ha distinto i test che sorvegliano da quelli che decorano.

E la seconda metà: i test 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 su tre scale: il flusso toccato con ogni voce, tutti i flussi alla chiusura di ogni blocco, e tutti i flussi con la versione esatta prima della produzione.

1. Contesto richiesto

Quello che segue è la lista generica. I file concreti che devi avere pronti prima di ogni prompt, con il loro contenuto e il loro stato minimo, stanno nella sezione 2, nel blocco "Prima di inviare il prompt" che precede ciascuno.

• La modifica già implementata (per default i test vengono dopo l'implementazione; "prima il test" resta come opzione per perimetri piccoli e ben definiti).
• La voce in sospeso che origina la modifica, con i suoi criteri di accettazione e il suo "come si verifica".
• La batteria esistente e il comando per eseguirla (gradino 4).

2. Prompt

Routine (va nel patto di convivenza; si applica a ogni modifica):

Il rosso del primo blocco. Nel primo blocco di un progetto nuovo non c'è codice precedente: il test nuovo fallisce perché il modulo non esiste, e quel fallimento non prova che il test distingua un comportamento. Per questo, 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 del difetto, così vedi che non era banale), lo annulla e mostra il verde. Un solo mutante per elemento in sospeso, eseguito e registrato come qualsiasi altra ricevuta; i test di mutazione su tutta la base restano il rinforzo opzionale del gradino 9. (Decisione D-037, dalla pratica Turnera: sei ricevute di rosso che dicevano solo "il file non si carica".)

Cosa gli sto chiedendo, clausola per clausola: (1) il test, guidato dai criteri di accettazione della voce; (2) il rosso dimostrato come ricevuta (comando, versione, numeri, codice di uscita), che è la clausola che distingue questo metodo da "scrivi test" e quella che impedisce al rosso di essere un racconto; (3) il verde; (4) la regressione dei vicini nella stessa sessione, perché una modifica rompe cose accanto; (5) il test end to end del flusso toccato, con l'effetto nel backend in vista; (6) non simulare proprio ciò che si prova; e la clausola di completezza adattata a questo gradino: se manca qualcosa per provare end to end, chiederlo, non simularlo. Il messaggio di commit con i numeri lascia la prova dove vive il codice.

Alla chiusura di ogni blocco e prima di ogni deployment in produzione:

Cosa gli sto chiedendo: la seconda e la terza scala dei test end to end, con la versione esatta (non "l'ultima"), con l'effetto nel backend per flusso, e con la clausola di completezza: ciò che non è coperto si dichiara e diventa voce in sospeso, non si fa passare per coperto.

Quando l'agente dice che non si può provare:

Cosa gli sto chiedendo: che "non si può provare" non sia la fine della conversazione ma l'inizio di una voce in sospeso. La non testabilità è debito, e il debito si registra.

3. Risultato atteso

• Il test nuovo nel repository, nominato con la voce in sospeso che chiude.
• Nel rapporto dell'agente e nel messaggio del commit: l'output in rosso come ricevuta (il comando, la versione contro cui è stato eseguito, quanti falliscono, il codice di uscita), l'output in verde, e la regressione in verde con i suoi numeri.
• Il test end to end del flusso toccato, con la prova che il backend è cambiato (la riga, il record, lo stato).
• Alla chiusura di ogni blocco e prima della produzione: la batteria completa end to end in verde, per flusso, con la versione esatta.

4. Verifica di completezza

• Il rapporto mostra il rosso? Con numeri: "4 su 8 falliscono contro il criterio vecchio". Se mostra solo verde, il gradino non è salito.
• Il rosso è una ricevuta o un racconto? Deve avere il comando esatto, la versione contro cui è stato eseguito, i numeri e il codice di uscita. Una volta per blocco, scegli una voce in sospeso a caso ed esegui tu quel comando: il rosso deve ricomparire.
• La regressione è stata eseguita nella stessa sessione? Quanti test, quanti in verde?
• C'è qualche parte "simulata" (mock) proprio dove sta la modifica? Chiedi all'agente cosa ha simulato e perché.
• Il commit cita la voce in sospeso e dice "provato in rosso"?
• Il test di schermata verifica anche l'effetto nel backend?
• Alla chiusura del blocco: ci sono tutti i flussi nella batteria end to end, o ce n'è qualcuno che "si copre con gli unitari"?

5. Segnali d'allarme

• Tutti i test nuovi della settimana sono passati in verde al primo colpo, e non si è mai mostrato un rosso. O l'agente sta omettendo il passo o i test non provano niente.
• La batteria ci mette sempre di più e nessuno sa perché. Di solito è che i test end to end sono stati sostituiti via via da simulazioni "perché giri veloce".
• L'agente riporta "i test passano" senza dire quanti. Sempre con i numeri.
• Il rosso arriva raccontato in prosa ("il test è fallito come previsto") senza comando, senza versione e senza numeri. Un rosso senza ricevuta vale quanto nessuno.
• Arrivi all'uscita in produzione e la batteria completa end to end si esegue per la prima volta. Sono mancate le chiusure di blocco.

Passo 9 — Qualità del codice verificata dalla macchina, con cancello (contratto del gradino)

Fase: ciclo. Quando: si monta una volta, all'apertura del primo blocco funzionale (appena finisce l'avvio), e da allora gira da solo a ogni commit, come cancello dell'integrazione continua; ogni voce in sospeso si chiude con la qualità in verde, dopo il test in rosso (8) e prima del caso di prova manuale (10). Alla chiusura di ogni blocco e prima di ogni deployment, il rapporto di qualità si legge con il proprietario. In un legacy, la prima esecuzione è la linea base e i rilievi entrano nel backlog con la loro marca di velocità. Forma: un solo invio per montarlo; poi, routine di ogni modifica e lettura per blocco. Dimensione: obbligatorio nel suo livello minimo in ogni progetto (un linter e un limite di dimensione nella catena); completo, test di mutazione inclusi, in qualunque progetto con utenti. I test di mutazione restano un rinforzo opzionale solo senza utenti reali (uno strumento interno, un prototipo che nessun altro esegue).

A cosa serve

Il proprietario non legge il codice, e quello è il punto del metodo. Ma il codice esiste, lo manterrà qualcuno (il prossimo agente, il prossimo sviluppatore), e un codice che oggi funziona e domani è illeggibile è debito che si paga al terzo mese. Se nessuno lo legge, lo deve guardare una macchina: strumenti che, a ogni commit, misurano ciò che guarderebbe un revisore umano e lo convertono in un numero con un limite. Io l'ho fatto in tutti i miei progetti, senza chiamarlo gradino, e un audit di qualità mi ha restituito un componente di più di duemila righe e un file di progetto di quasi diecimila Ref. 41: nessuno dei due avrebbe superato un limite di dimensione scritto. Il cricchetto statico, che impedisce a un numero di qualità di peggiorare Ref. 35, è la forma che do a questo gradino.

Ciò che si misura a macchina, in ordine di importanza: che il codice rispetti uno stile unico (il linter e il formattatore); che nessuna funzione e nessun file superi una dimensione; che la complessità di ogni funzione resti sotto un limite; che non ci sia codice duplicato né codice morto; che le dipendenze siano dichiarate e usate; che la copertura dei test non scenda mai (il cricchetto); e, se il linguaggio lo permette, che i tipi tornino. Niente di tutto questo sostituisce il test in rosso: un codice impeccabile può essere sbagliato. Ciò che evita è il codice corretto che nessuno può più toccare.

E ciò che smetto di trattare come rinforzo opzionale in qualunque progetto con utenti: i test di mutazione. Li avevo lasciati come "opzionali, raccomandati" in una versione precedente di questo documento, e una valutazione esterna del metodo mi ha fatto notare la contraddizione: se la Parte F dice che la mutazione è, per quanto ne so, l'unica misura che negli studi del 2026 ha distinto i test che provano da quelli che decorano, non ha senso lasciarla fuori dal "completo" proprio nei progetti dove un test decorativo in più fa danno a qualcuno. Uno strumento pianta errori di proposito nel codice (cambia un "maggiore" in "maggiore o uguale", cancella una riga, inverte una condizione) ed esegue i test; ogni errore che i test non catturano è un mutante che sopravvive, e la proporzione di quelli catturati è il punteggio. È la misura che completa il rosso dimostrato del gradino 8: il rosso prova che un test sorveglia la modifica di oggi; la mutazione misura quanto sorveglia la batteria intera. Ed è, per quanto ne so, l'unica che negli studi del 2026 ha distinto i test che provano da quelli che decorano (Parte F del documento principale).

Se sei alle prime armi. Un linter è un programma che legge il codice e segnala ciò che è scritto male o è pericoloso (una variabile che non si usa, un confronto che dà sempre lo stesso risultato), come il correttore ortografico di un elaboratore di testi. Un formattatore lo sistema con uno stile unico (rientri, spazi) perché tutto il codice sembri scritto dalla stessa mano. La complessità di una funzione è quanti percorsi diversi può prendere (ogni "se" la aumenta); una funzione con quaranta percorsi non la capisce nessuno. Codice duplicato è lo stesso blocco copiato in due posti: il giorno in cui se ne sistema uno, l'altro resta sbagliato. La copertura è quale percentuale del codice viene eseguita da qualche test. E un cricchetto è un meccanismo che lascia solo migliorare: il numero di oggi è il pavimento di domani. I test di mutazione sono un programma che rompe il codice di proposito, una piccola modifica alla volta, e guarda se qualche test se ne accorge; se nessuno se ne accorge, quel pezzo di codice non è sorvegliato.

1. Contesto richiesto

Quello che segue è la lista generica. I file concreti che devi avere pronti prima di ogni prompt, con il loro contenuto e il loro stato minimo, stanno nella sezione 2, nel blocco "Prima di inviare il prompt" che precede ciascuno.

• L'integrazione continua che gira a ogni push (gradino 4).
• Il primo blocco funzionale aperto, con almeno una voce in sospeso costruita: senza codice non c'è qualità da misurare.
• La tua decisione sui limiti, o la disponibilità ad accettare quelli che l'agente propone, con la loro ragione.
• L'audit precedente (13, o N3 in un legacy), se c'è stato.

2. Prompt

Iniziale (montare il cancello):

Cosa gli sto chiedendo: le cinque verifiche che farebbe un revisore umano, fatte a macchina e con la costruzione in rosso come conseguenza, perché una verifica che non blocca è un consiglio; i limiti con il loro valore misurato, perché il limite esca dal numero e non da un'opinione; il cricchetto di copertura, che è il pezzo che fa sì che la qualità non si degradi da sola; e non sistemare ancora niente, perché in un sistema con codice già scritto la prima esecuzione dà sempre rosso e la decisione su cosa si sistema adesso e cosa si tollera con una data è mia.

Routine (va nel patto di convivenza):

Cosa gli sto chiedendo: che la qualità sia parte della chiusura di ogni voce in sospeso e non un compito a parte; il divieto di zittire (un modello davanti a un linter in rosso tende ad aggiungere l'eccezione invece di sistemare, perché è più veloce) e di alzare il limite; e la lettura per blocco, che è l'unico momento in cui i numeri li guardi tu.

Obbligatorio in qualunque progetto con utenti (opzionale solo senza utenti reali): test di mutazione.

Cosa gli sto chiedendo: la misura che la copertura non dà (la copertura dice quale codice è stato eseguito; la mutazione dice quale codice è sorvegliato); la portata limitata alle righe cambiate, che è ciò che rende il costo pagabile a ogni voce in sospeso; non sistemare ancora niente, perché decidere quale mutante conta spetta a me; e il punteggio alla chiusura di ogni blocco, accanto alla copertura, con un calo trattato come rosso.

3. Risultato atteso

• Il linter, il formattatore, i limiti, il rilevamento di duplicazione e codice morto, la copertura con cricchetto e i tipi, che girano a ogni push e vanno in rosso quando serve.
• docs/CODE_QUALITY.md con strumenti, configurazione, limiti con valore misurato, e la lista di ciò che fallisce con la sua voce in sospeso o la sua data.
• Il cancello in docs/GATES.md e la routine nel patto.
• In qualunque progetto con utenti: il punteggio di mutazione in docs/CODE_QUALITY.md, per blocco, accanto alla copertura, e una voce in sospeso per ogni mutante che sopravvive in codice che conta.

4. Verifica di completezza (la fai tu, senza leggere codice)

• Chiedigli il link all'ultima esecuzione della catena: la qualità è in verde?
• Chiedigli di inserire apposta, in un ramo, una funzione di cento righe e una variabile senza uso: la catena va in rosso per entrambe le cose?
• La copertura di oggi è maggiore o uguale a quella della chiusura del blocco precedente? Chiedi i due numeri.
• C'è qualche eccezione al linter nel codice? Chiedigli la lista; ciascuna deve avere la sua ragione scritta.
• È salito qualche limite dalla prima esecuzione? Con quale ragione e chi l'ha deciso?
• Se il progetto ha utenti reali: i test di mutazione stanno girando? Se no, quale ragione scritta giustifica non averli?
• Se ci sono test di mutazione: quanti mutanti sono sopravvissuti nell'ultimo blocco, e ciascuno ha la sua voce in sospeso o la sua ragione scritta?

5. Segnali d'allarme

• La qualità è passata in verde al primo colpo su codice già scritto. Non è quasi mai vero: i limiti sono troppo larghi.
• L'agente propone di "disattivare questa regola perché è troppo severa". A volte ha ragione; sempre deve passare da te con la ragione scritta.
• La copertura sale perché sono stati aggiunti test che non provano niente (il verde che nasconde un bug, gradino 8). Il cricchetto misura la quantità; il rosso dimostrato misura la qualità. Vanno insieme.
• Un file è cresciuto fino al limite ed è stato spezzato in due file con lo stesso contenuto. È la duplicazione travestita da adempimento.
• La copertura è alta e il punteggio di mutazione è basso. Sono test che eseguono il codice senza verificare niente: il caso esatto che il rosso dimostrato del gradino 8 cerca di evitare.
• Il progetto ha utenti reali e nessuno ha eseguito i test di mutazione né ha scritto perché no. "È opzionale" ha smesso di essere una ragione valida per un progetto con utenti.

Passo 10 — I casi di prova manuale si scrivono insieme alla funzionalità, e li eseguono le persone (contratto del gradino)

Fase: ciclo. Quando: con ogni voce in sospeso, alla sua chiusura, dopo il test in rosso (8) e la qualità (9): l'agente scrive i casi di prova manuale del flusso che ha toccato. Si eseguono da parte di persone in tre momenti: alla chiusura di ogni blocco (le prove umane), prima del primo deployment in produzione (le prove di accettazione con il proprietario), e dopo ogni deployment, in una passata di sola lettura. Ogni esecuzione che fallisce reimmette un requisito nel ciclo come voce in sospeso correttiva. Forma: routine di ogni voce in sospeso; poi, esecuzione umana per ciclo. Dimensione: obbligatorio in ogni progetto con utenti: il caso di prova manuale è l'unica prova che il modello non scrive né esegue.

A cosa serve

Il metodo ha prove automatiche in abbondanza: il test in rosso, la regressione, l'end to end in tre scale. Le scrive e le esegue tutte il modello, e tutte provano ciò che il modello ha capito. Manca la prova che fa una persona con i propri occhi e le proprie mani, seguendo un copione scritto, e che trova ciò che nessun test trova: il pulsante che sta dove non deve, il messaggio che non si capisce, il flusso che tecnicamente va e umanamente non serve. La vista umana e le prove umane erano già nella linea del tempo; ciò che mancava era che avessero un copione, e che il copione lo scrivesse lo stesso che ha costruito la funzionalità, nello stesso momento, a partire dai criteri di accettazione della voce in sospeso. Senza copione, la prova umana è "gioca un po' con il sistema", e ciò che si trova dipende dall'umore del giorno. Con copione, si esegue uguale ogni volta, si registra cosa è successo, e ciò che fallisce torna nel ciclo come requisito. È la chiusura del circuito che il grafico del processo mostra: l'esecuzione manuale dei casi di prova reimmette requisiti nello sviluppo.

Un caso di prova manuale ha sempre la stessa forma: un identificatore; la voce in sospeso che lo origina; la precondizione (cosa deve esistere prima: un paziente, un appuntamento di ieri); i passi, numerati, ciascuno con ciò che la persona fa e ciò che deve vedere; il risultato atteso alla fine, incluso l'effetto nel backend che una persona può verificare (un record che compare, un messaggio nella casella finta); i dati di prova da usare; e lo spazio per il risultato di ogni esecuzione: data, chi, passato o fallito, osservazione.

Se sei alle prime armi. Un caso di prova manuale è una ricetta perché una persona provi una funzionalità: cosa preparare, cosa fare passo per passo, e cosa deve succedere a ogni passo. Si scrive perché chiunque la segua allo stesso modo, senza sapere com'è fatto il sistema. Eseguire un caso è seguire la ricetta e annotare se è passato o fallito. Precondizione è ciò che deve esistere prima di cominciare. E reimmettere vuol dire che ciò che la persona ha trovato sbagliato torna nella lista delle voci in sospeso come una richiesta nuova, con le sue parole.

1. Contesto richiesto

Quello che segue è la lista generica. I file concreti che devi avere pronti prima di ogni prompt, con il loro contenuto e il loro stato minimo, stanno nella sezione 2, nel blocco "Prima di inviare il prompt" che precede ciascuno.

• La voce in sospeso che si sta chiudendo, con i suoi criteri di accettazione "dato, quando, allora" (gradino 5): sono la materia prima del caso.
• L'ambiente di test con i dati, perché i passi si possano seguire davvero.
• Chi eseguirà i casi (il proprietario, un utente di fiducia) e quando (chiusura di blocco, accettazione, dopo ogni deployment).

2. Prompt

Routine di ogni voce in sospeso (va nel patto di convivenza):

Cosa gli sto chiedendo: che il caso esca dai criteri di accettazione (così prova ciò che è stato chiesto, non ciò che il modello ha capito); che sia scritto per qualcuno che non sa come funziona il sistema, che è la differenza tra un caso di prova e una nota tecnica; che includa l'effetto nel backend verificabile da una persona, perché anche la prova manuale guardi dall'altro lato dello schermo; che i casi si mantengano nello stesso commit, come la documentazione; e che il modello non li esegua mai, perché eseguiti dal modello sono un test in più, e il bello è che li esegua una persona.

Per un'esecuzione (chiusura di blocco, accettazione, dopo un deployment):

Cosa gli sto chiedendo: la reimmissione resa operativa: ogni fallimento umano è una voce in sospeso correttiva, con le parole della persona (non quelle del modello) come riproduzione, e appesa all'albero; il confronto con l'esecuzione precedente, che è ciò che ti dice se il sistema migliora o si degrada tra un blocco e l'altro; e la distinzione tra "il caso è scritto male" e "il sistema è sbagliato", che sono due voci in sospeso diverse.

3. Risultato atteso

• docs/MANUAL_TESTS.md con un caso per flusso toccato da ogni voce in sospeso chiusa, nel formato, scritto per una persona.
• Le esecuzioni registrate, con data e chi, in ogni ciclo.
• Una voce in sospeso correttiva per ogni fallimento e per ogni osservazione.
• La routine nel patto.

4. Verifica di completezza (la fai tu, senza leggere codice)

• Prendi un caso a caso e seguilo tu nell'ambiente di test senza chiedere niente all'agente: ci sei riuscito? Se hai dovuto chiedere, il caso non è scritto per una persona.
• Ogni voce in sospeso chiusa che tocca una schermata ha il suo caso? Chiedigli la lista delle voci senza caso.
• Il caso dice quale effetto verificare dall'altro lato dello schermo, e come lo verifica una persona?
• L'ultima esecuzione ha data e nome in ogni caso? Ce n'è qualcuno "passato" senza data?
• Ogni fallimento dell'ultima esecuzione ha la sua voce in sospeso, con le parole della persona?

5. Segnali d'allarme

• L'agente ha marcato i casi come eseguiti. Li ha eseguiti lui, che è lo stesso che non eseguirli.
• I casi sono copie del test automatico in prosa. Un caso manuale deve guardare ciò che il test non guarda: ciò che si vede, ciò che si capisce, ciò che dà fastidio.
• Tutti i casi passano in tutte le esecuzioni. Le persone trovano sempre qualcosa; se non trovano niente, non stanno seguendo il copione o il copione non chiede di guardare.
• I fallimenti si "sistemano" sul momento, senza voce in sospeso. Si perdono le parole della persona e la traccia di cosa si è ripetuto.

Passo 11 — Simmetria tra produttore e consumatore, e il registro degli anti-pattern (contratto del gradino)

Fase: ciclo. Quando: con ogni voce in sospeso che tocca un contratto tra due parti del sistema. La mappa dei contratti si costruisce all'apertura del secondo blocco funzionale, quando ci sono già una schermata e un server. Il registro degli anti-pattern cresce ogni volta che qualcosa si rompe per la seconda volta. Forma: automatica dentro il ciclo; più un file che cresce a ogni colpo. Dimensione: la simmetria è obbligatoria sempre; la mappa produttore/consumatore è opzionale in un progetto di un solo modulo, e obbligatoria appena ci sono una schermata e un server separati.

A cosa serve

Quando cambi un'estremità (il server, il robot, lo schema del database), fai in modo che l'altra estremità (la schermata, il contatore, il consumatore) cambi nello stesso commit. Altrimenti, prima o poi divergono, e l'utente vede un numero da una parte e un altro numero dall'altra Ref. 26. E gli errori che hai già pagato una volta, annotali per non pagarli due volte Ref. 2.

Il principio generale che c'è dietro, che ho imposto alla Mutua e che vale per qualunque sistema Ref. 27: ogni lista ha un solo proprietario. Le colonne di una tabella, gli stati possibili di un ordine, le cause per cui qualcosa aspetta: le definisce una sola parte del sistema (il produttore) e tutte le altre le leggono da lì. Appena ci sono due copie della stessa lista, una è disallineata; resta solo da scoprire quale. L'albero semantico del gradino 2 è il primo posto in cui quelle liste si dichiarano: gli stati di un'entità stanno lì, e il codice deve leggerli da una sola fonte.

1. Contesto richiesto

Quello che segue è la lista generica. I file concreti che devi avere pronti prima di ogni prompt, con il loro contenuto e il loro stato minimo, stanno nella sezione 2, nel blocco "Prima di inviare il prompt" che precede ciascuno.

• Una mappa di quali parti del sistema consumano cosa: quali schermate leggono quali servizi, quali processi scrivono quali tabelle. Se non esiste, il primo prompt la costruisce.
• Il registro degli anti-pattern docs/GOTCHAS.md, anche se è vuoto.

2. Prompt

Per costruire la mappa (una volta):

Cosa gli sto chiedendo: l'inventario dei contratti con i loro due lati, e la clausola di completezza nella sua forma per questo gradino: ciò che non si vede si dichiara, non si omette. Una mappa con buchi nascosti è peggio di nessuna mappa.

Routine (va nel patto di convivenza):

Cosa gli sto chiedendo: la simmetria come riflesso (cercare l'altro lato prima di chiudere), la regola della lista con un solo proprietario, e che la mappa si mantenga da sola man mano che la si usa.

Quando qualcosa si rompe per la seconda volta:

Cosa gli sto chiedendo: il formato fisso di un anti-pattern (odore, causa radice, correzione, rilevamento precoce) e, soprattutto, la verifica automatica: un anti-pattern annotato e non automatizzato si ripeterà quando cambia la persona o la sessione.

3. Risultato atteso

• docs/PRODUCER_CONSUMER_MAP.md: la lista dei contratti con produttore e consumatori.
• In ogni commit che tocca un contratto: i consumatori aggiornati, nominati nel messaggio.
• docs/GOTCHAS.md: una voce per anti-pattern, con le quattro parti (odore, causa radice, correzione, come rilevarlo prima), e la data della prima volta.

4. Verifica di completezza

• Scegli un contratto della mappa e chiedi all'agente di mostrarti dove lo legge ogni consumatore. Se qualcuno ha la propria copia della lista, c'è debito.
• C'è un numero che si mostra in due schermate diverse? Confronta: danno lo stesso risultato?
• Ogni voce di GOTCHAS ha le quattro parti?
• Si è ripetuto un errore che era già in GOTCHAS? Se sì, manca la verifica automatica.

5. Segnali d'allarme

• Lo stesso valore compare scritto a mano in più di un file ("IN SOSPESO", "APPROVATA" nel server e nella schermata). Due copie; una divergerà.
• Una modifica al server si è chiusa con il test del server in verde e nessuno ha toccato la schermata.
• GOTCHAS ha voci senza la parte "come rilevarlo prima". Sono aneddoti, non anti-pattern.

Passo 12 — Verifica onesta e rapporto proporzionato (contratto del gradino)

Fase: ciclo. Quando: in ogni rapporto, di ogni voce in sospeso, per tutto il progetto. È la forma che deve avere tutto ciò che l'agente ti dice. Forma: routine; è la forma che deve avere ogni rapporto dell'agente. Dimensione: obbligatorio in ogni progetto, senza eccezioni. Non costa nulla ed è ciò che permette al proprietario di non leggere codice.

A cosa serve

Se non leggerai codice, il rapporto dell'agente deve essere affidabile. Non ottimista, non "completo in apparenza": affidabile. Questo è ciò che c'è di genuinamente nuovo nel metodo: l'autore del codice fabbrica anche la prova, e lo fa con la stessa sicurezza nella voce quando è giusto e quando è sbagliato. Per questo la prova deve dimostrare se stessa, e il rapporto deve separare il verificato dal creduto. La regola l'ho scritta a giugno Ref. 8, e ne ho avuto di nuovo bisogno a ottobre, quando un errore di autenticazione è stato riportato con la dicitura "success" Ref. 43.

Capisci perché il modello tende a riportare più del dovuto. Non è malafede: è che è stato addestrato per essere utile e completo, e un rapporto che dice "questo non sono riuscito a verificarlo" sembra meno utile di uno che dice "fatto". Quindi chiedigli 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.

1. Contesto richiesto

Quello che segue è la lista generica. I file concreti che devi avere pronti prima di ogni prompt, con il loro contenuto e il loro stato minimo, stanno nella sezione 2, nel blocco "Prima di inviare il prompt" che precede ciascuno.

• Il lavoro fatto e la voce in sospeso che lo chiedeva.
• Il patto di convivenza (gradino 1), che già vieta di annunciare ciò che non è stato fatto.

2. Prompt

Routine (va nel patto di convivenza; si applica a ogni rapporto):

Cosa gli sto chiedendo, clausola per clausola: i tre blocchi, che sono la struttura che rende onesto un rapporto (il verificato con la sua prova, il creduto con la ragione per cui non è stato provato, ciò che non può vedere); la copertura punto per punto, perché nulla "si dimentichi"; la prova accanto a ogni affermazione; il divieto del "fatto" secco; e le cattive notizie per prime, perché il modello tende a lasciarle per la fine o per mai.

Davanti a un tuo "è ancora rotto":

Cosa gli sto chiedendo: che davanti a un "è ancora rotto" non torni a diagnosticare da zero ma prima confronti le versioni. La metà degli "è ancora rotto" sono correzioni che stanno nel repository ma non nel posto in cui tu guardi Ref. 45.

3. Risultato atteso

Ogni rapporto dell'agente con:

• I tre blocchi (verificato / creduto / punti ciechi), anche se qualcuno è vuoto.
• Una riga per ogni punto chiesto, con il suo stato.
• Per ogni "verificato": il comando e l'output, o il test e il suo risultato, o il numero e il suo misuratore.
• Ciò che è andato storto, all'inizio e non alla fine.

4. Verifica di completezza

• Ci sono i tre blocchi? Se "creduto" e "punti ciechi" sono sempre vuoti, l'agente non sta essendo onesto: c'è sempre qualcosa che non ha visto.
• Scegli a caso un'affermazione del blocco "verificato": ha la sua prova accanto? La puoi riprodurre?
• Copre ogni punto di ciò che hai chiesto, o ce n'è uno che "si è dimenticato"?
• Le cattive notizie sono all'inizio?
• Ha detto "fatto" secco qualche volta? È una violazione del patto.

5. Segnali d'allarme

• Dieci rapporti di fila senza nessun punto cieco. Nessuno vede tutto; il blocco è vuoto per abitudine, non per verità.
• Il blocco "verificato" ha frasi come "dovrebbe funzionare". È "creduto" travestito.
• Il rapporto è più lungo della modifica. Un rapporto proporzionato dice ciò che va detto; uno gonfiato sta coprendo qualcosa con il volume.

Passo 13 — L'audit periodico come input del piano (contratto del gradino)

Fase: uscita in produzione. Quando: obbligatorio prima del primo deployment in produzione; apre la fase di uscita. Poi, in esercizio, ogni uno o due mesi secondo il ritmo di cambiamento, e alla chiusura di ogni tappa grande. Forma: un solo invio lungo, idealmente a un agente diverso da quello che costruisce. Dimensione: obbligatorio prima del primo deployment in produzione, in qualunque progetto; poi, proporzionale al ritmo di cambiamento (un sistema che cambia tutte le settimane si sottopone ad audit ogni mese; uno stabile, ogni sei).

A cosa serve

Guarda il sistema intero con occhi freschi ogni tanto, e converti ciò che vedi in voci in sospeso. L'audit non è un rapporto che si archivia: è piano. Evita la password scritta nel codice che nessuno aveva visto, le query che leggono tabelle intere Ref. 18, la vulnerabilità nota in una dipendenza, il componente di migliaia di righe Ref. 41. Ed è l'indipendenza del controllo di qualità portata un passo più in dentro: chi fa l'audit non è chi ha costruito.

Sull'indipendenza: non serve un'altra azienda né un altro strumento. Basta un'altra sessione, con un altro file di istruzioni, che non abbia partecipato alla costruzione. Ciò che cerchi è che l'auditor non condivida i presupposti del costruttore. 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 quello che è. Così sono state rilevate due porte di amministratore che il costruttore aveva lasciato in un giorno Ref. 40.

Se puoi scegliere, che sia anche un modello diverso da quello che ha costruito, non solo un'altra sessione dello stesso: uno studio del 2026 ha misurato che una sessione pulita con un modello diverso trova più errori di due sessioni dello stesso modello (arXiv 2610.01471). Non è un cancello duro, perché a volte il modello del costruttore è l'unico disponibile; è una preferenza che vale la pena esercitare quando si può, e più il sistema è critico, più vale la pena esercitarla.

1. Contesto richiesto

Quello che segue è la lista generica. I file concreti che devi avere pronti prima di ogni prompt, con il loro contenuto e il loro stato minimo, stanno nella sezione 2, nel blocco "Prima di inviare il prompt" che precede ciascuno.

• Il repository completo, in sola lettura.
• La produzione o l'ambiente di test, in sola lettura (database, log).
• L'audit precedente, se c'è stato, per misurare cosa è cambiato.
• Il perimetro: integrità, sicurezza, prestazioni, qualità del codice, o tutto.
• docs/PENDING.md con le voci in sospeso chiuse nell'ultimo ciclo e le loro ricevute, perché l'auditor scelga quali riprodurre.

2. Prompt

Iniziale (a un agente diverso dal costruttore, se si può):

Cosa gli sto chiedendo, clausola per clausola: sola lettura (l'auditor non corregge; propone); la clausola di completezza nella sua forma per l'audit: ciò che non si è potuto verificare si dichiara, non si approva per omissione; tutto il codice e non un campione, perché i rilievi gravi di solito stanno dove nessuno guarda; la riproduzione letterale di due o tre ricevute, perché l'audit verifichi prove invece di limitarsi a leggerle (è la clausola che chiude il buco di D-033: un rosso raccontato non è un rosso sottoposto ad audit); ogni rilievo con posizione, rischio, prova e priorità, perché sia azionabile senza rileggere il rapporto; voti per dimensione, per confrontare con l'audit precedente; e i P0 già convertiti in voci in sospeso proposte.

Di chiusura (al costruttore):

Cosa gli sto chiedendo: che l'audit si converta in voci in sospeso (altrimenti è un rapporto che si archivia), e che il disaccordo sia esplicito e con prove, non silenzioso.

3. Risultato atteso

• docs/AUDIT_[data].md con: perimetro, cosa si è potuto verificare e cosa no (e perché), i rilievi con posizione, rischio, prova e priorità, un voto per dimensione, il risultato della riproduzione di due o tre ricevute dell'ultimo ciclo, e la lista delle voci in sospeso proposte.
• In docs/PENDING.md: una voce in sospeso per ogni P0 e P1, citando il rilievo.

4. Verifica di completezza

• Il rapporto dice cosa NON ha potuto verificare? Se dice di aver verificato tutto, diffida.
• Scegli due rilievi: hanno file e riga, e una prova che puoi riprodurre?
• Il rapporto dice quali ricevute ha riprodotto, con il comando e il risultato, o dice solo di averle lette?
• Ogni P0 ha la sua voce in sospeso aperta prima di dare l'audit per chiuso?
• I voti per dimensione si potranno confrontare con l'audit precedente?
• Ha fatto l'audit lo stesso agente che ha costruito? Se è così, chiedi un secondo sguardo sui P0.

5. Segnali d'allarme

• L'audit non ha trovato nessun P0. In un sistema di più di tre mesi, non è quasi mai vero; più probabile è che il perimetro fosse piccolo o che l'auditor condividesse i presupposti.
• I rilievi non hanno la riga del file. Sono opinioni, non rilievi.
• Il rapporto dice che le ricevute "sono state riviste" senza mostrare il comando eseguito né il suo output. Una ricevuta letta e una riprodotta non sono la stessa cosa, e solo la seconda chiude l'obiezione di D-033.
• Sono passate due settimane e i P0 sono ancora senza voce in sospeso. L'audit è stato archiviato.

Passo 14 — Fail-closed, lucchetti e zero danno silenzioso (contratto del gradino)

Fase: uscita in produzione. Quando: nella fase di uscita in produzione, PRIMA di costruire qualunque funzionalità che addebiti, invii, approvi o cancelli; si rivede con ogni nuova azione con conseguenze. Le automazioni nuove partono in modalità di prova e si abilitano dopo averne guardato il registro per qualche giorno. Forma: conversazione: l'agente elenca le azioni con conseguenze, tu confermi quali portano un lucchetto e di che tipo. Dimensione: obbligatorio appena il sistema fa qualcosa di irreversibile (addebitare, inviare, cancellare, approvare). Un sistema di sola lettura può saltarlo; nel momento in cui guadagna il suo primo pulsante che agisce sul mondo, questo gradino diventa il più importante.

A cosa serve

Fai in modo che il sistema, davanti a un dubbio o a un guasto, NON agisca, e che lo dica. Suona ovvio ed è il contrario di ciò che il software fa per default, che davanti al dubbio va avanti. Evita il doppio addebito, l'approvazione automatica senza passare da un umano, il git add -A che carica una credenziale, e la cancellazione dei dati del cliente. I lucchetti che ho messo alla Mutua sono il modello: il pulsante di emergenza con doppia sicura, l'approvatore automatico in modalità di prova, la sentinella con guardie Ref. 28; e il riflesso per cui un guasto lascia una riga senza il suo pulsante invece di rompere l'intero elenco Ref. 25.

Il principio ha un nome, "fail-closed", e viene dalla sicurezza fisica: una porta di sicurezza che resta chiusa quando va via la luce. Il contrario, "fail-open", è la porta che si apre. Nel software la maggior parte delle cose sono fail-open per default: se la validazione fallisce, il codice prosegue; se il servizio non risponde, si assume che vada tutto bene. Il metodo inverte il default: nel dubbio, no. E si applica tanto al sistema quanto all'agente che lo opera.

1. Contesto richiesto

Quello che segue è la lista generica. I file concreti che devi avere pronti prima di ogni prompt, con il loro contenuto e il loro stato minimo, stanno nella sezione 2, nel blocco "Prima di inviare il prompt" che precede ciascuno.

• Rilevazione delle azioni con conseguenze, nominata così in forma generica: cosa fa il sistema che addebita, invia, approva, cancella, o avvisa qualcuno all'esterno; cosa succede se si fa due volte; cosa succede se si fa male; come si annulla. Lo sa il business; l'agente valuta se la lista è completa e chiede. L'albero semantico aiuta: ogni processo con conseguenze sta lì.
• Quali azioni può fare l'agente stesso sul sistema (se è incorporato).

2. Prompt

Iniziale:

Cosa gli sto chiedendo: l'incrocio tra ciò che il business ha detto e ciò che il codice fa (lì compaiono le azioni che nessuno ricordava); la clausola di completezza nella sua forma per questo gradino: le differenze tra le due liste si chiedono, non si risolvono; per ogni azione, reversibilità, lucchetto e via del ritorno; e la regola generale del fail-closed scritta nel prompt, perché resti nella tabella e nel codice.

Di chiusura:

Cosa gli sto chiedendo: il test per lucchetto provato in rosso (senza il lucchetto, l'azione avveniva; con il lucchetto, no), che è il gradino 8 applicato alla sicurezza; la tabella finale; e la regola della modalità di prova per ogni automazione nuova, che è ciò che permette di vedere cosa avrebbe fatto prima di lasciarla fare.

3. Risultato atteso

• docs/LOCKS.md: una riga per azione con conseguenze: cosa fa, se è reversibile, il lucchetto, la via del ritorno, chi l'ha approvato e quando.
• Un test per lucchetto, provato in rosso, che verifica che nel dubbio l'azione non avviene.
• Le automazioni nuove che partono in modalità di prova, con il registro di "avrebbe fatto".
• Se l'agente è incorporato: i suoi permessi scritti (cosa può leggere, cosa può cambiare, cosa richiede approvazione).

4. Verifica di completezza

• Ogni azione che addebita, invia, approva o cancella sta nella tabella? Pensane una che non c'è e chiedi.
• Ogni lucchetto ha il suo test in rosso? ("Senza il lucchetto, l'azione avveniva; con il lucchetto, no.")
• Ogni azione irreversibile ha una via del ritorno scritta? Se non ce l'ha, ha bisogno di una doppia sicura.
• Le automazioni nuove sono partite in modalità di prova? Hai visto il registro di "avrebbe fatto" prima di abilitarle?
• Cosa succede se l'agente incorporato tenta qualcosa fuori dai suoi permessi? Chiedigli di provarci e di mostrarti il rifiuto nel log.

5. Segnali d'allarme

• Un'automazione è passata da "non esiste" a "gira da sola" senza un periodo di modalità di prova.
• Il log non ha nessuna voce di "azione non eseguita per dubbio". O il sistema non dubita mai (impossibile) o quando dubita va avanti.
• Un lucchetto si può saltare con un parametro "per i test". Quel parametro resterà impostato in produzione.

Passo 15 — Integrazione continua, ambienti, segreti e deployment come parte del prodotto (contratto del gradino)

Fase: uscita in produzione. Quando: la catena di integrazione e il deployment all'ambiente di test si montano nel gradino

4. La chiusura verso la produzione —ambiente reale, segreti sul server, promozione, rollback

provato, lucchetto contro i segreti— si fa nella fase di uscita, dopo l'audit e dopo i lucchetti. La routine di ogni deployment si applica per tutto l'esercizio. Forma: un solo invio per montarlo; routine per ogni deployment. Dimensione: obbligatorio in ogni progetto con utenti. In uno piccolo, "integrazione continua" può essere una sola action di GitHub e "ambienti" possono essere due cartelle sullo stesso server; ciò che non si negozia è che i test girino da soli, che la configurazione non stia nel repository, e che ci sia un rollback.

A cosa serve

Fai in modo che arrivare in produzione sia un pacchetto riproducibile: i test girano UNA volta, la configurazione vive fuori dal repository, e i segreti non vanno in giro. Evita i test eseguiti tre volte per commit e la quota bruciata Ref. 39, il deployment irrobustito a colpi di voci in sospeso per averlo scoperto tardi Ref. 32, e i segreti incollati nella chat Ref. 42.

Sui segreti c'è una regola che devi adottare come riflesso, senza eccezioni: un segreto che è stato visto in una chat, in un log o in un commit non è più un segreto. Non importa se "nessuno l'ha visto" o se "è stato cancellato dopo". Si ruota. La rotazione costa dieci minuti; scoprire se qualcuno l'ha usato è impossibile.

1. Contesto richiesto

Quello che segue è la lista generica. I file concreti che devi avere pronti prima di ogni prompt, con il loro contenuto e il loro stato minimo, stanno nella sezione 2, nel blocco "Prima di inviare il prompt" che precede ciascuno.

• Rilevazione di ambienti e accessi, in forma generica: quali ambienti ci sono (test, produzione), dove girano, chi ha accesso, come si promuove qualcosa dall'uno all'altro, quali segreti esistono e dove vivono oggi, quanta quota di integrazione continua c'è. L'agente valuta se basta e chiede.
• Lo scheletro con la sua integrazione continua e il suo deployment in test (gradino 4).

2. Prompt

Iniziale:

Cosa gli sto chiedendo, clausola per clausola: gli accessi prima di cominciare; i test una sola volta per commit (eseguirli tre volte è ciò che ha bruciato la quota); il deployment che si limita a impacchettare; la configurazione fuori dal repository; la promozione come procedura ripetibile; il rollback provato, con il suo piano dei dati (un rollback che non è mai stato provato non esiste, e una migrazione di schema o di dati non si disfa ripristinando il commit); il lucchetto contro i segreti nei commit; e la documentazione per una persona, che è il gradino 20 applicato all'infrastruttura.

Routine di ogni deployment:

Cosa gli sto chiedendo: le tre condizioni preliminari (test in verde con la stessa versione, rollback pronto, modifiche di configurazione annunciate) e le due prove successive (la versione in esecuzione e una verifica end to end senza scrivere nulla).

Se un segreto è comparso nella chat o in un commit:

Cosa gli sto chiedendo: rotazione immediata, inventario di dove altro stava, e la verifica che lo avrebbe rilevato, perché la prossima volta non arrivi alla chat.

3. Risultato atteso

• L'integrazione continua che gira una sola volta per commit, con il link a un'esecuzione.
• Il deployment che aspetta l'integrazione e si limita a impacchettare; misurato: quanto ci mette prima e dopo.
• La configurazione fuori dal repository; nel repo, solo un esempio senza valori.
• docs/DEPLOYMENT.md: come distribuire, promuovere e tornare indietro, passo per passo, per una persona.
• Il rollback provato almeno una volta, con la sua prova.
• La verifica anti-segreti attiva (un tentativo di caricarne uno, respinto).
• Un registro della quota di integrazione continua consumata per mese.

4. Verifica di completezza

• Quante volte gira la batteria per ogni commit? Deve essere una. Chiedi il link.
• C'è qualche valore reale di configurazione (una chiave, una password, una URL interna) nel repository? Chiedi all'agente di cercare e di mostrarti la ricerca vuota.
• Potresti seguire docs/DEPLOYMENT.md da solo, senza l'agente? Leggilo con quella domanda.
• Il rollback è stato provato? Quando? Che prova c'è?
• Se c'è stata una migrazione di schema o di dati: c'è un piano scritto per disfarla o compensarla, oltre al rollback del codice?
• È stato incollato qualche segreto nella chat durante il progetto? Se sì, è stato ruotato?
• Sai quanta quota di integrazione continua resta questo mese?

5. Segnali d'allarme

• Il deployment in produzione si fa "a mano, veloce, perché è una modifica piccola". Le modifiche piccole sono quelle che rompono la produzione, perché nessuno le prova.
• Il file di esempio della configurazione ha valori che sembrano reali. Probabilmente lo sono.
• Nessuno sa dire quando è stata l'ultima volta che si è provato il rollback.
• Una migrazione ha cambiato dati o schema e "il rollback" di cui si parla è solo quello del codice. Per quella migrazione non c'è rollback: c'è, nella migliore delle ipotesi, un piano per compensarla.

Passo 16 — Osservabilità e tracciabilità totali, con livello configurabile (contratto del gradino)

Fase: uscita in produzione. Quando: nella fase di uscita in produzione, dopo il 15 (c'è già la catena di deployment e la configurazione per ambiente) e prima delle prove di rendimento (19), perché senza osservabilità le prove di rendimento non dicono cosa si è rotto. In un legacy, il livello minimo (registri strutturati con livello configurabile e un identificatore di correlazione) entra nella cintura di sicurezza (N4); il livello completo, qui. La regola "ogni modulo nuovo registra e propaga" vige durante tutto l'esercizio. Forma: un solo invio; l'agente costruisce e dimostra; tu leggi una traccia reale. Dimensione: obbligatorio nel suo livello minimo in ogni progetto che avrà utenti; completo in qualunque progetto con conseguenze.

A cosa serve

Quando qualcosa fallirà in produzione, e fallirà, voglio poter seguire un'azione dalla schermata fino al database e fino a ogni chiamata esterna, con un solo identificatore, senza aprire il codice e senza chiedere all'agente di "controllare". E voglio poter alzare il livello di dettaglio dei registri in produzione, in un minuto, senza rifare il deployment, e riabbassarlo dopo. Questa è l'osservabilità: vedere ciò che il sistema fa. E la seconda cosa è la tracciabilità: che ogni azione con conseguenza (ha incassato, ha inviato, ha cancellato, ha approvato) lasci una traccia di chi, quando, cosa, da dove e con quale risultato, in un registro che l'applicazione non può modificare. Senza questo, l'agente residente del gradino 23 opera alla cieca, il monitoraggio dei gradini 21 e 22 non ha di che alimentarsi, e ogni incidente si diagnostica con ipotesi invece che con prove. Il turno orfano che è rimasto vivo un'ora e quarantatré si è trovato dal log, non dal codice Ref. 16; e l'agente residente è partito, appunto, leggendo log Ref. 13.

"Livello configurabile" è la clausola che distingue questo dal "mettere dei log": il livello (errore, avviso, informazione, debug, traccia) si cambia per configurazione sul server, per ambiente, senza toccare codice né rifare il deployment, e la produzione gira su informazione salvo quando si sta investigando qualcosa.

Se sei alle prime armi. Un registro (log) è una riga che il sistema scrive ogni volta che fa qualcosa: "10:42:13, modulo agenda, utente reception1, appuntamento 17 cancellato". Strutturato vuol dire che tutte le righe hanno le stesse parti nello stesso ordine, perché si possano cercare a macchina. Il livello è quanto dettaglio si scrive: in "errore" solo ciò che è fallito; in "traccia", ogni passo. L'*identificatore di correlazione* è un numero unico che si dà a ogni azione quando comincia (hai premuto "cancella") e che viaggia attaccato a tutto ciò che quell'azione provoca (la query al database, il messaggio al paziente), così dopo si cerca quel numero e compare la storia completa. E l'*audit* è una lista che non si può modificare delle azioni importanti: chi ha fatto cosa e quando.

1. Contesto richiesto

Quello che segue è la lista generica. I file concreti che devi avere pronti prima di ogni prompt, con il loro contenuto e il loro stato minimo, stanno nella sezione 2, nel blocco "Prima di inviare il prompt" che precede ciascuno.

• La catena di deployment e la configurazione per ambiente (gradino 15): il livello si configura lì.
• La tabella dei lucchetti (gradino 14): ogni azione con conseguenza è una voce dell'audit.
• La rilevazione iniziale con i dati personali segnati: i registri non possono contenerli.
• Dove vivranno i registri e le metriche (un file ruotato, un servizio): lo decidi tu.

2. Prompt

Iniziale:

Cosa gli sto chiedendo: i cinque pezzi, e due dimostrazioni che sono la prova del gradino: un identificatore reale seguito attraverso tutti gli strati (se non lo può mostrare, la propagazione è rotta da qualche parte) e il livello che cambia senza deployment (se bisogna fare il deployment, non è configurabile). L'audit delle azioni con conseguenza deve essere immutabile dall'applicazione, perché una traccia che l'applicazione può cancellare non è una traccia. E il mascheramento dei dati personali va nello stesso prompt perché i registri sono il luogo dove più dati personali si disperdono senza che nessuno lo decida.

Routine (va nel patto di convivenza):

Cosa gli sto chiedendo: che l'osservabilità non si degradi con ogni modulo nuovo, che è ciò che succede sempre se non è una regola: il modulo del terzo mese non registra niente ed è proprio quello che fallisce.

3. Risultato atteso

• Registri strutturati con livello configurabile per ambiente, cambiati senza deployment.
• Un identificatore di correlazione in ogni record, propagato dalla schermata al database e alle chiamate esterne.
• Un registro di audit immutabile delle azioni con conseguenza.
• Endpoint o file di salute e metriche, documentati.
• Nessun dato personale nei registri.
• docs/OBSERVABILITY.md e la routine nel patto.

4. Verifica di completezza (la fai tu, senza leggere codice)

• Chiedigli l'identificatore di una richiesta reale e cercalo tu nei registri: compare nella schermata, nel backend, nel database e nella chiamata esterna, se c'è stata?
• Alza il livello a debug nell'ambiente di test, fai un'azione, guarda i registri, riabbassalo. Hai dovuto fare il deployment? Allora non è salito.
• Cerca un nome o un telefono di prova nei registri: non ci deve essere.
• Fai un'azione con conseguenza in test (cancellare, inviare alla casella finta): è rimasta nell'audit con chi, quando, cosa ed esito?
• docs/OBSERVABILITY.md ti basta per trovare un registro da solo alle tre del mattino?

5. Segnali d'allarme

• L'agente mostra dei "log" ma ogni modulo scrive in un formato diverso. Non è strutturato; nessuno potrà cercarli.
• L'identificatore compare nel backend ma non nelle chiamate esterne o nelle attività pianificate. Sono proprio i posti dove gli incidenti si perdono.
• Il livello di produzione è rimasto su debug "per ora". Si riempie il disco e si disperdono dati.
• L'audit delle azioni con conseguenza vive nella stessa tabella del resto dei dati e l'applicazione può cancellarla.

Passo 17 — Ottimizzazione dello strato di persistenza, misurata prima e dopo (contratto del gradino)

Fase: uscita in produzione. Quando: nella fase di uscita in produzione, dopo il 16 (serve vedere le query per misurarle) e prima del 19 (le prove di rendimento si eseguono sulla persistenza già ottimizzata; altrimenti misurano il problema che si conosceva già). Si ripete quando un blocco aggiunge una tabella grande o cambia un flusso critico, e quando il monitoraggio (21) mostra una query fuori range. In un legacy, le misurazioni escono da N6 e la maggior parte di ciò che si trova si paga "al tocco", salvo ciò che è già fuori range. Forma: due invii: misurare e proporre; applicare con prima e dopo. Dimensione: proporzionale: in un progetto piccolo, gli indici delle query reali e la fine dei cicli N+1; in uno con conseguenze, completo, con budget per percorso.

A cosa serve

Lo strato di persistenza è dove i sistemi muoiono lentamente: funzionano bene con cento record, accettabilmente con diecimila, e a centomila ogni schermata ci mette venti secondi, e nessuno sa quando è cominciato. Questo gradino esiste perché quella cosa si decida con i numeri e prima della produzione, non con le lamentele e dopo. E perché si decida con il metodo del gradino 7: ogni query che il sistema fa si conta e si cronometra con un misuratore che ha il suo test, si cambia ciò che i numeri dicono, e si misura di nuovo sugli stessi dati. Il primo audit di query senza indice su un sistema vivo Ref. 18 e il budget di query stretto a ciò che era stato misurato Ref. 37 sono l'origine di questo gradino; la decisione dell'interfaccia asincrona dalla riga uno Ref. 15, il suo antecedente nell'avvio.

Ciò che non è: non è "riscrivere l'accesso ai dati", né scegliere un altro motore. Quello lo ha deciso il gradino 3. È aggiustare ciò che c'è (indici, paginazione, lotti, retention, dimensione del pool) a partire da ciò che le query reali fanno.

Se sei alle prime armi. Lo strato di persistenza è la parte del sistema che salva e legge i dati, quasi sempre un database. Un indice è come l'indice di un libro: senza di esso, per trovare un appuntamento il database legge l'intera tabella (questo è un full scan); con esso, va dritto. Un ciclo N+1 è un errore molto comune: per mostrare cento appuntamenti, il sistema fa una query per la lista e poi altre cento query, una per appuntamento, invece di una sola. Paginazione è mostrare venti alla volta invece di tutto insieme. Retention è per quanto tempo si conserva ogni dato prima di archiviarlo o cancellarlo. E il pool di connessioni è la quantità di "linee aperte" che il sistema tiene con il database nello stesso momento. Niente di tutto questo richiede che tu legga codice: richiede che tu guardi numeri prima e dopo.

1. Contesto richiesto

Quello che segue è la lista generica. I file concreti che devi avere pronti prima di ogni prompt, con il loro contenuto e il loro stato minimo, stanno nella sezione 2, nel blocco "Prima di inviare il prompt" che precede ciascuno.

• Il dimensionamento e la volumetria (gradino 3, o N6 in un legacy): i volumi ai quali bisogna misurare.
• La mappa produttore-consumatore (gradino 11): cosa consuma ogni tabella.
• L'osservabilità (16): ogni query visibile con il suo tempo.
• L'ambiente di test caricato con dati al volume atteso.

2. Prompt

Iniziale (misurare e proporre):

Cosa gli sto chiedendo: misurare con il metodo del gradino 7 (misuratore con test, verificato nelle due direzioni, numero con comando) prima di proporre; proporre query per query, con il guadagno e il rischio, e con i consumatori della mappa che ogni modifica tocca (un indice nuovo non tocca nessuno; una retention per tabella tocca tutti quelli che leggono quella tabella); e non cambiare nulla finché non approvo io, perché l'ottimizzazione è il luogo dove più si "migliora" ciò che nessuno ha chiesto.

Di chiusura (applicare con prima e dopo):

Cosa gli sto chiedendo: un commit per modifica, perché il prima e il dopo siano attribuibili; lo stesso misuratore sugli stessi dati (se cambiano i dati, il numero non dice niente); il budget con test, che è ciò che impedisce al ciclo N+1 di tornare tra tre mesi; e la simmetria del gradino 11 applicata alla persistenza.

3. Risultato atteso

• I misuratori di query nel repository, con test.
• docs/PERSISTENCE.md con la tabella del prima e dopo per ogni modifica, i budget per percorso e la retention per tabella.
• Gli indici, la paginazione, i lotti e la retention applicati, un commit ciascuno, con la regressione e l'end to end in verde.
• Un test per budget che fallisce se viene superato.

4. Verifica di completezza

• Esegui tu un misuratore prima e dopo (l'agente ti dà i due comandi): coincidono con la tabella?
• C'è qualche query che legge una tabella intera in un flusso critico? Perché è rimasta?
• Ogni tabella ha una politica di retention scritta, anche se è "per sempre"?
• I budget hanno un test? Chiedigli di superarne uno apposta e di mostrarti il rosso.
• La schermata più lenta, con i dati al volume, ci mette quanto il dimensionamento si aspettava?

5. Segnali d'allarme

• Le misurazioni sono state fatte con i dati di esempio dello scheletro. Tutto è veloce con dieci righe.
• L'agente propone di "migrare a un altro database" o di "riscrivere lo strato dati". Quello è il gradino 3, e se bisogna tornarci è una decisione tua, non un'ottimizzazione.
• Il numero è migliorato ma l'end to end di un flusso ha smesso di passare. Un indice non rompe un flusso; una retention o una paginazione sì: è mancato un consumatore della mappa.
• Non ci sono budget. Senza budget, l'ottimizzazione dura fino al blocco successivo.

Passo 18 — Scansione e soluzione delle vulnerabilità, nella catena e con un calendario (contratto del gradino)

Fase: uscita in produzione. Quando: nella fase di uscita in produzione, dopo il 15 (la scansione gira nell'integrazione continua) e prima del primo deployment: nessun P0 aperto viene promosso. Poi, a ogni push, e con un calendario proprio (settimanale) anche se non ci sono push, perché le vulnerabilità nuove compaiono senza che tu cambi nulla. In un legacy, la prima esecuzione fa parte di N3 (la dimensione di sicurezza dell'audit) e i rilievi entrano nel backlog con la loro marca di velocità. Forma: un solo invio per montare ed eseguire; poi, automatico, con un rapporto che leggi tu. Dimensione: obbligatorio in ogni progetto che avrà utenti: la scansione delle dipendenze e dei segreti non si negozia; l'analisi statica e la linea base di configurazione, proporzionali.

A cosa serve

L'audit del gradino 13 guarda il sistema con occhi freschi ogni tanto; questo gradino guarda una cosa sola, la sicurezza, tutto il tempo e a macchina. Sono complementari: l'audit trova ciò che richiede criterio (una porta di amministratore che nessuno dovrebbe avere Ref. 40); la scansione trova ciò che richiede costanza (la dipendenza che ieri non aveva una vulnerabilità nota e oggi sì Ref. 41). Il primo audit di sicurezza formale mi ha convinto che la sicurezza è una routine periodica e non una lista che si spunta una volta Ref. 23; questo gradino è quella routine fatta macchina.

E una regola che voglio scritta: un aggiornamento di dipendenza è una modifica, ed entra dal ciclo come qualunque altra. "Ho alzato la versione per chiudere la vulnerabilità" senza regressione né end to end è il modo più comune di rompere la produzione di venerdì.

Se sei alle prime armi. Una vulnerabilità è un difetto che qualcuno può usare per entrare, rubare dati o far fare al sistema qualcosa che non dovrebbe. Ce ne sono di quattro tipi che questo gradino cerca a macchina. Nelle dipendenze: i pezzi di software di altri che il tuo sistema usa (ci sono basi pubbliche che elencano quali hanno difetti noti, identificati con un numero CVE). Nel codice: l'*analisi statica* legge il codice senza eseguirlo cercando schemi pericolosi, come un'*injection* (che un utente scriva in un modulo qualcosa che il database interpreta come un ordine). Nella storia: un segreto (una password, una chiave) che una volta è stato salvato nel repository resta lì anche se dopo è stato cancellato. E nella configurazione: porte aperte che non servivano, password predefinite, header di sicurezza (istruzioni che il server manda al browser per proteggerlo) che mancano.

1. Contesto richiesto

Quello che segue è la lista generica. I file concreti che devi avere pronti prima di ogni prompt, con il loro contenuto e il loro stato minimo, stanno nella sezione 2, nel blocco "Prima di inviare il prompt" che precede ciascuno.

• L'integrazione continua (gradini 4 e 15), dove gira la scansione.
• La rilevazione degli ambienti: quale server, quale contenitore, quali porte, per la linea base di configurazione.
• L'audit precedente (13, o N3), per non riportare ciò che è già noto.
• Il tuo criterio su cosa è P0: ciò che permette di entrare, ciò che espone dati personali, ciò che permette di incassare o inviare senza controllo.

2. Prompt

Iniziale (montare, eseguire, proporre):

Cosa gli sto chiedendo: i quattro strati di scansione (dipendenze, codice, segreti nella storia, configurazione), nella catena e con un calendario, perché le vulnerabilità nuove non aspettano il tuo prossimo push; il rapporto con la forma del gradino 13, con la clausola di "non scansionato" invece di "pulito"; il criterio di P0 dato da me; e il divieto di aggiornare senza passare dal ciclo, che è quello che evita il venerdì rotto.

Di chiusura (sistemare e trasformare in cancello):

Cosa gli sto chiedendo: una voce in sospeso per soluzione, con il rosso del gradino 8 dove si può (una vulnerabilità sistemata senza test torna con il prossimo refactor); la scansione ripetuta come prova; e la conversione in cancello, che è ciò che fa sì che questo gradino resti vivo quando nessuno lo guarda.

3. Risultato atteso

• La scansione in quattro strati che gira a ogni push e settimanalmente.
• docs/SECURITY_[data].md con i rilievi e ciò che non è stato scansionato; docs/SECURITY.md con la politica, il calendario, il cancello e la copertura.
• I P0 e i P1 sistemati, ciascuno con la sua voce in sospeso e il suo test dove si applica.
• Il cancello in docs/GATES.md.

4. Verifica di completezza

• Chiedigli il link all'ultima esecuzione della scansione: è in verde, e di che data è?
• Il rapporto dice cosa NON ha scansionato?
• Ogni P0 ha la sua voce in sospeso chiusa con prova, o aperta con data?
• Chiedigli di introdurre apposta una dipendenza con vulnerabilità nota in un ramo: la catena va in rosso?
• Sai quando gira la prossima scansione programmata?

5. Segnali d'allarme

• La scansione è passata pulita al primo colpo in un sistema con più di un mese. Non è quasi mai vero: manca uno strato, oppure è stato scansionato solo il ramo e non la storia.
• Sono state aggiornate dieci dipendenze in un commit "per chiudere i rilievi". Quel commit non ha né prima né dopo; è il venerdì rotto che aspetta.
• La scansione c'è ma non è un cancello: produce rapporti che nessuno legge.
• C'è un P0 "accettato" senza voce in sospeso né data né firma.

Passo 19 — Prove di rendimento in volume e punto di rottura (contratto del gradino)

Fase: uscita in produzione. Quando: nella fase di uscita in produzione, dopo il 16 (senza osservabilità non si sa cosa si è rotto) e dopo il 17 (sulla persistenza già ottimizzata), e prima del primo deployment in produzione. Si ripete prima di ogni deployment che cambi l'architettura, la persistenza o un flusso critico, e quando il dimensionamento cambia (lo si vende a un altro cliente, il volume raddoppia). In un legacy, si esegue con i volumi misurati in N6, prima del primo deployment successivo alla normalizzazione. Forma: un solo invio; l'agente carica, misura e rompe; tu leggi i numeri e il punto di rottura. Dimensione: proporzionale: in un progetto piccolo, un'esecuzione al volume atteso e una al "per dieci"; in uno con conseguenze, completo, con il punto di rottura trovato e le soglie registrate per il monitoraggio.

A cosa serve

Il gradino 3 ha dimensionato con i conti; questo gradino verifica i conti con il sistema reale in esecuzione. Voglio sapere tre cose prima che entri il primo utente: come si comporta il sistema al volume che il business ha dichiarato (la schermata più usata risponde in un tempo che il proprietario tollererebbe?), come si comporta al "per dieci" (regge, o cosa smette di reggere per primo?), e dove si rompe: il carico esatto al quale qualcosa cede, e cos'è quel qualcosa (le connessioni al database, la memoria, una coda, un blocco). Il punto di rottura è il numero più utile di tutta la fase, perché da lì escono le soglie di allerta del gradino 21: un'allerta messa "a occhio" avvisa tardi o avvisa sempre; un'allerta messa sotto il punto di rottura misurato, con un margine, avvisa quando c'è ancora tempo. Gli schemi di scala che ho ricavato da un sistema in produzione Ref. 12 e la batteria che moriva per memoria e sembrava un test fallito Ref. 44 sono i due antecedenti: il primo, del misurare il carico reale; il secondo, del fatto che un punto di rottura non trovato in tempo si traveste da altro.

Se sei alle prime armi. Una prova di carico è un programma che simula molti utenti che usano il sistema nello stesso momento, per vedere cosa succede. Il rendimento (throughput) è quante azioni al secondo regge. La latenza è quanto ci mette un'azione a rispondere; si guarda la mediana (metà delle azioni ci ha messo meno di questo) e il percentile 95 (il 95 % ci ha messo meno di questo; il restante 5 % sono gli utenti che si lamentano). Il punto di rottura è la quantità di carico alla quale qualcosa smette di funzionare: non "diventa lento" ma "le connessioni al database si sono esaurite" o "la memoria si è riempita". E una soglia è un numero limite a partire dal quale il monitoraggio avvisa.

1. Contesto richiesto

Quello che segue è la lista generica. I file concreti che devi avere pronti prima di ogni prompt, con il loro contenuto e il loro stato minimo, stanno nella sezione 2, nel blocco "Prima di inviare il prompt" che precede ciascuno.

• Il dimensionamento (gradino 3 o N6): il volume atteso e il "per dieci".
• L'osservabilità (16) accesa, per vedere cosa si rompe.
• La persistenza ottimizzata (17) con i suoi budget.
• Un ambiente di test simile alla produzione nelle risorse, o la consapevolezza di in cosa differisce.
• I flussi critici (quelli dell'albero semantico, o quelli della caratterizzazione in un legacy).

2. Prompt

Iniziale (caricare, misurare, rompere):

Cosa gli sto chiedendo: uno script di carico che è un misuratore come gli altri (vive nel repository e ha il suo test, perché uno script di carico che non esercita il flusso misura l'aria); tre esecuzioni (atteso, per dieci, fino a rompere); i numeri con i comandi; il confronto con i budget, la tolleranza del business e le ipotesi del dimensionamento, che è dove si scopre che il gradino 3 si era sbagliato in qualcosa; e niente ottimizzazioni per ora, perché ottimizzare senza leggere la diagnosi è cambiare ciò che non era.

Di chiusura (soglie e voci in sospeso):

Cosa gli sto chiedendo: le soglie di allerta derivate dal punto di rottura, che è l'aggancio con il gradino 21; i colli di bottiglia come voci in sospeso con il numero come criterio (così si chiudono con una prova e non con "adesso va meglio"); e la prova di carico come cancello archiviato, perché tra sei mesi si possa confrontare.

3. Risultato atteso

• Lo script di carico nel repository, con test.
• docs/PERFORMANCE_[data].md con le tre esecuzioni, i numeri, il punto di rottura e la diagnosi; docs/PERFORMANCE.md con le soglie e il cancello.
• Una voce in sospeso per ogni collo di bottiglia sotto il volume deciso.
• La prova di carico come cancello prima dei deployment che la richiedono.

4. Verifica di completezza

• La schermata più usata, al volume atteso, ci mette meno della tolleranza del proprietario? Se no, c'è una voce in sospeso aperta con quel numero.
• Il punto di rottura dice cosa si è rotto e a quale carico, o dice "il sistema è diventato lento"?
• Le soglie di docs/PERFORMANCE.md stanno sotto il punto di rottura e sopra l'atteso?
• Esegui tu lo script al volume atteso con il comando che ti ha dato: i numeri si somigliano?
• L'ambiente di test differisce dalla produzione nelle risorse, ed è annotato in cosa?

5. Segnali d'allarme

• "Regge il per dieci senza problemi" senza un punto di rottura. Se non ha trovato dove si rompe, non ha alzato abbastanza il carico.
• Lo script di carico colpisce l'API ma non passa dalla schermata, in un sistema dove è la schermata a caricare. Misura un'altra cosa.
• I risultati sono di un'esecuzione sulla macchina dell'agente, non nell'ambiente di test.
• Sono stati sistemati colli di bottiglia durante la prova, "già che c'ero". Adesso non sai quale numero corrisponde a quale versione.

Passo 20 — Documentazione viva e manuali che una persona può seguire senza IA (contratto del gradino)

Fase: uscita in produzione. Quando: il manuale utente cresce con ogni blocco funzionale, alla chiusura, con le schermate nuove; alimentato dalle voci in sospeso chiuse, che sono la documentazione di ciò che è stato fatto. I tre manuali completi si generano nella fase di uscita in produzione, dopo il 15, e la prova con una persona che non programma si fa prima del primo deployment. La routine dello stesso commit vale per tutto l'esercizio. Forma: routine; più un invio lungo quando si generano i manuali. Dimensione: proporzionale. Un sistema piccolo ha bisogno, come minimo, del manuale di infrastruttura e ripristino; quello utente può essere una pagina. Ciò che non cambia: se la persona che l'ha costruito sparisce, un'altra deve poter andare avanti.

A cosa serve

Fai in modo che il sistema si possa usare, mantenere e ripristinare senza l'agente e senza di te. Se il giorno in cui non c'è l'agente non si può distribuire, non è finito. Nel metodo classico la documentazione era cara e invecchiava; qui rigenerarla è gratis, quindi la regola diventa "nello stesso commit" e "riproducibile a mano". I manuali che ho scritto per la Mutua con quel criterio sono il modello Ref. 24; e il file di progetto che è diventato uno storico di migliaia di righe è il controesempio Ref. 41.

Un criterio di qualità per il manuale di ripristino, che serve a giudicarlo senza essere tecnici: deve poterlo seguire una persona di fiducia che non programma, alle tre del mattino, con il sistema giù e l'agente senza connessione. Se in qualche passo dice "consultare lo sviluppatore" o "a seconda del caso", quel passo è incompleto.

E una fonte da non sprecare: le voci in sospeso chiuse. Ognuna porta la sua specifica, la sua decisione, la sua prova e la sua data. Il manuale utente non si scrive da zero alla fine: si compone, blocco per blocco, a partire dalle voci in sospeso che si sono chiuse, e il diario delle modifiche esce direttamente da loro.

1. Contesto richiesto

Quello che segue è la lista generica. I file concreti che devi avere pronti prima di ogni prompt, con il loro contenuto e il loro stato minimo, stanno nella sezione 2, nel blocco "Prima di inviare il prompt" che precede ciascuno.

• Chi sono i lettori di ogni manuale: l'utente finale, chi mantiene, chi opera l'infrastruttura. Lo sa il business; l'agente chiede se non è chiaro.
• Il sistema in esecuzione nell'ambiente di test, per fare schermate reali.
• Le voci in sospeso chiuse del blocco, con la loro documentazione di chiusura (gradino 5).
• docs/DEPLOYMENT.md (gradino 15) e docs/LOCKS.md (gradino 14), che sono input.

2. Prompt

Routine (va nel patto di convivenza):

Cosa gli sto chiedendo: la regola dello stesso commit, che è l'unica che mantiene un manuale aggiornato; la chiusura del blocco come momento in cui le voci in sospeso chiuse diventano manuale e diario delle modifiche; e la domanda quando non è chiaro a quale manuale va.

Per generare i manuali:

Cosa gli sto chiedendo: i tre manuali con i loro lettori; schermate reali dell'ambiente di test (non disegni né descrizioni); il criterio delle tre del mattino per quello di ripristino; la clausola di completezza nella sua forma per documentare: ciò che solo il business sa si chiede, e non si lascia un buco né si inventa; e data e versione, perché si sappia a quale sistema corrisponde ogni manuale.

3. Risultato atteso

• docs/USER_MANUAL.md (o HTML), con schermate reali e incorporate, cresciuto blocco per blocco.
• docs/MAINTENANCE_MANUAL.md.
• docs/INFRASTRUCTURE_AND_RECOVERY_MANUAL.md: passo per passo, per una persona.
• docs/CHANGELOG.md, alimentato dalle voci in sospeso chiuse.
• Ciascuno con la data e la versione del sistema che documenta.
• Nei commit che cambiano schermate, esercizio o deployment: il manuale aggiornato.

4. Verifica di completezza

• Apri il manuale utente su una schermata a caso: la schermata coincide con ciò che c'è oggi nell'ambiente di test?
• Il manuale di ripristino lo potresti seguire tu, o qualcuno di fiducia che non programma? Leggi la sezione "è andato giù": dice cosa fare, in ordine, con i comandi?
• Scegli un commit recente che ha cambiato una schermata: ha toccato il manuale?
• Il diario delle modifiche ha una voce per ogni voce in sospeso chiusa dell'ultimo blocco?
• C'è un buco tipo "[completare]" o "consultare il responsabile"? Lì l'agente doveva chiedere.
• Ogni manuale dice per quale versione del sistema vale?

5. Segnali d'allarme

• Il manuale utente ha schermate di una versione che non esiste più. È stato generato una volta e non mantenuto: la regola dello stesso commit non è nel patto o non si sta applicando.
• Il manuale di ripristino comincia con "apri una sessione con l'agente". Se l'agente è un prerequisito, non è un manuale per una persona.
• Nessuno fuori dal costruttore ha mai letto il manuale di ripristino. Chiedi a qualcuno di seguirlo nell'ambiente di test; ciò che lo blocca è ciò che va corretto.

Passo 21 — Monitoraggio di risorse, funzioni e query fuori range, con rapporto ciclico (contratto del gradino)

Fase: esercizio. Quando: si monta nella fase di esercizio, con il primo deployment in produzione, con le soglie del 19 e le metriche del 16; da allora gira da solo, e il rapporto ciclico si legge con il proprietario a ogni ciclo (settimanale in un sistema con conseguenze, mensile in uno piccolo). Ogni evento fuori range entra nel ciclo come voce in sospeso correttiva. In un legacy, uguale, con una differenza: la prima lettura del rapporto è la linea base, e ciò che era già fuori range il primo giorno diventa voci in sospeso con la loro marca di velocità. Forma: un solo invio per montare; poi, routine ciclica. Dimensione: minimo in un progetto piccolo (un rapporto mensile, un'allerta sul disco e una sugli errori del database); completo in uno con conseguenze (soglie per funzione e per query, allerte, rapporto settimanale).

A cosa serve

Le prove del gradino 19 dicono come si comporta il sistema un giorno, con un carico che ho scelto io. La produzione è tutti i giorni, con il carico che scelgono gli utenti, con i dati che crescono, e con modifiche che entrano ogni settimana. Ciò che era in range a ottobre esce dal range a marzo senza che nessuno cambi nulla, solo perché la tabella è cresciuta. Questo gradino esiste perché quella cosa si veda prima che la veda l'utente: l'uso delle risorse contro la capacità, il tempo di risposta di ogni funzione, ogni punto di ingresso, ogni processo e ogni query, confrontato con le soglie del 19 e con la propria storia; un'allerta quando qualcosa esce dal range; e un rapporto ciclico che io leggo con il proprietario, dove ogni scostamento ha una causa o una voce in sospeso. Il tetto stretto a ciò che era stato misurato Ref. 37 è l'idea di fondo: il range non è un'opinione, è il numero misurato più un margine; e la quota di integrazione continua che si è bruciata senza che nessuno guardasse Ref. 39 è il fallimento che evita: una risorsa che si consuma senza monitoraggio si scopre quando finisce.

Due regole che non negozio. Un'allerta che scatta e nessuno legge è un difetto dell'allerta, non di chi non l'ha letta: si aggiusta o si elimina. E una soglia non si alza per far tacere un'allerta senza una ragione misurata e scritta.

Se sei alle prime armi. Monitorare è guardare il sistema tutto il tempo a macchina e avvisare quando qualcosa esce dal normale. Le risorse sono ciò che il sistema consuma: processore, memoria, disco, connessioni al database, e anche le quote di servizi esterni (quanti messaggi al mese ti lascia mandare il provider). "*Fuori range*" vuol dire sopra una soglia (un limite fisso, uscito dalle prove del gradino 19) o molto diverso dalla linea base (ciò che quello stesso numero dava negli ultimi giorni). Un'*allerta* è l'avviso sul momento; il rapporto ciclico è il riassunto che si legge ogni settimana o ogni mese con calma.

1. Contesto richiesto

Quello che segue è la lista generica. I file concreti che devi avere pronti prima di ogni prompt, con il loro contenuto e il loro stato minimo, stanno nella sezione 2, nel blocco "Prima di inviare il prompt" che precede ciascuno.

• L'osservabilità (16): le metriche e i registri di cui si alimenta.
• Le soglie del 19 e i budget del 17.
• La produzione distribuita (15), con accesso in sola lettura per il monitoraggio.
• Il canale delle allerte e il ciclo del rapporto: li decidi tu con il proprietario.

2. Prompt

Iniziale (montare e dimostrare):

La finestra della misurazione. Il report ciclico confronta le righe osservate per anno con quanto dichiarato al gradino 3. Un numero corretto con una finestra sbagliata apre un elemento in sospeso falso: nella pratica Turnera ereditata, 30.000 righe di tre anni passate come se fossero di uno. Per questo la misurazione porta la sua finestra verificabile: il primo e l'ultimo record letti dal database o dal log, non un numero scritto a mano. Se lo strumento non può leggere il database, lo dichiara come punto cieco; una finestra scritta a mano è segnata come tale nel report e si limita ad avvisare, non apre mai da sola un elemento in sospeso. (Decisione D-039.)

Cosa gli sto chiedendo: raccolta con storia (senza storia non c'è linea base, e senza linea base non c'è "fuori range"); allerte contro due riferimenti, la soglia assoluta del 19 e lo scostamento relativo sulla propria storia; il rapporto ciclico con la forma di un rapporto del gradino 12 (ogni scostamento con causa o con proposta, niente "tutto normale"); la conversione di ogni scostamento in voce in sospeso con numero; e le due dimostrazioni: il primo rapporto e un'allerta provocata.

Routine di ogni ciclo (va nel patto di convivenza):

Cosa gli sto chiedendo: che il rapporto si legga e si decida, con una traccia; e la regola della soglia, che è quella che evita che il monitoraggio diventi silenzioso un po' alla volta.

3. Risultato atteso

• Raccolta di risorse e tempi di risposta con storia, senza dati personali.
• Allerte per soglia e per scostamento, a un canale che una persona legge.
• Il rapporto ciclico, generato da solo, con ogni scostamento con causa o proposta.
• docs/MONITORING.md con soglie, canale, ciclo e come silenziare con una ragione.
• La routine nel patto; gli scostamenti come voci in sospeso correttive.

4. Verifica di completezza

• Chiedi che si superi una soglia apposta in test: ti è arrivata l'allerta, dal canale concordato, con l'identificatore?
• Leggi l'ultimo rapporto: ogni evento fuori range ha una causa o una proposta? Qualcuno è rimasto senza niente?
• C'è una voce in sospeso per ogni scostamento che hai deciso di affrontare, con il numero come criterio?
• Qualche soglia è salita dal 19? Con quale ragione scritta?
• Il rapporto menziona la quota dei servizi esterni (messaggistica, integrazione continua)?

5. Segnali d'allarme

• Le allerte scattano tutti i giorni e nessuno le legge. Bisogna abbassarne il numero finché ciascuna non significhi qualcosa, non abituarsi.
• Il rapporto dice "tutto normale" per tre cicli di fila. O il sistema non ha utenti, o il rapporto non guarda ciò che conta.
• Una soglia è salita "perché smetta di avvisare". È il gradino 21 che muore in silenzio.
• Il monitoraggio conserva dati personali "per poter diagnosticare". È una fuga di dati con orario.

Passo 22 — Monitoraggio degli errori e rapporto ciclico: nessun errore senza voce in sospeso (contratto del gradino)

Fase: esercizio. Quando: si monta nella fase di esercizio, con il primo deployment, insieme al 21, sui registri del 16; da allora gira da solo, con allerte sul momento e un rapporto ciclico che si legge con il proprietario. Ogni errore nuovo entra nel ciclo come voce in sospeso correttiva e si chiude con il test che lo riproduce in rosso. In un legacy, la prima lettura è la linea base: gli errori che esistevano già il primo giorno diventano voci in sospeso con la loro marca di velocità, e nessuno resta come "noto" senza una voce in sospeso che dica perché si tollera e fino a quando. Forma: un solo invio per montare; poi, routine ciclica. Dimensione: obbligatorio in ogni progetto con utenti: la cattura centralizzata e il rapporto non si negoziano; le allerte sul momento, proporzionali.

A cosa serve

Un sistema in produzione produce errori che nessun utente segnala: quello di chi ha visto la schermata bianca ed è tornato a provare, quello del processo notturno che è fallito e nessuno guarda, quello della chiamata esterna che ha restituito un errore e il codice si è ingoiato. Se non li catturo, non esistono finché non esistono troppo. Questo gradino è la controparte del 21: quello sorveglia il rendimento, questo sorveglia gli errori, e tutti e due finiscono nello stesso posto, il ciclo, come voci in sospeso correttive. Le regole di fondo sono due. Nessun errore senza voce in sospeso: un errore nuovo ne apre una, e si chiude con il test che lo riproduce in rosso, come chiede la modalità correttiva del percorso evolutivo. E non esiste l'"errore noto" senza una voce in sospeso che dica perché si tollera e fino a quando; "quell'errore c'è sempre stato" è la frase con cui un sistema marcisce. L'errore di autenticazione riportato come successo Ref. 43 e i quattro giri fino alla causa radice Ref. 22 sono i due antecedenti: il primo, del fatto che gli errori si nascondono se non li si cattura a macchina; il secondo, del fatto che un errore senza riproduzione si sistema più volte.

Se sei alle prime armi. Un errore è qualunque cosa che il sistema ha provato a fare e non ha potuto: una schermata che non si è caricata, un processo notturno che si è interrotto, una chiamata a un altro servizio che è fallita. Un'*eccezione non gestita* è un errore che il codice non aveva previsto e che interrompe ciò che stava facendo. Catturare un errore è salvarlo con tutti i suoi dati (quando, in quale versione, con quale identificatore, lo stack, che è la lista dei passi del programma fino al guasto) in un solo posto centrale, invece di lasciarlo perdere nella schermata di un utente. Raggruppare è mettere insieme le mille volte in cui è successo lo stesso errore in un'unica voce con un contatore. E il tasso di errore per flusso è, su cento volte che qualcuno ha caricato un appuntamento, quante sono fallite.

1. Contesto richiesto

Quello che segue è la lista generica. I file concreti che devi avere pronti prima di ogni prompt, con il loro contenuto e il loro stato minimo, stanno nella sezione 2, nel blocco "Prima di inviare il prompt" che precede ciascuno.

• L'osservabilità (16): gli errori arrivano con identificatore di correlazione, versione e attore.
• La tabella dei lucchetti (14): gli errori nelle azioni con conseguenza sono allerta immediata.
• La produzione distribuita (15), con il browser dell'utente incluso nella cattura.
• Il canale delle allerte e il ciclo del rapporto, condivisi con il 21.

2. Prompt

Iniziale (montare e dimostrare):

Gli errori dello strumento non sono errori del sistema. La cattura centralizzata separa per fonte: gli errori del sistema e quelli degli strumenti che lo osservano (il pannello, l'agente residente, il monitoraggio stesso) si conservano con fonte distinta, il report li elenca in sezioni separate, e solo quelli del sistema aprono elementi in sospeso. Nella pratica Turnera, il primo report ciclico aprì sei "bug" che erano il pannello di Forge che parlava con un server spento. (Decisione D-038.)

Cosa gli sto chiedendo: la cattura nei tre posti dove gli errori si nascondono (backend, processi, browser), con l'identificatore del 16 per poterli seguire; il raggruppamento, senza il quale il rapporto è una lista di diecimila righe; le tre allerte che contano (nuovo, ricorrente che cresce, con conseguenza); il rapporto con il tasso per flusso, che è il numero che il proprietario capisce; le due regole; e la dimostrazione da un capo all'altro, dal browser al rapporto.

Routine di ogni ciclo (va nel patto di convivenza):

Cosa gli sto chiedendo: la disciplina del ciclo, e la regola dell'errore che sparisce, che è la più controintuitiva e quella che vale di più: un errore che se n'è andato da solo torna da solo.

3. Risultato atteso

• Cattura centralizzata degli errori in backend, processi e browser, raggruppati per causa, senza dati personali.
• Allerte per errore nuovo, ricorrente che cresce, e con conseguenza.
• Il rapporto ciclico con il tasso di errore per flusso.
• docs/MONITORING.md completo (con il 21); la routine nel patto.
• Una voce in sospeso per ogni errore aperto; nessuno "noto" senza voce in sospeso.

4. Verifica di completezza

• Provoca tu un errore nel browser in test (un'azione che sai che fallisce): è comparso nella cattura con il tuo identificatore, e ti è arrivata l'allerta?
• Leggi l'ultimo rapporto: c'è qualche errore ricorrente senza voce in sospeso né ragione?
• Prendi un errore "sistemato" del rapporto: la voce in sospeso ha il test che lo ha riprodotto in rosso?
• Il tasso di errore per flusso c'è, ed è sceso o salito rispetto al periodo precedente?
• Cerca un dato personale nella cattura degli errori: non ci deve essere.

5. Segnali d'allarme

• Zero errori in produzione per un mese con utenti reali. Non esiste un sistema così; la cattura non sta vedendo il browser o i processi.
• Un errore con mille occorrenze e un commento "noto, non influisce". Senza voce in sospeso, senza data.
• Gli errori si "sistemano" riavviando il servizio. Spariscono e tornano.
• Il rapporto degli errori e quello delle risorse li legge gente diversa e nessuno li incrocia: la query lenta del 21 è la causa del timeout del 22.

Passo 23 — L'agente dentro il sistema, e la retrospettiva con i numeri (contratto del gradino)

Fase: esercizio. Quando: l'agente residente, all'entrata in esercizio, dopo il primo deployment in produzione. La retrospettiva, alla chiusura di ogni tappa e del progetto; torna al gradino 0 per il progetto successivo. Fai girare anche una retrospettiva breve quando cambia il modello che costruisce: un contratto calibrato per un modello non necessariamente rende uguale con un altro, e un cambio di modello è esattamente il tipo di scoperta che questa scala chiede di trasformare in una proposta di cambiamento, non in una sorpresa scoperta a metà di un blocco. Forma: due parti: una conversazione per definire il perimetro dell'agente residente, e un invio lungo per la retrospettiva. Dimensione: l'agente residente è opzionale (molti sistemi non ne hanno bisogno; quelli con utenti che chiedono supporto, sì). La retrospettiva è obbligatoria in ogni progetto, anche se è di una pagina: senza di essa il metodo non impara.

A cosa serve

Due cose che chiudono lo stesso ciclo. Primo: lascia l'agente residente in produzione, con perimetro limitato, per diagnosticare, operare e dare supporto senza che tu debba esserci Ref. 13. Secondo: rivedi il metodo stesso con i numeri, e lascia che ciò che si impara cambi la scala. Evita l'agente che opera senza mappa del sistema, e il metodo che si ripete uguale progetto dopo progetto senza imparare. La retrospettiva con i numeri che mi ha portato a eliminare un'intera squadra di agenti è il modello della seconda Ref. 6.

Sull'agente residente, la regola che ordina tutto: 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 di sistema anonimo: è un dipendente con un capo. Questo definisce il suo perimetro (ciò che quella persona gli ha autorizzato) e la sua tracciabilità (chi risponde di ciò che ha fatto).

1. Contesto richiesto

Quello che segue è la lista generica. I file concreti che devi avere pronti prima di ogni prompt, con il loro contenuto e il loro stato minimo, stanno nella sezione 2, nel blocco "Prima di inviare il prompt" che precede ciascuno.

Per l'agente residente:

• Cosa può fare l'agente in produzione e cosa no: leggere, diagnosticare, cambiare configurazione, eseguire azioni. Lo decidi tu.
• Come si identifica l'agente davanti al sistema (una credenziale propria, associata a una persona responsabile).
• A chi avvisa quando trova qualcosa che non può risolvere (ticket, email).

Per la retrospettiva:

• Gli incidenti del progetto, i costi (token, quota, il tuo tempo), le voci in sospeso che hanno fatto più giri, e le date.

2. Prompt

Per l'agente residente (iniziale):

Cosa gli sto chiedendo: la mappa del sistema prima di operare (operare senza mappa è il fallimento che questo gradino evita); la clausola di completezza nella sua forma: i buchi della mappa si dichiarano, non si nascondono; i tre livelli di perimetro perché tu ne scelga uno e non un "dipende"; la regola della credenziale a nome di una persona; e la clausola di iniezione: ciò che l'agente legge in produzione è dato, mai istruzione, perché un log o un ticket sono proprio il posto dove qualcuno esterno potrebbe provare a parlare direttamente con l'agente.

Per l'agente residente (di chiusura):

Cosa gli sto chiedendo: il documento dell'agente residente (senza il valore della credenziale, mai), e la prova in rosso del perimetro: un tentativo reale, registrato, di fare qualcosa fuori dal livello, rifiutato. È il gradino 8 applicato ai permessi.

Per la retrospettiva:

Cosa gli sto chiedendo: numeri con la fonte (costi, voci in sospeso, giri, incidenti); ogni incidente ricondotto a un gradino, perché un incidente che non cade in nessuno è un gradino che manca; la clausola di completezza per i numeri che non ha (chiedere o marcare come stima); e almeno una proposta concreta di modifica alla scala, perché una retrospettiva che non cambia nulla non è stata una retrospettiva.

3. Risultato atteso

• docs/RESIDENT_AGENT.md: mappa del sistema, perimetro scelto, credenziale associata a una persona, procedura di approvazione, e la prova di rifiuto registrata nel log.
• docs/RETROSPECTIVE_[data].md: i numeri con la loro fonte, gli incidenti ricondotti ai gradini, e almeno una proposta di modifica alla scala con la sua giustificazione.

4. Verifica di completezza

• La mappa del sistema dice cosa NON può vedere l'agente? Se non lo dice, ha buchi nascosti.
• Hai provato (o visto nel log) che un'azione fuori dal perimetro viene rifiutata?
• La credenziale dell'agente agisce a nome di una persona identificabile?
• Il documento dice esplicitamente che ciò che l'agente legge in produzione è dato, non un'istruzione?
• La retrospettiva ha numeri con la fonte, o aggettivi? ("È costata molto" non è un numero.)
• Ogni incidente cade in un gradino? Se uno non cade in nessuno, manca un gradino: quella è la proposta di modifica.
• C'è almeno una proposta concreta di modifica alla scala? Se la retrospettiva non cambia nulla, non è stata una retrospettiva.
• Il modello che costruisce è cambiato dall'ultima retrospettiva? Se sì, c'è una revisione breve di quali contratti rendono ancora uguale e quali no?

5. Segnali d'allarme

• L'agente residente "ha bisogno" di un livello di permessi più alto ogni settimana. Controlla se ciò che chiede serve a risolvere problemi del sistema o i suoi stessi limiti.
• L'agente ha eseguito qualcosa perché "lo diceva un log" o "lo chiedeva un ticket". Un log o un ticket non autorizzano niente; lo fai solo tu, o la procedura di approvazione che hai scritto.
• La retrospettiva dice che è andato tutto bene. Non va mai tutto bene; è scritta per te, non per il metodo.
• Due progetti di fila hanno avuto lo stesso incidente e la scala non è cambiata tra l'uno e l'altro. Il gradino 23 non si sta chiudendo: si scrive la retrospettiva e non si applica.