Harness vs context engineering: in cosa l'harness engineering si distingue dal prompt e dal context engineering

In breve: tre livelli dello stesso compito

Il prompt engineering risponde alla domanda "come chiedere", il context engineering a "che cosa deve sapere il modello adesso", l'harness engineering a "in quale ambiente lavora l'agente e come scopre di aver sbagliato". Non sono approcci concorrenti, ma livelli annidati: un buon prompt è parte di un buon contesto, e un contesto ben progettato è uno dei componenti dell'harness.

La confusione nasce dal fatto che tutti e tre modificano il comportamento del modello, ma con leve diverse. Se l'agente non sa eseguire i test, nessuna formulazione del prompt lo risolverà. Se l'agente dimentica le decisioni del giorno prima, il problema non sono le parole della richiesta, ma il luogo in cui è conservato lo stato. Capire la differenza tra harness vs context engineering fa risparmiare settimane, perché smetti di riscrivere le istruzioni quando a essere rotto è l'ambiente.

Prompt engineering: la formulazione di una richiesta

Il prompt engineering è il lavoro sul testo della richiesta: ruolo, compito, formato della risposta, esempi (few-shot), vincoli, ordine dei passi. L'unità di lavoro è una singola chiamata al modello. Il risultato si valuta dalla risposta: è giusta, è nel formato richiesto, il modello è uscito di strada?

Tecniche tipiche:

• descrivere esplicitamente il formato di output (schema JSON, tabella, elenco);
• fornire 2–3 esempi "input → output corretto";
• chiedere di ragionare passo dopo passo prima di rispondere;
• separare istruzioni e dati con delimitatori chiari;
• elencare ciò che non si deve fare.

Il prompt engineering funziona bene per i compiti "un input, una risposta": classificazione, estrazione di dati, traduzione, generazione di testo da un modello. Il suo limite si vede quando il modello comincia ad agire: chiamare strumenti, modificare file, lavorare decine di passi di seguito. Lì la qualità non dipende più da una frase, ma dall'intero ambiente che circonda il modello.

Context engineering: cosa entra nella finestra del modello

Il context engineering è la gestione del contenuto della finestra di contesto a ogni passo. La finestra è limitata, e in una sessione lunga l'agente accumula output di comandi, contenuti di file e cronologia della conversazione. L'obiettivo è che in ogni momento ci sia ciò che serve e non ci sia ciò che non serve.

Vi rientrano:

• selezione: quali file, documenti e frammenti di codice caricare per il compito (ricerca, RAG, lettura su richiesta);
• compressione: riassunto della cronologia lunga, troncamento dell'output dei comandi, compattazione della sessione;
• struttura: il file d'ingresso delle istruzioni come un indice, e i dettagli in documenti separati che l'agente apre quando servono;
• isolamento: affidare un sottocompito a un subagent con un contesto pulito, perché il flusso principale non si sporchi.

La metrica del context engineering è questa: l'agente ha trovato la regola o il fatto giusto al momento giusto, o è affogato nel rumore? Il sintomo tipico: la regola è scritta in CLAUDE.md, ma l'agente la viola, perché il file è di cinque pagine e la regola si è persa tra il resto.

Harness engineering: tutto ciò che circonda il modello

L'harness ("imbracatura") è l'ambiente in cui lavora l'agente. Il modello è in esso un componente che entra nel ciclo una volta. Tutto il resto, cioè istruzioni, strumenti, ambiente, stato e feedback, viene progettato dall'ingegnere. L'harness engineering fa sì che l'agente non si limiti a scrivere codice, ma sia anche in grado di eseguirlo, verificarlo, riconoscere i propri errori e, nella sessione successiva, riprendere da dove si era fermato.

È utile scomporre l'harness in cinque componenti:

In questo schema il context engineering vive dentro i primi due componenti: decide come istruzioni e output degli strumenti entrano nella finestra. L'harness aggiunge ciò che non si può mettere nel contesto: una verifica funzionante, un ambiente riproducibile, un file di stato che sopravvive al riavvio.

Tabella di confronto

Perché prompt e contesto da soli non bastano

Una storia classica: il team vede che l'agente sbaglia e passa una settimana a scrivere un AGENTS.md di cinque pagine. L'agente però continua a non eseguire il linter prima del commit. La causa non è nel testo: l'agente non ha una shell con i permessi giusti, e il linter non è installato nell'immagine. Era un problema di strumenti e ambiente, che si cercava di risolvere con le istruzioni.

Seconda storia: l'agente, alla terza sessione di fila, cerca di correggere lo stesso bug, perché dopo il riavvio non ricorda che cosa ha già provato. Il context engineering all'interno della sessione non aiuta, perché la finestra viene svuotata. Serve il componente di stato: un file in cui l'agente annota tentativi e decisioni, e la regola di leggerlo prima di cominciare.

