Metodo · software con IA · open source
Urazuke, il metodo del riscontro.
Urazuke (裏付け) è la parola giapponese per il sostegno che ha un'affermazione: ciò che la regge da dietro. È il mio metodo per costruire software con l'intelligenza artificiale che risulti robusto e pronto per la produzione, senza che il proprietario del progetto debba leggere una sola riga di codice. L'ho distillato da tre sistemi reali che oggi ho in produzione, appoggiandomi all'ingegneria dei sistemi di sempre e a ciò che quei sistemi mi hanno insegnato su dove i modelli la applicano in modo fragile.
Autore: Pablo Kuschniroff, assistito da Claude Code.
Creative Commons BY-SA 4.0 · Otto lingue · Neutrale rispetto allo strumento · Tre sistemi in produzione come fonte · Open source e collaborativo
La tesi
L'IA non interrompe il metodo: lo continua.
Prima della tesi, un chiarimento che mi sta a cuore: questo metodo non è una raccolta di toppe messe dopo ogni colpo. Nasce da due fattori combinati. Il primo è la mia conoscenza dell'ingegneria dei sistemi: rilevazione, requisiti, dimensionamento, test come prova, deployment riproducibile, audit; la porto da molto prima che esistessero questi modelli. Il secondo è ciò che tre sistemi in produzione mi hanno mostrato, incidente dopo incidente: dove i modelli applicano quei principi in modo fragile, e quindi dove bisogna stringere per iscritto. Le cicatrici provano dove serve la rigidità; non sono l'origine dei principi.
L'industria ha smesso di fidarsi dell'autore del codice vent'anni fa. Quando la scrittura è passata a team junior, esternalizzati o a rotazione, la revisione riga per riga è diventata insostenibile, e al suo posto è cresciuto tutto ciò che oggi diamo per scontato: test automatizzati, integrazione continua, criteri di accettazione, pipeline che non lasciano passare nulla senza il verde. Quella è stata la risposta dell'ingegneria dei sistemi a "chi scrive non è affidabile": non leggergli il codice, esigergli prove. Il modello è l'autore successivo, non il primo di cui diffidare.
Dove va lo sforzo dell'umano
L'umano fa solo due cose: decide, e verifica artefatti. Redigere, costruire, testare, misurare e documentare lo fa il modello. Ogni gradino termina in una verifica di completezza senza leggere codice.
La prova dimostra se stessa
Un test che non hai mai visto fallire non sai se prova qualcosa. Un misuratore senza test mente. Un rapporto senza punti ciechi nasconde. La disciplina di indipendenza del controllo qualità, portata un passo più dentro.
Il costo degli artefatti
Prima la documentazione era cara e invecchiava. Ora rigenerarla è gratis, quindi la regola diventa "nello stesso commit" e "riproducibile a mano, senza IA". Ciò che era un ideale irraggiungibile diventa un cancello.
Cos'è e cosa non è
Ingegneria dei sistemi applicata a un costruttore che non si stanca e a cui non si può credere.
A chi viene dai sistemi suona familiare: rilevazione, requisiti, dimensionamento, progettazione, costruzione, test, deployment, esercizio, audit. A chi viene dal vibecoding dà ciò che non ha, che è proprio lo scheletro.
Cos'è
- Un metodo: cosa fare in quale ordine, cosa chiedere al modello, cosa deve consegnare, e come sapere che è completo.
- Ventiquattro gradini in quattro fasi, ciascuno con un contratto: contesto, prompt, risultato atteso, verifica, segnali d'allarme.
- Neutrale rispetto allo strumento: Claude Code, Cursor, Codex CLI, Gemini CLI o Forge. Ogni artefatto è un file, un test o uno script.
- Distillato da tre sistemi reali in produzione, con ogni regola legata al commit e al colpo che l'ha originata.
Cosa non è
- Un corso di programmazione né di un framework.
- Una raccolta di trucchi per i prompt perché il modello scriva meglio.
- Un metodo per il prototipo della demo di venerdì: è per ciò che deve continuare a funzionare dopo.
- Un metodo che serve per qualunque progetto. Il gradino 0 definisce il confine per iscritto.
La scala
Ventiquattro gradini, quattro fasi, nell'ordine in cui si salgono.
I gradini sono numerati nell'ordine cronologico in cui si salgono. Quelli di avvio una volta per progetto; quelli del ciclo a ogni modifica; quelli di messa in produzione una volta, prima del primo deploy; quelli di esercizio quando il sistema è vivo. Il 23 chiude il ciclo e torna allo 0. Ogni gradino ha una scheda in otto parti e un contratto con i prompt. Niente scadenze: il metodo è un processo, non una promessa di velocità.
Una volta per progetto, prima di scrivere funzionalità
I cinque che danno più tentazione di saltare e costano più caro da saltare.
A ogni modifica, per tutto il progetto
Nell'ordine in cui si fanno con ogni voce in sospeso. Si imparano sui primi due blocchi e si praticano per tutto il progetto.
Una volta, prima del primo deploy
Trasformano "funziona" in "si può sostenere": audit, lucchetti, pipeline verso la produzione, osservabilità, persistenza, vulnerabilità, prestazioni e manuali.
Quando il sistema è già vivo
I due monitoraggi con rapporto ciclico, l'agente residente e la retrospettiva che chiude il ciclo e torna allo 0.
Tredici gradini non negoziabili in nessun progetto
- Idoneità (un'ora; risparmia mesi)
- Patto di convivenza
- Definizione corta, con "cosa NON è"
- Dimensionare con i numeri del business
- Le voci in sospeso come piano
- Decisioni con proprietario e data
- Test visti in rosso
- Rapporto verificato / creduto / punti ciechi
- Retrospettiva con numeri
- Scansione di dipendenze e segreti nella pipeline
- Cattura centralizzata degli errori e rapporto
- Qualità del codice nella pipeline, al minimo
- Casi di test manuale eseguiti da persone
La linea del tempo
Quando si sale ogni gradino, e cosa succede nel mezzo.
Un metodo senza linea del tempo è una lista di buone intenzioni. Questa è quella di qualsiasi progetto: cinque fasi, in ordine, e in ciascuna ciò che si fa oltre ai gradini: la raccolta dei requisiti, l'infrastruttura, la pipeline di integrazione e deploy, lo sviluppo, i test end-to-end, lo sguardo umano, i test umani. Senza scadenze: ogni fase dura quanto il sistema richiede.
Ingestione
Rilevazione con il proprietario, con i metodi classici dell'ingegneria dei requisiti: interviste, casi d'uso, modello di dominio con i suoi stati, prototipi di schermata. In prosa, incompleta apposta: l'agente la completa chiedendo.
Avvio (gradini da 0 a 4)
Idoneità, patto, definizione con albero semantico, dimensionamento. E tutta l'infrastruttura iniziale con la catena CI/CD: repository, ambiente di prova, integrazione continua, primo deployment con il sistema vuoto. Il proprietario apre l'URL e vede la schermata vuota.
Ciclo (gradini da 5 a 12)
Blocco funzionale per blocco. Con ogni voce in sospeso: specifica, decisioni, test in rosso, prova end to end del flusso, screenshot che il proprietario guarda. Alla chiusura di ogni blocco: la batteria completa end to end e prove umane nell'ambiente di prova.
Messa in produzione (da 13 a 20)
Audit da parte di un'altra sessione. Lucchetti prima di costruire ciò che incassa o invia. Chiusura della catena verso la produzione con rollback provato. I tre manuali. Prove di accettazione del proprietario su tutti i flussi. E i quattro gradini di qualità operativa prima del deploy: osservabilità, persistenza, vulnerabilità, prestazioni.
Esercizio (da 21 a 23 e il ciclo)
Agente residente a nome di una persona. Audit periodico. Ogni evoluzione entra dal ciclo completo ed esce dalla catena di deployment. Retrospettiva con i numeri alla chiusura di ogni tappa. I due monitoraggi, risorse ed errori, montati nella settimana del primo deploy, con un rapporto ciclico che il proprietario legge.
Le prove end to end non sono una volta sola alla fine
Con ogni voce in sospeso, il flusso che ha toccato. Alla chiusura di ogni blocco, tutti i flussi che esistono. Prima della produzione, tutti i flussi con la versione esatta che verrà promossa. Se fai solo la terza, arrivi alla fine con settimane non provate.
I tre casi d'uso
Cartella vuota, sistema fatto con il metodo, o sistema ereditato: da dove si entra.
La scala è scritta guardando una cartella vuota, che è il caso più chiaro per imparare e non il più frequente. Prima di aprire l'agente conviene sapere in quale dei tre casi sei, perché cambia da dove si entra. E il terzo, il sistema che esiste già e non è nato con il metodo, ha un cammino proprio: si normalizza senza riscrivere, e solo dopo si sale la scala.
Progetto nuovo
Cartella vuota e un proprietario con una richiesta. Si entra dal gradino 0 e si salgono i ventiquattro in ordine: una settimana di avvio prima della prima funzionalità. È ciò che descrivono il documento principale, i contratti e il corso.
Evolutivo-correttivo con metodo
Il sistema ha già salito la scala: ha un patto, una mappa, voci in sospeso chiuse con evidenza, batteria, deploy e manuali. Si entra dal gradino 5, aprendo un blocco, e si segue il ciclo. È il 15 che torna allo 0.
Evolutivo-correttivo senza metodo
Un sistema che gira, con utenti, fatto da altri o da te stesso senza evidenza. Otto stazioni di normalizzazione (da N0 a N7): recuperare per autoscoperta gli input che nessuno ha scritto, con marcature di fonte; una cintura di sicurezza come cancello duro; il debito pagato man mano che si tocca. Poi il ciclo, in modalità correttiva o evolutiva.
Leggi il cammino evolutivo-correttivo → Il corso, parte 2: il progetto ereditato →
Il contratto di ogni gradino
Come si chiede, cosa deve tornare, e come so che è tornato completo.
Ogni gradino si esegue con un contratto in cinque sezioni. I prompt per il modello sono in inglese, un unico pezzo identico nelle otto versioni del documento, e sotto ciascuno la spiegazione nella lingua del lettore di cosa stiamo chiedendo e perché ogni clausola è lì.
Contesto richiesto
Nominato in modo generico. Le rilevazioni sono per natura incomplete; non si completano con un modulo, le completa il modello chiedendo.
Prompt
Testuali. Tutti con la stessa clausola: il modello valuta se il contesto basta, chiede ciò che manca prima di proseguire, e non stima né inventa un dato che solo il business ha.
Risultato atteso
Le caratteristiche dettagliate dell'artefatto: quale file, quali sezioni, cosa non può mancare.
Verifica di completezza
Ciò che il proprietario controlla sull'artefatto senza leggere codice. Se uno dà "no", il gradino non è salito.
Segnali d'allarme
I sintomi che il gradino è stato salito male anche se sembra salito. Quelli che si vedono settimane dopo, quando fa già male.
Un prompt di esempio · gradino 7
docs/PENDING.md; la modifica già implementata; il comando della batteria in docs/STATUS.md; e l’ambiente di prova in esecuzione, con dati per il flusso toccato. Nella documentazione, ogni prompt è preceduto da un blocco così: quali file costruisci tu, con quale contenuto, e qual è lo stato minimo accettabile.Perché in inglese: lo stesso contenuto in un'altra lingua occupa tra il 30 e il 50 % di token in più, i modelli seguono le istruzioni con più precisione in inglese, e il vocabolario del mestiere è inglese. Ma non voglio che l'inglese sia una barriera: nella documentazione ogni prompt porta la sua traduzione nella lingua del documento e un pulsante come questo. Al modello si incolla l'inglese; la traduzione serve a te per capirlo. Tutti terminano con "Reply in my language".
Dal requisito alla voce in sospeso
Ingegneria dei requisiti di sempre, scomposta in unità che un modello può costruire e tu puoi verificare.
Un requisito non è una frase del cliente in una chat. È quella frase elaborata con metodi che esistono da decenni e che il modello applica molto bene se glielo chiedi e molto male se no: interviste, casi d'uso, modello di dominio, criteri di accettazione, prototipi di schermata, tracciabilità. Nel metodo, tre artefatti li sostengono.
L'albero semantico
Il sistema come un albero: i domini; sotto, attori, processi (i casi d'uso), entità con i loro stati, schermate e integrazioni; e da ogni nodo pendono le voci in sospeso e le decisioni. Lo costruisce l'agente, lo correggi tu, ed è ciò che l'agente legge prima di toccare codice. Una voce che non pende da nessun nodo è fuori perimetro, e lo si vede in dieci secondi.
La specifica dettagliata vive in ogni voce in sospeso
Il lungo documento di specifica che invecchiava si scompone: ogni voce porta il suo nodo dell'albero, la storia d'origine con le parole del cliente, la descrizione, le regole di business con decisione e data, i dati, le schermate, i casi limite, i criteri di accettazione e come si verifica. Leggere quella specifica è il più vicino che arriverai a leggere codice, ed è la distanza giusta.
Le voci in sospeso chiuse sono documentazione
Una voce chiusa non si cancella: resta con la sua specifica, la decisione che l'ha originata, la prova con cui è stata chiusa, il commit e la data. La coda delle voci chiuse è la storia funzionale del sistema; da lì escono il diario delle modifiche, il manuale utente, e la risposta a "perché il sistema fa questo" sei mesi dopo.
Con qualunque strumento
Gli artefatti sono file, test e script. Ciò che cambia è dove vanno.
Claude Code
Il patto e le routine vanno nel CLAUDE.md del progetto; i prompt di gradino si incollano nella chat salendo ogni gradino.
Cursor
Le routine vanno in .cursor/rules/ come regole sempre attive; il resto, uguale.
Codex CLI / Gemini CLI
In AGENTS.md o GEMINI.md nella radice del repository.
Yujin Forge
Il patto e le routine sono dottrine, i prompt si iniettano da soli attraversando ogni cancello, e il registro delle voci in sospeso è nativo. È lo stesso metodo con meno copia e incolla. Scopri Forge →
Il corso
Ventiquattro lezioni con compiti pratici, fino all'applicazione in produzione.
Un manuale tipo corso, una lezione per gradino, per applicare il metodo su un progetto proprio o sul progetto guida ("Turnera", un'agenda di appuntamenti con promemoria, caparre e dati personali: tutto ciò che serve perché nessun gradino sia finto). Termina con la lista di uscita in produzione: ventiquattro condizioni che il proprietario verifica senza aprire il codice. La parte 2 del corso prende lo stesso studio con un sistema ereditato ("Turnera ereditata") e insegna a normalizzarlo prima di correggerlo e farlo evolvere.
Cosa devi capire
Il concetto di ogni gradino, spiegato come lo si spiega a una persona, con il fallimento reale che l'ha originato.
Il compito, passo per passo
Con il prompt esatto per l'agente e cosa fare con ciò che restituisce. Include prove apposta: lasciare una domanda senza risposta e vedere cosa fa.
La verifica e il risultato da consegnare
Le domande che ti fai su ciò che è stato consegnato, senza aprire il codice, e il file o la prova che deve esistere alla fine.
Errori tipici e il progetto guida
Ciò che succede a quasi tutti la prima volta, e come appare ogni lezione applicata a Turnera.
Per chi entra
Lo sviluppatore junior nell'era dopo la programmazione a mano.
Se il modello scrive il codice, come si forma un junior, cosa impara e per diventare cosa? Un documento a parte sui focus di formazione che perdono peso, quelli che guadagnano, l'alfabetizzazione che resta obbligatoria, l'obiettivo e un piano di dodici settimane con mentore. Scritto per principianti, come tutto il metodo.
In squadra
Più sviluppatori, ciascuno con il proprio agente, sullo stesso branch.
Il metodo è scritto al singolare. Questo documento dice come si applica quando si è in più: le sette regole del branch condiviso (la voce in sospeso come unità di proprietà, integrare piccolo e spesso, l'integrazione continua come arbitro, ciò che è a metà dietro un interruttore, la mappa come rilevatore di conflitti, le decisioni con il nome, rivedere l'evidenza e non il codice), come si distribuiscono i gradini, e i prompt.
Tutto il materiale, in otto lingue
Leggilo nella tua lingua.
Lo spagnolo è la fonte della verità; le altre sette versioni sono traduzioni e, se divergono, prevale lo spagnolo. I prompt sono identici in tutte. Tre documenti per lingua: il documento principale (la tesi, la rilevazione dei tre sistemi, i ventiquattro gradini, i fallimenti reali e il glossario), i ventiquattro contratti e il manuale-corso. E dalla versione 5, altri due documenti per lingua: il cammino evolutivo-correttivo, per i sistemi che esistono già, e la parte 2 del corso con il progetto guida ereditato.
Il metodo è pubblicato con licenza Creative Commons Attribuzione-Condividi allo stesso modo 4.0: si può usare, tradurre e adattare, con attribuzione e con la stessa licenza. Il repository è pubblico e collaborativo: github.com/pkuschnirof/urazuke. I miglioramenti entrano tramite pull request da un fork, con la loro prova, e li integro dopo averli esaminati.
Esiste già con un altro nome? Ho indagato a fondo cosa c'è di simile fino a ottobre 2026 (Uncle Bob e il suo "gauntlet", Tsumiki, Spec Kit, Consort, IACDM, Osmani e altri), cosa conviene citare invece di rivendicare, cosa non ho trovato da nessuna parte, e l'obiezione più seria con la sua risposta. È nella Parte F del documento principale, "Lavori correlati".
Due manuali di esecuzione in Forge, passo passo e con schermate, fatti su progetti di pratica reali: progetto nuovo (Turnera) e progetto esistente (Turnera ereditata). Con le evidenze raccolte a ogni gradino (in spagnolo).
Altri due documenti, fuori dal corpus tradotto: le porte spiegate, in inglese, perché è documentazione di strumento e viene generata dai dati; e le valutazioni dei modelli di IA sul metodo, in spagnolo.
Se vuoi consumare il metodo con uno strumento, non serve leggere il repository: l’interfaccia dati è su yujin.app/urazuke/api/. Il suo indice elenca ogni risorsa con il suo indirizzo canonico, la sua versione e la sua impronta: gates.json, la definizione meccanica delle porte, e prompts.json, i prompt. L’impronta si ricalcola sul contenuto, quindi una copia vecchia si tradisce da sola.
Da dove viene
Tre sistemi in produzione, e quarantasei casi documentati con data e prova.
Ho rilevato in sola lettura tre repository che oggi sono in produzione con persone reali che li usano: lo strumento in cui il metodo ha preso forma (millenovanta commit in cinque mesi), un sistema di automazione per un ente sanitario con denaro e dati sensibili in gioco (seicentoquarantuno voci in sospeso, tutte chiuse), e uno sportello omnicanale per un'associazione civile (il primo in cui la misurazione precede sistematicamente la costruzione). Ogni caso che cito nel metodo è numerato nel documento dei riferimenti, perché le procedure restino pulite e il dettaglio resti a un clic. I clienti sono anonimizzati; i numeri, le date e i commit sono reali.
Dove il modello fallisce nell'applicare l'ovvio
Il misuratore che ha mentito due volte. L'errore di autenticazione riferito come successo. Le tre affermazioni su quattro che erano sbagliate. Ciascuno mi ha detto dove un principio per me ovvio doveva diventare una clausola esplicita del prompt.
Retrospettiva con i numeri
Ho eliminato un'intera squadra di agenti con sessanta dollari e settantatré minuti contro novanta minuti. Ho spezzato il deployment con ventiquattro-ventisette minuti contro undici. La scala stessa è questo.
Pablo Kuschniroff, assistito da Claude Code
RPAForce / Yujin. Il metodo si applica a se stesso: le sue decisioni sono registrate con data e parole testuali, e il repository è pubblico dal 18 ottobre 2026 su github.com/pkuschnirof/urazuke.
Domande frequenti
Domande frequenti.
- Devo saper programmare?
- No. Serve un proprietario del dominio con criterio e tempo per decidere, e nozioni minime di cosa sono un repository, un commit e un push. Il metodo esiste proprio perché il proprietario verifichi prove invece di leggere codice.
- Serve per qualunque progetto?
- No, e non è un difetto. Ci sono due condizioni escludenti: un repository standard in cui lasciare la prova, e schermate operabili da programma per provare end to end. Il gradino 0 mette il confine per iscritto.
- Mi servono Forge o NAC3?
- No. Il metodo è neutrale rispetto allo strumento; ogni artefatto è un file, un test o uno script. Forge automatizza i cancelli e l'iniezione dei prompt, ma il gradino esiste senza Forge. NAC3 è il mezzo con cui oggi otteniamo la testabilità delle schermate, non una condizione.
- Perché i prompt sono in inglese se la documentazione è nella mia lingua?
- Perché i modelli seguono le istruzioni con più precisione e meno token in inglese. Ogni prompt è un unico pezzo identico nelle otto versioni, spiegato sotto nella tua lingua, e termina con "Reply in my language".
- Quanto ci vuole per un progetto piccolo da cima a fondo?
- Non do una scadenza, apposta. Il metodo è un processo per fare sistemi operabili e manutenibili senza capire un bit di codice; non è un processo per costruire più in fretta, anche se la velocità compare come conseguenza. Ciò che il metodo fissa sono l'ordine e i cancelli; quanto dura ogni tappa lo decidono la dimensione e la complessità del tuo sistema.
- Come propongo un miglioramento?
- Con prove: il gradino 15 chiede che ogni retrospettiva termini con una proposta concreta di modifica alla scala, con l'incidente che la giustifica. Le proposte entrano tramite pull request da un fork su github.com/pkuschnirof/urazuke e le esamino prima di integrarle.
Esigi prove. Non leggergli il codice.
Un metodo perché il modello costruisca e tu decida e verifichi. In otto lingue, con licenza aperta, e con i colpi di tre sistemi reali perché tu non debba prenderti gli stessi.