Harness engineering: come rendere affidabile un agente AI che scrive codice

Due team usano lo stesso modello, lo stesso agente di coding e lo stesso piano in abbonamento. Il primo ottiene pull request pronte da rivedere; il secondo passa la giornata a correggere errori ripetuti. La differenza raramente sta nel modello. Sta in quello che c’è attorno: istruzioni, strumenti, test, controlli automatici, memoria. Questo insieme si chiama harness, e la disciplina che lo progetta è l’harness engineering.

Il termine è nato all’inizio del 2026 ed è diventato uno dei temi più discussi dagli sviluppatori che lavorano con gli agenti. Nelle ultime settimane Cole Medin ha mostrato come far proporre all’agente le modifiche al proprio harness, Anthropic ne ha parlato nel podcast Latent Space e alla conferenza AI Engineer c’è stato un talk dal titolo provocatorio “Is the Agent Harness Dead?”.

In questa guida trovi una definizione operativa, i componenti di un harness, come costruirlo passo dopo passo su un progetto reale e come farlo migliorare con ogni errore dell’agente.

Per un’azienda che fa sviluppare software, con un team interno o con un fornitore, l’harness è la differenza tra agenti che accelerano davvero il lavoro e agenti che producono codice da rifare. Ed è anche un patrimonio: regole, controlli e procedure restano all’azienda quando cambiano le persone, gli strumenti o i modelli.

In breve

• L’harness è tutto ciò che sta attorno al modello: istruzioni, strumenti, permessi, test, hook, memoria e flusso di lavoro.
• L’harness engineering trasforma ogni errore ricorrente dell’agente in un controllo permanente: una regola, uno script, un test o un vincolo.
• Si divide in guide (che orientano l’agente prima che agisca) e sensori (che verificano il risultato e permettono di correggersi).
• I controlli deterministici (test, type checker, linter) vengono prima di quelli basati su LLM, perché sono rapidi, economici e ripetibili.
• Un buon harness è piccolo, misurato e rivisto spesso: ogni regola deve rispondere a un problema reale.
• Oggi l’agente stesso può proporre miglioramenti all’harness analizzando le sessioni passate, ma l’approvazione resta umana.
• Per chi decide: l’harness è un asset aziendale. Chiedere al team o al fornitore come è fatto, dove è conservato e come migliora è un modo concreto per valutarne la maturità nell’uso degli agenti.

Che cos’è l’harness di un agente AI

L’harness è l’infrastruttura software che circonda il modello e gli permette di lavorare su un sistema reale. Il modello ragiona e propone; l’harness decide cosa può leggere, quali strumenti può usare, come verifica il proprio lavoro e cosa ricorda tra una sessione e l’altra.

Un’immagine utile: il modello è il motore, l’harness è l’auto. Senza volante, freni e cruscotto il motore più potente non porta da nessuna parte. Senza harness, un modello non può scrivere un file in sicurezza, eseguire un test o accorgersi di aver rotto la build.

Conviene distinguere due livelli:

• Harness interno: quello che i produttori dell’agente costruiscono per noi. Il ciclo di esecuzione, gli strumenti per leggere e modificare file, la gestione del contesto, i permessi. In Claude Code, Codex, Cursor o OpenCode è già presente.
• Harness esterno: quello che costruiamo noi attorno all’agente, per il nostro progetto e il nostro team. File di istruzioni, skill, hook, script di verifica, test, regole di architettura.

Quando parliamo di harness engineering ci riferiamo soprattutto al secondo livello. È quello su cui hai il controllo e quello che fa la differenza tra un agente generico e un agente che conosce il tuo codice.

Perché l’harness interessa a chi guida un’azienda

A prima vista l’harness engineering sembra materia da sviluppatori. In realtà incide su quattro aspetti che interessano direttamente chi gestisce un’azienda o un reparto.

Qualità prevedibile

Senza un harness, la qualità del lavoro con gli agenti dipende da chi li usa e da come li usa quel giorno. Con regole, controlli e procedure condivise, il risultato diventa più uniforme tra persone, progetti e settimane. È la stessa logica delle procedure di qualità in produzione, applicata allo sviluppo.

Conoscenza che resta in azienda

Un buon harness contiene in forma scritta e verificabile ciò che di solito sta nella testa degli sviluppatori più esperti: come si avvia il progetto, quali errori evitare, quali convenzioni rispettare. Questo accelera l’inserimento di persone nuove e riduce la dipendenza da singoli individui o da un singolo fornitore.

