Ratchet Agentic Engineering: perché copre la seconda metà del giro
· 6 min di lettura · metodo, agentic-engineering, cricchetto, harness-engineering
Gli strumenti di specifica portano una richiesta fino al codice. Il metodo copre quello che succede dopo: tetti che possono solo scendere, un test di guardia per ogni incidente, sonde sul sito pubblicato e un rilascio deciso da una persona.
Alle 00:33 del 7 settembre 2026 la telemetria degli errori di Seantral ha registrato «Minified React error #310»: un componente aveva chiamato più hook del render precedente. In GoodWindowTimeline un hook era finito sotto un return anticipato. Di notte, per il nuoto, l’elenco delle ore era vuoto e il componente usciva prima di arrivarci. Appena l’elenco si riempiva, l’hook veniva chiamato e React cadeva.
La regola di lint che riconosce questo errore, react-hooks/rules-of-hooks, era già nella configurazione, come avviso. In CI il lint completo non ferma il deploy, per un vecchio debito di any espliciti.
Lo stesso giorno è nato npm run lint:hooks, che esegue solo quella regola, a livello di errore, su tutto src, nel job di qualità da cui dipende il deploy. La correzione ha spostato una riga in un componente; la regola tiene lo stesso errore fuori da ogni altro file.
Ratchet Agentic Engineering, il metodo con cui lavora il laboratorio, riguarda soprattutto questa parte del giro: quello che succede dopo che il codice è scritto.
Dove si fermano gli strumenti di specifica
Spec Kit, di GitHub, porta una richiesta a una specifica scritta, poi a un piano tecnico e a un elenco di compiti che un agente esegue. Kiro, l’ambiente di sviluppo di AWS, tiene per ogni funzione tre file sotto .kiro/specs, con requisiti, disegno e compiti. Tutti e due lavorano sul percorso dall’intenzione al codice.
Con l’errore #310 una specifica più precisa non avrebbe cambiato niente. Il guasto stava nella posizione di una riga, ed è uscito solo in produzione, di notte. Il metodo copre la seconda metà del giro: cosa ferma una modifica prima del rilascio, chi decide il rilascio, cosa succede quando qualcosa si rompe e come si impedisce all’errore di tornare.
Le due metà si possono usare insieme. Una specifica scritta con Kiro, per esempio, può diventare l’elenco di requisiti numerati da cui il metodo parte.
Tetti che scendono soltanto
Nel metodo un cricchetto è un test con un numero dentro. Il test accessibilita.test.ts conta gli avvisi di eslint-plugin-jsx-a11y nel codice di Seantral e fallisce se superano il tetto scritto nel file, il conto del 2 ottobre 2026. Chi toglie un avviso abbassa il numero; chi ne aggiunge uno deve sistemare il codice.
Lo stesso vale per i testi. Il test credibilita.test.ts legge le pagine pubbliche del sito e gli articoli di questo diario, e fallisce su un verbo in prima persona o su un trattino lungo. Una frase che non passa si riscrive.
Un tetto scritto in un file ha un punto debole: chi può modificare il test può anche alzarlo. In Cockpit by RiftSeed, lo strumento in cui il laboratorio applica il metodo, i tetti stanno sul server, in una tabella che accetta solo righe nuove. Se una lettura della CI riporta un tetto più alto di quello registrato, il cancello diventa rosso con ceiling_raised_without_decision. Per alzare un tetto c’è una funzione sola, che chiede una persona collegata e una ragione scritta e registra la decisione. Nessuno strumento MCP la chiama.
Un test per ogni incidente
In Cockpit un guasto diventa un incidente, e la tabella degli incidenti ha un vincolo nel database: lo stato «risolto» richiede il commit della correzione e il test di guardia. Quando a chiudere è il Commander, l’agente che in Cockpit assegna i compiti, il controllo va oltre. Il commit deve avere un giro del cancello sul ramo di rilascio, e l’ultimo esito del test di guardia deve essere verde. Un incidente si può anche archiviare, ma con una ragione scritta.
Sonde sul sito pubblicato
I test girano prima del rilascio, le sonde dopo, sul sito in produzione. Sono script Playwright, nella cartella scripts/sonde, che rigiocano scenari veri da computer e da telefono e contano errori, pagine bianche e schermate di guasto. Il 21 settembre 2026 una di queste ha trovato un crash di Seantral: i cerchi dei temporali venivano montati prima che esistesse il loro livello sulla mappa, e Leaflet cadeva.
Le sonde hanno un limite dichiarato. Un bundle collegato al backend sbagliato, con la pagina che risponde, passa inosservato. Per quel caso c’è una guardia prima del build: guardia-backend-seantral.mjs ferma il build di Seantral se l’indirizzo del backend non è il suo.
Il verdetto
In questo repository il rilascio è un push su main. Il job di deploy dipende da quello di qualità, che esegue il typecheck, la suite di Vitest, i test Deno delle funzioni edge e il lint degli hook. Se uno è rosso, niente va online.
In Cockpit un rilascio aspetta il verdetto di una persona. Un agente lo può solo chiedere, con verdict.request, che restituisce la pagina dove la persona approva o respinge. Sulla pagina ci sono l’esito di ogni controllo del cancello, i requisiti che il rilascio porta, l’indirizzo dove provarlo e gli incidenti aperti. Per approvare serve un cancello verde, e finché c’è un incidente aperto il tasto per approvare non compare. Per respingere serve una nota.
Cosa ha in comune con l’harness engineering
Il 5 febbraio 2026 Mitchell Hashimoto ha descritto un’abitudine che ha chiamato «engineer the harness»: ogni volta che un agente sbaglia, si costruisce qualcosa perché quell’errore non si ripeta. Può essere una riga in AGENTS.md o uno strumento vero, come uno script che lancia solo i test che servono. Il 2 aprile, su martinfowler.com, Birgitta Böckeler ha diviso i controlli intorno a un agente in guide, che lo orientano prima che agisca, e sensori, che osservano dopo.
Il metodo parte dalla stessa abitudine, e la regola sugli hook del 7 settembre è un sensore nel senso di Böckeler. Quello che aggiunge sta fuori dall’agente. I tetti e la chiusura degli incidenti sono regole del database, e nessuno strumento del protocollo le aggira. Il giro continua dopo il merge, in produzione, con le sonde. Il rilascio lo decide una persona. E i commit portano una riga Refs: con la chiave del requisito, così un file o un test risale alla richiesta da cui è nato.
Da dove viene, e cosa manca
Alcune pratiche vengono dal software safety-critical, quello dell’aviazione e dell’automobile: requisiti numerati e confermati da chi ne risponde, la traccia da requisito a codice a test, l’analisi d’impatto prima di ogni modifica, un problema che si chiude con una prova, un’autorità di rilascio. In quei settori costano molto. Gli agenti di codice ne abbassano il costo abbastanza da applicarle a un’app sul mare.
Le garanzie formali di quei settori qui non ci sono. Nessuna verifica è indipendente da chi ha scritto il codice. La copertura strutturale non si misura; oggi si conta solo quanti requisiti sono citati da un test. I livelli di garanzia non sono ancora definiti. E chi conferma i requisiti è la stessa persona che decide il rilascio.
Scritto come nasce ogni cosa in questo lab: con l’AI, poi riletto e approvato da una persona.