Parte 2 — Costruire i binari
La seconda parte del libro nasce direttamente sul campo. Ho passato diverse settimane a studiare e testare gli agenti e i framework agentici per comprenderne appieno portata, utilità e limiti, traendone una conclusione pratica: per governare i progetti software affiancati da un agente, è indispensabile disporre di un harness. Non l’ennesima procedura da memorizzare in prompt «copia-incollati», ma un metodo solido, ordinato e il più possibile deterministico per condurre il ciclo di sviluppo del software durante la collaborazione con l’IA.
La ragione è semplice: ogni progetto software non può essere una strada da riscoprire ogni volta, tra convenzioni eterogenee, gestione difforme dei branch e definizioni arbitrarie di «finito» o «completato». Se c’è una cosa che ho imparato in questi anni è che nessuno sviluppo regge se condotto a mano libera, né può essere formalizzato senza un modello sottostante che lo guidi. Dotare un agente di un harness significa posare dei binari, tracciare una direzione, buona o cattiva che sia, che permetta di procedere spediti verso la destinazione senza doversi occupare di ogni singolo ostacolo lungo il percorso, mantenendo l’attenzione dove conta davvero: sull’obiettivo.
Un esempio banale rende bene l’idea. Se chiedo a un agente di creare una scheda con un cap di 200 caratteri, probabilmente lo farà correttamente nella maggior parte dei casi, diciamo 90 su 100. Ma se quel limite è una regola del sistema, non posso accontentarmi del «probabilmente». Senza un harness che verifichi il risultato e blocchi il passaggio quando il tetto viene superato, non avrò mai la certezza che la regola sia stata rispettata.
Ma attenzione: i binari non decidono la direzione. Quella resta una prerogativa del Senior: svincoli, passaggi e fermate.
La Parte 1 ha mantenuto la tecnologia sullo sfondo, favorendo prosa e astrazione, per descrivere un modello operativo piuttosto che gli strumenti con i quali metterlo all’opera. Da qui in avanti, però, chiameremo le cose con il loro nome: i testi letti dall’agente, i comandi che esegue, la logica scatenata da ciascun evento. Anche le entità terranno il nome che hanno nell’harness, senza traduzione: task, bug, backlog. Una parola, invece, cambia oggetto. Nella Parte 1 il ciclo era quello in cui il framework agentico fa girare il modello con i suoi strumenti; da qui in avanti, quando dico ciclo, intendo il ciclo di sviluppo: il percorso di una modifica al software da quando la si decide a quando la si chiude, tracciato in una scheda accanto al codice.
L’Introduzione poneva un interrogativo centrale: in che modo il System Harness può delimitare il raggio d’azione dell’agente e preservare le decisioni prese? I capitoli seguenti rispondono a questa domanda analizzando un componente alla volta, nell’ordine logico con cui sono stati affrontati. Ecco la rassegna dei contenuti:
L’architettura delinea l’harness nella sua interezza prima di entrarne nei dettagli: un eseguibile invocato da Claude Code a ogni evento, una configurazione che guida, la struttura della memoria su tre livelli e la proprietà dei singoli file.
Il caso illustra perché un Senior necessiti di un harness: con più progetti gestiti in parallelo, il contesto da ripristinare a ogni rientro è anzitutto il proprio, ancora prima che quello dell’agente.
Il ciclo dà un modello al ciclo di sviluppo con basic, il più semplice dei tre metodi dell’harness: tre entità (task, bug, backlog), i loro stati e le loro relazioni, e la scheda che le conserva accanto al codice. Gli altri metodi usano la stessa grammatica, e da basic si ricava come funzionano.
Il lavoro traccia un task dall’apertura alla chiusura: il piano condiviso, gli step esecutivi, l’oracolo, la revisione incrociata tra agenti, la distillazione delle regole e il riallineamento dell’architettura.
Le guide mostrano con quale forza l’agente viene tenuto sui binari: le forze prescrittive e coercitive, i punti di estensione del runtime, gli hook e il posto in cui mettere una regola perché venga seguita.
Il linguaggio spiega come l’agente impara a usare i verbi dell’harness nella lingua del progetto: le skill generate dalla configurazione e i subagenti che entrano nelle fasi del lavoro, ciascuno in una finestra propria.
La memoria ripristina il contesto sia per il Senior sia per l’agente: cosa includere nella sessione, in quali dosi e con quali modalità richiamare le decisioni pregresse.
La telemetria mostra come si vede l’harness al lavoro: il registro degli eventi, il log diagnostico e il transcript della sessione, letti per capire dove il testo non insegna e dove il disegno va corretto.
La prova conclude con l’oracolo, il rilascio e la prova dell’harness stesso: come verificare la tenuta dei binari, e il bilancio dell’esperimento.
Ogni capitolo si chiude con alcune pillole pratiche: indicazioni rapide e intuitive su come procedere per ottenere un determinato risultato, con quale grado di vincolo e a quale livello d’azione. Rappresentano la porzione riutilizzabile dell’opera, integrabile nel proprio ambiente a prescindere dall’adozione del framework descritto dal libro.
Una breve avvertenza prima di iniziare. L’harness si chiama SAF, come già anticipato nella Nota dell’autore, e si tratta di un progetto reale, utilizzato quotidianamente nella mia operatività.
Nei prossimi capitoli lo analizzeremo in una veste molto semplificata e descrittiva, affiancata da codice, configurazioni ed esempi di file generati; del resto, promettere una parte tecnica priva di riscontri pratici sarebbe ingiusto e poco utile. Gli estratti di codice sono accurati e i nomi dei file riflettono quelli adottati, ma questo volume non costituisce la guida utente di SAF: non troverai istruzioni di installazione né repository da scaricare.
Ti dico anche il perché: non ce n’è bisogno. L’architettura che vado a descrivere nelle prossime pagine può essere riprodotta da qualunque sviluppatore, adottando stack e finalità differenti: il modello che racconto conserva la sua validità indipendentemente dalla sua implementazione.
Iniziamo, dai.