Costi più bassi

Ogni errore ripetuto dall’agente costa due volte: il tempo della persona che lo corregge e i token consumati per rifare il lavoro. Un harness che trasforma gli errori ricorrenti in controlli automatici riduce entrambe le voci.

Indipendenza dai fornitori di modelli

Il mercato dei modelli cambia ogni mese. Un harness costruito con formati aperti (file di istruzioni standard, script, test) permette di cambiare agente o modello senza ripartire da zero. È una forma di protezione dell’investimento.

Domande per valutare un team o un fornitore

• Esiste un file di istruzioni per gli agenti nei nostri progetti? Possiamo vederlo?
• Quali controlli automatici bloccano un errore prima che arrivi in produzione?
• Cosa fate quando l’agente sbaglia due volte nello stesso modo?
• L’harness è nel nostro repository e resta nostro a fine contratto?
• Quali indicatori usate per dire che gli agenti stanno migliorando il lavoro?

Gli indicatori più utili sono semplici: quota di attività accettate senza correzioni, difetti trovati dopo il rilascio, tempo necessario a una persona nuova per diventare operativa sul progetto.

Da dove nasce il termine

La paternità viene attribuita a Mitchell Hashimoto, cofondatore di HashiCorp e autore del terminale Ghostty. Nel suo post My AI Adoption Journey descrive sei fasi del suo percorso con gli agenti. La quinta è proprio “costruire l’harness”: ogni volta che l’agente sbaglia, invece di correggere a mano e andare avanti, si crea qualcosa che impedisca lo stesso errore in futuro.

Hashimoto indica due strumenti principali. Il primo è il file AGENTS.md: ogni riga risponde a un comportamento sbagliato osservato, come un comando errato o un’API obsoleta. Il secondo sono script e strumenti dedicati, per esempio uno script che fa uno screenshot dell’interfaccia o che esegue solo i test pertinenti, segnalati all’agente con una nota nello stesso file.

Pochi giorni dopo OpenAI ha pubblicato Harness engineering: leveraging Codex in an agent-first world, il resoconto di un esperimento interno di cinque mesi in cui un piccolo team ha costruito un prodotto senza scrivere a mano nessuna riga di codice. Documentazione leggibile dalla macchina, telemetria e test strutturali hanno guidato l’agente. La sintesi del post: le persone guidano, gli agenti eseguono.

Ad aprile Birgitta Böckeler di Thoughtworks ha dato al concetto una struttura più rigorosa in un articolo su martinfowler.com, che useremo come base per la classificazione dei componenti.

Prompt, context e harness engineering: le differenze

Le tre discipline si sovrappongono, ma rispondono a domande diverse.

Disciplina	Domanda centrale	Strumenti tipici	Orizzonte
Prompt engineering	Come formulo la richiesta?	Istruzioni, esempi, formato dell’output	Singola richiesta
Context engineering	Quali informazioni arrivano al modello, e quando?	Recupero di documenti, memoria, compattazione, caricamento progressivo	Singola sessione
Harness engineering	Come lavora l’agente sul sistema reale, e come migliora nel tempo?	Regole, strumenti, permessi, test, hook, CI, flusso di lavoro	Tutto il progetto, per mesi

Qualcuno sostiene che l’harness engineering sia solo un nuovo nome per il context engineering. In parte è vero: molti componenti dell’harness arrivano al modello sotto forma di contesto. La differenza sta nell’orizzonte temporale e nel metodo. L’harness è un sistema che evolve con il progetto e che include controlli deterministici che non passano affatto dal modello.

I componenti di un harness: guide e sensori

La classificazione più utile divide i componenti in due famiglie.

• Guide (controllo in avanti): orientano l’agente prima che agisca. File di istruzioni, convenzioni, skill, esempi, template di progetto.
• Sensori (controllo a posteriori): osservano il risultato dopo l’azione e restituiscono un segnale su cui l’agente può correggersi. Test, linter, type checker, build, analisi statica, revisione automatica.

Ogni componente può poi essere computazionale (deterministico, veloce, economico) o inferenziale (basato su un modello, più flessibile ma più lento, costoso e meno prevedibile).

	Computazionale	Inferenziale
Guide	Template di progetto, generatori di codice, schemi tipizzati	AGENTS.md o CLAUDE.md, skill, documentazione di architettura
Sensori	Test, type checker, linter, regole sulle dipendenze, build	Revisione del codice con un LLM, LLM-as-judge, controlli semantici

