Cos'è l'harness engineering: come rendere un agente AI uno strumento di lavoro reale

L'harness engineering in parole semplici

L'harness engineering è la disciplina ingegneristica che spiega come costruire attorno a un modello linguistico un ambiente in cui esso svolge in modo affidabile il lavoro reale. La parola harness significa "imbracatura". Il modello è potente, ma da solo non sa dove andare, quale strumento usare né quando fermarsi. L'harness indirizza quella forza.

La formulazione più breve è questa:

Agente = Modello + Harness

Il modello è l'insieme dei pesi che sanno ragionare e scrivere testo o codice. L'harness è tutto il resto: le istruzioni di sistema e i file come CLAUDE.md o AGENTS.md, il set di strumenti (shell, modifica dei file, server MCP), la sandbox in cui l'agente esegue i comandi, i file che conservano lo stato tra le sessioni e i test, i linter e gli hook che segnalano all'agente gli errori. Se si toglie l'harness, resta una chat che sa solo rispondere con testo.

Perché l'agente sembra a volte "senior" e a volte "junior"

È una situazione familiare: in un repository l'agente lavora come uno sviluppatore esperto, in un altro si perde, dimentica le decisioni del giorno prima e dichiara "pronta" una funzionalità che non funziona. La prima reazione è passare a un modello più recente. Di solito non serve, perché in entrambi i casi il modello è lo stesso. La differenza sta nell'ambiente.

Qui inizia il cambio di mentalità con cui parte l'harness engineering: l'agente non è rotto, è rotto ciò che lo circonda. Un agente non può eseguire i test se non vi ha accesso. Non ricorda ciò che ha già provato se non è scritto da nessuna parte. Non si accorge che una funzionalità è rotta se nessun controllo glielo segnala. Non sono "caratteri" del modello, ma difetti di progettazione, e si possono correggere in modo sistematico.

Sintomi tipici di un harness scadente

• Ogni nuova sessione inizia riparando l'ambiente: dipendenze sbagliate, database che non parte, variabili mancanti.
• L'agente ripete soluzioni già scartate, perché non ricorda la sessione precedente.
• La regola è scritta nelle istruzioni, ma l'agente la ignora.
• "I test sono verdi", ma la funzionalità è rotta, perché i test controllavano un'altra cosa.
• L'agente inizia tre attività contemporaneamente e non ne porta a termine nessuna.

L'harness è composto da cinque componenti

Un errore comune è considerare l'harness un solo file con un prompt. In realtà sono cinque meccanismi, e ciascuno si rompe a modo suo.

Istruzioni

Le istruzioni rispondono alla domanda: l'agente troverà la regola giusta? Un buon file d'ingresso è una mappa, non un manuale: un breve indice, i comandi di verifica e i vincoli rigidi, mentre i dettagli stanno in documenti separati che l'agente apre quando serve. Le buone istruzioni fissano invarianti ("tutte le query SQL sono parametrizzate") senza dettare riga per riga l'implementazione.

Strumenti

L'agente può verificare solo ciò a cui ha accesso. Se non riesce a eseguire il linter, la regola "esegui il linter prima del commit" non funziona. Gli strumenti si collegano attraverso le capacità integrate dell'agente (leggere e scrivere file, eseguire comandi) e attraverso MCP, il protocollo che dà all'agente accesso a database, browser e sistemi di tracciamento dei task.

Ambiente

L'ambiente è il luogo in cui l'agente esegue i comandi. Deve avviarsi con un solo comando, essere uguale da una sessione all'altra e limitare i danni di un errore: una sandbox senza accesso alla produzione, un branch o una copia di lavoro separata, e la possibilità di riportare tutto allo stato iniziale in un minuto.

Stato

Il modello non ha memoria tra le sessioni: tutto ciò che non è scritto nel repository svanisce insieme alla finestra di contesto. Per questo obiettivo, lavoro completato, decisioni prese, vicoli ciechi e prossimo passo devono vivere nei file. La verifica è semplice: apri una nuova sessione, di' all'agente "continua" e osserva se inizia a lavorare o se comincia a chiedere che cosa fare.

Feedback

I cicli di feedback sono il componente più importante. Senza di essi l'agente è il proprio unico giudice e considera onestamente il compito concluso. Test, controllo dei tipi, linter, un hook che si esegue dopo ogni modifica, uno scenario E2E nel browser: tutti questi strumenti restituiscono all'agente un segnale rosso quando l'errore è ancora economico da correggere.

L'harness è un ciclo, non un elenco

I cinque componenti funzionano come un ciclo chiuso. Il modello riceve le istruzioni, agisce con gli strumenti nell'ambiente, apporta modifiche al repository e la verifica ne controlla il risultato. Il rosso torna al modello per la correzione, il verde viene registrato nello stato. Lo stato aggiorna a sua volta le istruzioni per la sessione successiva.

istruzioni → modello → strumenti → ambiente → modifiche
                ↑                              ↓
                └──── rosso ── verifica ───────┘
                                     ↓ verde
                                 stato → (sessione successiva)