La terza storia è la più costosa: l'agente scrive "fatto", gli unit test sono verdi, ma la funzionalità non funziona. Né un prompt del tipo "controlla con attenzione", né altra documentazione nel contesto danno all'agente una verifica indipendente. La può dare solo un feedback della macchina: un test end-to-end, uno script di verifica o un valutatore separato che non vede il ragionamento di chi ha lavorato.

Conclusione generale: prompt e contesto influenzano ciò che il modello pensa. L'harness influenza ciò che il modello può fare e ciò che scopre dopo un'azione.

Perché cambiare modello non è la soluzione

La reazione più comune a un agente instabile è prendere un modello più potente. Di solito questo non risolve nulla: lo stesso modello, in un repository ben strutturato, lavora come un senior esperto, mentre in un repository senza comandi di verifica né descrizione dello stack si smarrisce. Un modello più forte non conosce le convenzioni del tuo team, non ottiene l'accesso a un database che non gli è stato concesso e non si accorge di una migrazione rotta se nessuno l'ha eseguita.

L'harness non diventa obsoleto con l'uscita di nuovi modelli. Istruzioni, ambiente riproducibile e verifiche servono a ogni modello. Cambia soltanto quanta micro-gestione manuale si può eliminare: a un modello forte bastano gli invarianti ("i dati vengono validati ai confini del dominio"), non istruzioni passo passo.

Come capire quale livello correggere

Diagnosticare dai sintomi è più veloce di qualsiasi esperimento:

Da dove cominciare con l'harness

Se costruisci da zero, l'ordine pratico è: feedback → istruzioni → stato → ambiente → strumenti. Il feedback viene prima perché senza di esso non puoi misurare l'effetto delle altre modifiche. Finché non esiste un comando che risponda onestamente "funziona o non funziona", ogni miglioramento delle istruzioni viene valutato a occhio.

Un avvio minimo somiglia a questo:

# AGENTS.md (estratto)
## Come verificare
- make check   # lint, tipi, unit test
- make e2e     # scenari end-to-end
Una funzionalità è pronta solo se entrambi i comandi terminano con codice 0.

## Regole
- MUST: tutte le query SQL sono parametrizzate
- MUST: eseguire make check prima del commit
- Dettagli sui pagamenti: docs/payments.md (leggere quando il compito riguarda i pagamenti)

Nota l'ultima riga: è il context engineering all'interno dell'harness. Il file d'ingresso è una mappa, non un manuale, e i dettagli si caricano secondo la condizione "quando".

Come misurare il contributo di ciascun componente

L'harness ha una metrica che il prompt non ha: la quota di compiti che l'agente dichiara pronti ma che la verifica indipendente non conferma. Si chiama verification gap. Prendi gli ultimi 10 compiti, annota per ciascuno se l'agente ha detto "fatto" e se la verifica è passata. Il rapporto ottenuto è la base di confronto per le modifiche successive.

Per capire quale componente produce effetto si usa l'ablation: si fissano modello e insieme di compiti, si disattiva un componente alla volta e si osserva il calo. Tieni presenti due cose. Prima dell'ablation conviene tenere un registro dei fallimenti: indica il collo di bottiglia più in fretta. E un calo nullo non dimostra che il componente sia inutile: forse i compiti scelti non lo hanno usato.

Errori frequenti

• Considerare harness il file con il prompt. Le istruzioni sono uno dei cinque componenti. Una mensola di ricette non è una cucina.
• Curare l'assenza di strumenti con il testo. "Esegui sempre i test" non serve a nulla se nell'ambiente dell'agente i test non girano.
• Gonfiare le istruzioni. Più il file è lungo, più è probabile che una regola importante non venga letta. Trasforma le regole importanti in verifiche eseguibili.
• Fidarsi dell'autovalutazione dell'agente. Un modello che valuta il proprio lavoro tende a presentarlo meglio di com'è. La verifica deve farla uno script o un agente separato con un contesto pulito.
• Configurare l'harness una volta sola. Invecchia come il codice: le regole si scostano dalla realtà e i comandi cambiano. Va revisionato regolarmente.

Conclusione

Il prompt engineering migliora la formulazione della richiesta, il context engineering seleziona le informazioni nella finestra del modello, l'harness engineering progetta l'intero ambiente dell'agente, compresi strumenti, ambiente, stato e verifiche. Quando l'agente lavora a lungo e modifica da solo il codice, l'harness diventa decisivo: trasforma "l'agente ha detto che è pronto" in "il sistema ha verificato che funziona". Per questo la scelta tra harness e context engineering non è un aut aut: il contesto è parte dell'harness, e bisogna intervenire sul livello indicato dai sintomi. Il tema è trattato in pratica in un corso che lavora su un backend di pagamento reale.