La regola pratica: se un controllo può essere computazionale, rendilo computazionale. Una regola scritta in AGENTS.md (“non importare il modulo X dal modulo Y”) viene seguita quasi sempre. Una regola di architettura verificata da uno strumento come dependency-cruiser o un test strutturale viene seguita sempre, e l’agente riceve un errore preciso quando la viola.

Le guide: istruzioni, skill e convenzioni

Il file di istruzioni del progetto

Quasi tutti gli agenti leggono all’avvio un file di istruzioni: AGENTS.md è il formato aperto adottato da molti strumenti, mentre Claude Code usa CLAUDE.md, descritto nella documentazione sulla memoria. Il contenuto ideale è breve e specifico: come si avvia il progetto, come si eseguono i test, quali comandi evitare, quali convenzioni non sono ovvie dal codice.

# AGENTS.md

## Comandi
- Avvio locale: `pnpm dev` (porta 3000). Non usare `npm`.
- Test di un solo file: `pnpm vitest run percorso/del/file.test.ts`
- Prima di dichiarare un task finito: `pnpm check` (lint + tipi + test)

## Convenzioni
- Le date arrivano dall'API in UTC: convertirle solo nei componenti UI.
- Nessuna chiamata diretta al database dai componenti: passare da `src/server/`.
- Testi visibili all'utente in italiano, chiavi di traduzione in `locales/it.json`.

## Errori già visti
- Non rigenerare `pnpm-lock.yaml` a mano.
- Le migrazioni si creano con `pnpm db:migration nome`, mai scritte da zero.

La sezione “Errori già visti” è il cuore dell’approccio di Hashimoto. Ogni riga ha una storia: un errore che l’agente ha commesso almeno due volte.

Skill per i compiti ricorrenti

Le skill sono istruzioni modulari che l’agente carica solo quando servono: come si crea un nuovo endpoint, come si scrive una migrazione, come si prepara una release. In Claude Code sono file markdown descritti nella documentazione sulle skill. Il vantaggio rispetto a un file di istruzioni sempre più lungo è che non consumano contesto finché non vengono usate. Ne parleremo in dettaglio in un articolo dedicato.

Template e generatori

Se ogni nuovo modulo deve avere la stessa struttura, un generatore (anche un semplice script) è una guida computazionale. L’agente lo esegue e parte da una base corretta, invece di ricostruirla ogni volta con piccole variazioni.

I sensori: test, controlli e hook

Una guida riduce la probabilità di errore. Un sensore rende l’errore visibile. Senza sensori, l’agente dichiara il lavoro finito perché “sembra giusto”.

Test eseguibili dall’agente

Il primo sensore è una suite di test che l’agente può lanciare in pochi secondi. Se i test sono lenti o richiedono configurazioni manuali, l’agente li salterà o li lancerà raramente. Investire in test veloci è investire nell’harness.

Verifica end-to-end

Anthropic, nel post Effective harnesses for long-running agents, racconta che gli agenti tendevano a segnare come completate funzionalità verificate solo con test unitari o chiamate curl. Chiedere di testare l’applicazione attraverso l’automazione del browser, come farebbe un utente, ha migliorato sensibilmente i risultati.

Hook nel ciclo dell’agente

Gli hook sono comandi che l’agente esegue automaticamente in momenti precisi: prima di usare uno strumento, dopo aver modificato un file, alla fine di una sessione. In Claude Code si configurano in settings.json, come spiegato nella documentazione sugli hook.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": "pnpm exec eslint --fix \"$CLAUDE_PROJECT_DIR\"/src --quiet" }
        ]
      }
    ]
  }
}

Attenzione però a non esagerare. Matt Pocock ha messo in guardia, nel video “STOP running your checks in harness hooks”, contro i controlli pesanti a ogni modifica di file: rallentano l’agente e riempiono il contesto di rumore. La sua indicazione è lasciare agli hook i controlli istantanei e spostare quelli lenti nel pre-commit o nella CI. È un tema che riprenderemo in un articolo dedicato ai controlli di qualità.

Vincoli di architettura

Regole sulle dipendenze tra moduli, limiti di dimensione dei file, divieto di certe librerie: sono “fitness function” che proteggono la struttura del progetto. Per un agente sono preziose perché trasformano un principio vago (“mantieni separati i livelli”) in un errore concreto con nome del file e riga.