Basta eliminare una freccia e il ciclo si interrompe proprio in quel punto. Senza verifica l'agente non si accorge dell'errore. Senza stato la sessione successiva comincia con un lavoro di archeologia invece che con il lavoro vero. Per questo investire in un componente non compensa una falla in un altro: un AGENTS.md di cinque pagine non sostituisce i test mancanti.

In cosa l'harness engineering si distingue dal prompt e dal context engineering

Questi concetti sono annidati l'uno nell'altro, non in competizione.

Il prompt engineering è una parte del componente istruzioni. Il context engineering abbraccia istruzioni e stato: ciò che l'agente vede in ogni momento. L'harness engineering aggiunge ciò che non entra affatto nella finestra di contesto: accessi, sandbox, test, hook, processo di lavoro. Un prompt ben scritto non serve a nulla se l'agente non può eseguire i test.

La matematica dei compiti lunghi: perché serve l'harness

Intuitivamente, un modello che fa il 95% dei passi in modo corretto sembra quasi perfetto. Ma il compito di un agente è fatto di molti passi, e gli errori si accumulano. Se i passi sono indipendenti, la probabilità di attraversarli tutti senza errori è il prodotto delle probabilità:

0.95 ^ 10 ≈ 0.60
0.95 ^ 20 ≈ 0.36
0.95 ^ 50 ≈ 0.08

Al decimo passo senza nessun errore arriva solo circa il 60% delle esecuzioni, al cinquantesimo meno di una su dieci. Portare il modello al 97% è costoso e non dipende da voi. Ma individuare l'errore nello stesso passo in cui si è verificato e restituirlo all'agente è compito dell'harness. Il ciclo di feedback trasforma la catena "un errore trascina il successivo" in una catena di passi brevi e correggibili.

Esempio: lo stesso agente, due repository

Compito: aggiungere a un backend di pagamento in FastAPI uno sconto con codice promozionale.

Senza harness

L'agente legge un paio di file, scrive la funzione di calcolo dello sconto e uno unit test che controlla solo quella funzione in isolamento. Il test è verde e l'agente scrive "fatto". Non sapeva che il calcolo del totale avveniva in un altro modulo e non è riuscito a far partire il database per eseguire l'intero flusso dell'ordine. Un giorno dopo si scopre che nel carrello lo sconto non viene mai applicato.

Con harness

Nella radice c'è un AGENTS.md di qualche decina di righe: come avviare l'ambiente, quali comandi di verifica sono obbligatori, dove è descritta l'architettura dei pagamenti. L'ambiente si avvia con docker compose up -d. Nel repository c'è un file di piano con il criterio di completamento: "lo scenario E2E dell'ordine con codice promozionale passa". Dopo ogni modifica un hook esegue linter e controllo dei tipi, e prima di concludere l'agente deve eseguire il test E2E.

# AGENTS.md (estratto)
## Verifica — obbligatoria prima di dire "fatto"
make lint        # ruff + mypy
make test        # pytest, unit e integrazione
make e2e         # scenario dell'ordine

## MUST
- Gli importi si calcolano in centesimi (int), mai in float
- Tutte le query SQL sono parametrizzate
- Non modificare le migrazioni già applicate in produzione

Il modello è lo stesso. Ma ora l'agente trova il modulo del totale tramite la mappa del progetto, il test E2E fallisce al primo tentativo, l'agente vede che lo sconto non arriva al carrello, lo corregge e riferisce solo dopo un'esecuzione verde. La differenza nel risultato è interamente merito dell'harness.

Da dove cominciare

1. Descrivi come l'agente verifica il proprio lavoro: uno o tre comandi che è obbligato a eseguire. Il feedback produce l'effetto più grande, quindi parti da qui.
2. Rendi l'ambiente riproducibile: si avvia con un solo comando e ha un modo rapido per tornare indietro.
3. Crea un file di stato: obiettivo, lavoro svolto, decisioni e vicoli ciechi, prossimo passo.
4. Riduci le istruzioni a una mappa: comandi di verifica, vincoli rigidi, link ai documenti dettagliati.
5. Tieni un registro dei fallimenti dell'agente: a ogni errore annota quale componente l'ha reso possibile. Il registro mostrerà che cosa correggere dopo.

Un esercizio utile: valuta ciascuno dei cinque componenti su una scala da 1 a 5, dedica mezz'ora al più debole, poi esegui lo stesso piccolo insieme di compiti tipici prima e dopo. Così i miglioramenti dell'harness diventano misurabili, non "a sensazione".

Conclusione

L'harness engineering non riguarda il modello, ma tutto ciò che lo circonda: istruzioni, strumenti, ambiente, stato e cicli di feedback. L'affidabilità dell'agente è determinata dall'anello più debole di questo ciclo, quindi cambiare modello raramente risolve l'instabilità, mentre aggiungere un test o un file di piano spesso la risolve. I cinque componenti e l'assemblaggio completo dell'harness sono trattati in pratica in un corso che lavora su un vero progetto di backend di pagamento.