Come costruire un harness passo dopo passo

Non serve progettare tutto in anticipo. Anzi, un harness progettato a tavolino tende a riempirsi di regole inutili. Questo è il percorso che seguiamo nei progetti dei clienti.

Passo 1: rendi il progetto avviabile e verificabile

Un comando per installare, uno per avviare, uno per controllare tutto (lint, tipi, test). Se una persona nuova del team impiega mezza giornata ad avviare il progetto, l’agente sprecherà token per fare lo stesso. Anthropic suggerisce uno script di inizializzazione proprio per questo motivo.

Passo 2: scrivi un file di istruzioni minimo

Comandi, tre o quattro convenzioni non ovvie, nient’altro. Resisti alla tentazione di incollare la documentazione completa.

Passo 3: lavora e annota gli errori

Per una o due settimane usa l’agente su compiti reali. Ogni volta che correggi qualcosa, annota il tipo di errore. Dopo pochi giorni vedrai emergere i pattern: sono sempre gli stessi cinque o sei.

Passo 4: trasforma ogni errore ricorrente in un controllo

Per ogni pattern chiediti quale sia il controllo più forte possibile. Un test? Una regola del linter? Un vincolo di architettura? Uno script? Solo se nessuna di queste opzioni è praticabile, aggiungi una riga al file di istruzioni.

Passo 5: dai all’agente un modo per verificare

Per ogni tipo di compito, l’agente deve sapere come dimostrare di averlo completato: quale comando lanciare, quale pagina aprire, quale output aspettarsi. “Il task è finito quando pnpm check passa e la pagina /ordini mostra il nuovo filtro” è un criterio che l’agente può rispettare.

Passo 6: rivedi e pota

Ogni mese rileggi il file di istruzioni e le skill. Le regole che non servono più vanno tolte: consumano contesto e diluiscono quelle importanti.

Far migliorare l’harness all’agente stesso

La novità delle ultime settimane è che l’agente può partecipare attivamente al miglioramento del proprio harness. Ci sono tre approcci, in ordine di complessità.

Analizzare le sessioni passate

Gli agenti di coding salvano localmente la cronologia delle conversazioni: prompt, chiamate agli strumenti, errori. Cole Medin, nel video The Biggest AI Coding Agent Upgrade Is Already on Your Machine, mostra come chiedere all’agente di analizzare queste sessioni e proporre le modifiche più utili a regole, hook e skill. La versione avanzata carica tutto in un database interrogabile.

Retrospettive strutturate

Matt Pocock ha rilasciato una skill /retro che conduce una retrospettiva sugli errori della sessione e propone controlli automatici o guardrail da aggiungere al codice. La presenta nel video /retro is a banger of a skill. Il punto chiave: la retrospettiva produce proposte concrete, non riflessioni generiche.

Miglioramento continuo in produzione

Per gli agenti che girano in produzione (non solo di coding), Cole Medin mostra in Let Your AI Agent Do ITS OWN Harness Engineering un ciclo in cui l’agente impara dalle conversazioni reali e propone modifiche alle proprie regole, skill e memoria. Ogni proposta passa da un’approvazione umana prima di entrare in vigore.

In tutti e tre i casi vale la stessa regola: l’agente propone, una persona approva. Un harness che si modifica da solo senza revisione accumula regole contraddittorie e rischia di imparare scorciatoie sbagliate.

L’harness è destinato a sparire?

Alla conferenza AI Engineer di New York il talk Is the Agent Harness Dead? ha posto la domanda apertamente: con modelli sempre più capaci, serve ancora tutto questo lavoro?

La risposta più equilibrata arriva dalla stessa Anthropic. Nel post sulle managed agents osserva che l’harness codifica ipotesi su ciò che il modello non sa fare da solo, e che queste ipotesi vanno messe in discussione spesso perché invecchiano con i nuovi modelli. Una parte dell’harness interno diventerà superflua. Thariq Shihipar di Anthropic, nell’episodio di Latent Space Claude Code’s Bitter Lesson, descrive un futuro in cui gli agenti riscrivono parte del proprio harness.

Il nostro punto di vista: le guide generiche (“scrivi codice pulito”, “pensa passo dopo passo”) perdono valore a ogni nuovo modello. Le guide specifiche del progetto e i sensori deterministici no. Un modello più intelligente non può sapere che nel tuo gestionale le date arrivano in UTC, né può indovinare un test che non esiste. Quella parte dell’harness resta, ed è quella su cui conviene investire.

Errori comuni

Il file di istruzioni infinito

Trecento righe di regole, molte contraddittorie, la metà non più valide. L’agente le legge tutte a ogni sessione e ne segue meno di quanto pensi. Meglio cinquanta righe precise e il resto in skill caricate al bisogno.

Regole al posto di controlli

“Esegui sempre i test prima di finire” scritto in un file è una speranza. Un hook di fine sessione o un controllo in CI che blocca il merge è una garanzia.

Controlli lenti nel posto sbagliato

Una suite end-to-end da otto minuti lanciata a ogni modifica di file rende l’agente inutilizzabile. Ogni controllo ha il suo momento: istantaneo negli hook, medio nel pre-commit, completo in CI.

Nessuna misura

Senza sapere quante sessioni finiscono con un risultato accettato, quante richiedono correzioni e su cosa, è impossibile capire se una modifica all’harness ha migliorato le cose. Bastano poche metriche semplici, ma vanno raccolte.

Harness personale non condiviso

Uno sviluppatore costruisce un ottimo setup sul proprio computer, il resto del team no. L’harness va versionato nel repository, insieme al codice, e rivisto con le stesse regole.

Portarlo in produzione nel team

Quando l’harness passa da esperimento personale a strumento di squadra, servono alcune scelte esplicite.

• Proprietà: chi approva le modifiche a regole, skill e hook? Trattale come codice, con revisione obbligatoria.
• Permessi: definisci quali comandi l’agente può eseguire senza conferma e quali richiedono approvazione. Mai credenziali di produzione nell’ambiente dell’agente.
• Costi: un harness con molte verifiche inferenziali (revisioni con LLM, giudici automatici) consuma token. Misura il costo per task completato, non per singola chiamata.
• Portabilità: preferisci formati aperti (AGENTS.md, script shell, test standard) così da poter cambiare agente senza riscrivere tutto.
• Onboarding: un buon harness è anche documentazione per le persone. Chi entra nel team impara le convenzioni leggendo lo stesso file che legge l’agente.

Stai introducendo gli agenti di coding nel tuo team o nella tua agenzia? Come partner tecnico aiutiamo a impostare harness, convenzioni e controlli su progetti reali, e con la formazione aziendale trasferiamo il metodo al team.

Da dove partire questa settimana

1. Crea un comando unico che esegue lint, tipi e test, e verifica che giri in meno di due minuti.
2. Scrivi un AGENTS.md o CLAUDE.md di massimo quaranta righe: comandi, convenzioni non ovvie, errori già visti.
3. Per cinque giorni annota ogni correzione che fai al lavoro dell’agente.
4. Scegli i due errori più frequenti e trasformali in controlli automatici: un test, una regola del linter o un hook.
5. A fine mese chiedi all’agente di analizzare le sessioni passate e proporre modifiche; approva solo quelle che rispondono a un problema reale.

Se usi già decisioni veloci nel ciclo dell’agente, per esempio per bloccare comandi rischiosi, puoi integrare un modello decisionale come Jev tra i sensori dell’harness.

Checklist di un harness sano

• Il progetto si installa, si avvia e si verifica con tre comandi documentati.
• Il file di istruzioni è breve e ogni regola risponde a un errore osservato.
• Le procedure ricorrenti sono skill caricate solo quando servono.
• Esiste una suite di test veloce che l’agente può lanciare da solo.
• Le regole di architettura sono verificate da strumenti, non solo descritte.
• Gli hook eseguono solo controlli rapidi; quelli lenti stanno in pre-commit e CI.
• Ogni tipo di task ha un criterio di completamento verificabile.
• L’harness è versionato nel repository e le modifiche passano da revisione.
• Permessi e credenziali dell’agente sono limitati al necessario.
• Una volta al mese regole e skill vengono riviste e potate.

Domande frequenti

Fonti e approfondimenti

• Mitchell Hashimoto: My AI Adoption Journey
• OpenAI: Harness engineering, leveraging Codex in an agent-first world
• Birgitta Böckeler su martinfowler.com: Harness engineering
• Anthropic: Effective harnesses for long-running agents
• Documentazione Claude Code: hook
• AGENTS.md: formato aperto per istruzioni agli agenti

Vuoi agenti di coding che sbagliano meno e si verificano da soli? Parliamo del tuo progetto: partiamo dal tuo repository e dagli errori che vedi ogni giorno.