# osmani-agent-harness-engineering-2026-04-19

## Veille

Sintesi di Addy Osmani (Google, Chrome/Cloud) sul campo emergente dell'*harness engineering*: l'equazione `agent = model + harness`, il principio del *ratchet* ("ogni errore diventa una regola"), la rilettura "skill issue" di HumanLayer, le evidenze di Terminal Bench (Top 30 → Top 5 dal solo cambio di harness), l'architettura a livelli di Claude Code, la visione di Anthropic "gli harness non si riducono, si spostano", e l'Harness-as-a-Service (Claude Agent SDK, Codex SDK, OpenAI Agents SDK). Articolo cardine che consolida in una dottrina Trivedy, HumanLayer, Anthropic e Böckeler.

## Titre Article

Agent Harness Engineering

## Date

2026-04-19

## URL

https://addyosmani.com/blog/agent-harness-engineering/

## Keywords

harness engineering, agent harness, Addy Osmani, Viv Trivedy, HumanLayer, Dex Horthy, Anthropic engineering, Birgitta Böckeler, agent = model + harness, principio del ratchet, rilettura skill issue, Terminal Bench, architettura di Claude Code, Fareed Khan, Ralph Loop, separazione planner evaluator, AGENTS.md, ciclo di vita degli hook, sandbox, context rot, compaction, tool offloading, progressive disclosure, full context reset, ciclo di addestramento model-harness, Harness-as-a-Service, Claude Agent SDK, Codex SDK, OpenAI Agents SDK, assemblaggio just-in-time dei tool

## Authors

Addy Osmani (Software Engineer at Google, Cloud + Gemini)

## Ton

**Profilo**: Un articolo di sintesi firmato da un ingegnere software riconosciuto (Addy Osmani, Google, ex-Chrome) sul suo blog personale. Registro tech-editoriale ad alta densità concettuale, narrazione in prima persona ("I've watched this play out", "in my own workflows"). Pubblico target: ingegneri senior e tech lead che costruiscono o gestiscono agenti di coding in produzione, lettori di Trivedy/HumanLayer/Böckeler in cerca di un testo di consolidamento. Autorevolezza costruita sulla posizione in Google e sulla pratica personale dichiarata apertamente.

**Stile**: Articolo lungo strutturato in otto sezioni (equazione cardine → "skill issue" → ratchet → 7 primitive dell'harness → architettura di produzione → spostamento dell'harness → ciclo di addestramento → HaaS → domande aperte). Frasi nette, metafore precise (*"teaching someone to use a single kitchen gadget vs handing them a kitchen"* per bash, *"pilot's checklist, not style guide"* per AGENTS.md, *"GANs for prose"* per la separazione planner/evaluator). Citazione esplicita e attribuita di ogni fonte (Trivedy, Horthy/HumanLayer, Anthropic, Böckeler, Willison, Khan). Tono fermo, programmatico, senza hype. La forza del documento sta nella sua **funzione aggregativa**: Osmani non propone un nuovo framework, raccoglie in dottrina ciò che i pionieri avevano pubblicato separatamente. È il testo che fa passare l'harness engineering da disciplina emergente a consenso condiviso. Le cifre cardine circolano ("Top 30 → Top 5", "massimo 60 righe in AGENTS.md") e la frase di Anthropic *"gli harness non si riducono, si spostano"* diventa l'aforisma che struttura il dibattito del 2026.

## Pense-betes

- **Data e autore**: 19 aprile 2026, Addy Osmani (Google, Cloud + Gemini, ex-Chrome).
- **Equazione cardine** (attribuita a Viv Trivedy): ***"Agent = Model + Harness. If you're not the model, you're the harness."*** Riformulazione di Osmani: *"a decent model with a great harness beats a great model with a bad harness"*.
- Crediti espliciti:
- **Viv Trivedy**: ha coniato il termine *harness engineering*; il post "Anatomy of an Agent Harness" è la derivazione più chiara.
- **Dex Horthy / HumanLayer**: inquadramento "skill issue" — la maggior parte dei fallimenti degli agenti sono problemi di configurazione, non di pesi del modello.
- **Anthropic Engineering**: la migliore analisi pubblica sulla progettazione di harness a lunga durata.
- **Birgitta Böckeler**: una buona prospettiva lato utente.
- **Principio del ratchet**: *"Every line in a good AGENTS.md should be traceable back to a specific thing that went wrong."* Un vincolo viene aggiunto solo dopo un fallimento reale. Viene rimosso solo quando un modello più capace lo ha reso superfluo.
- **Rilettura skill issue (HumanLayer)**: *"It's not a model problem. It's a configuration problem."* Il default "aspetta la prossima versione" viene esplicitamente respinto.
- **Dati Terminal Bench** (citati da Trivedy/HumanLayer): su Terminal Bench 2.0, **Claude Opus 4.6 all'interno di Claude Code ottiene un punteggio nettamente inferiore rispetto allo stesso modello all'interno di un harness personalizzato**. Il team di Trivedy ha portato un agente di coding da **Top 30 a Top 5 cambiando solo l'harness**. Prova empirica massiccia.
- Il pattern *"working backwards from behaviour"*: *"behaviour we want (or want to fix) → harness design to help the model achieve this"*. Se non si riesce a nominare il comportamento che un componente produce, quel componente non dovrebbe esserci.
- **7 primitive dell'harness**: 1. **Filesystem e Git**: stato durevole, spazio di lavoro condiviso uomo/agente, versionamento gratuito. 2. **Bash ed esecuzione di codice**: *"the difference between teaching someone to use a single kitchen gadget and handing them a kitchen."* Citato Willison. 3. **Sandbox**: isolamento, buoni default (runtime preinstallati, browser headless per la verifica). 4. **Memoria e ricerca**: AGENTS.md ricaricato a ogni turno + MCP/Context7 per colmare il cutoff. 5. **Lotta contro il context rot**: 3 tecniche — *compaction* (riassunti intelligenti), *tool-call offloading* (token di testa/coda, output completo mantenuto su disco), *skill a progressive disclosure* (tool/istruzioni rivelati su richiesta). Anthropic aggiunge il *full context reset* con un file di passaggio di consegne strutturato. 6. **Esecuzione a lungo orizzonte**: Ralph Loop (un hook che re-inietta il prompt originale in una finestra di contesto nuova), pianificazione con un file di piano, **separazione planner/generator/evaluator** (Anthropic afferma esplicitamente: *"separating generation from evaluation outperforms self-evaluation"*), contratto di sprint (negoziare la condizione di "fatto" prima di scrivere codice). 7. **Hook**: livello di enforcement. Principio HumanLayer: ***"success is silent, failures are verbose"***. Bloccare bash distruttivi, eseguire il typecheck dopo una modifica, richiedere approvazione prima del push su main.
- **AGENTS.md**: *"flat markdown rulebook at the root of your repo... lands in the system prompt every turn."* HumanLayer mantiene il proprio sotto le **60 righe**. *"Checklist del pilota, non guida di stile. Guadagnati ogni riga."*
- **Economia dei tool**: *"Ten focused tools outperform fifty overlapping ones because the model can hold the menu in its head."* Sicurezza MCP: le descrizioni dei tool sono testo fidato, un MCP malevolo può effettuare prompt injection prima ancora che tu digiti qualcosa.
- **Architettura a livelli di Claude Code** (riferimento a Fareed Khan): livello di input (UI, session manager, permission gate) → livello di conoscenza (skill registry, context compressor, task graph, memory store) → livello di integrazione (runtime MCP) → livello di esecuzione (tool dispatch, streaming runtime, prompt cache) → livello di output → livello di osservabilità → livello multi-agente (spawning di subagent, mailbox, protocollo FSM, board autonoma, worktree isolator). Master agent loop al centro.
- **"Gli harness non si riducono, si spostano"** (Anthropic): l'aforisma che struttura il dibattito. Opus 4.6 ha eliminato la modalità di fallimento *context-anxiety* di Sonnet 4.5 → tutta l'impalcatura di "mitigazione dell'ansia" è ora codice morto. Ma il tetto si è spostato: nuovi task sbloccati → nuove modalità di fallimento → nuova impalcatura (policy di memoria pluri-giornaliera, coordinamento tra 3 agenti specializzati, valutatori di qualità del design).
- **Citazione chiave di Anthropic**: *"every component in a harness encodes an assumption about what the model can't do on its own."*
- **Ciclo di addestramento model-harness**: una primitiva scoperta nell'harness → standardizzata nel prodotto → usata per il post-training del modello successivo → il modello successivo migliora su quella primitiva. Ciclo. Crea *co-training* / overfitting: *"a genuinely general model wouldn't care whether you used apply_patch or str_replace, but co-training creates overfitting."* Spiega perché Opus 4.6 *"si comporta in modo diverso dentro Claude Code rispetto all'harness di qualcun altro"*.
- **Harness-as-a-Service (HaaS)**: inquadramento di Trivedy. Passaggio da "costruire su API LLM (completion)" a "costruire su API harness (runtime)". Terna citata: **Claude Agent SDK, Codex SDK, OpenAI Agents SDK**. Quattro pilastri di configurazione: system prompt, tool, contesto, subagent. Aforisma di Trivedy: *"good agent building is an exercise in iteration. You can't do iterations if you don't have a v0.1."*
- **3 domande aperte su cosa viene dopo**: 1. Orchestrazione multi-agente su una codebase condivisa. 2. Harness capaci di auto-analizzarsi che rilevano e correggono le proprie modalità di fallimento. 3. Assemblaggio JIT di tool/contesto — *"gli harness smettono di essere configurazione statica e iniziano a diventare qualcosa di più vicino a un compilatore."*
- Osservazione di fondo: *"Look at the top coding agents side by side (Claude Code, Cursor, Codex, Aider, Cline) and they look more like each other than their underlying models do. The models are different. The harness patterns are converging."*
- Posizionamento nel corpus di veglia: un pezzo di **consolidamento dottrinale** che attraversa Trivedy (ha coniato il termine, marzo 2026), Böckeler (prospettiva lato utente, aprile 2026), Seale (agente semantico, aprile 2026). Osmani aggrega e stabilizza il vocabolario condiviso.

## RésuméDe400mots

Addy Osmani (Google) ha pubblicato il 19 aprile 2026 un articolo che consolida in una dottrina ciò che Viv Trivedy, HumanLayer, Anthropic e Birgitta Böckeler avevano pubblicato separatamente dall'inizio del 2026: l'*harness engineering*. La sua tesi si riassume in un'equazione, attribuita a Trivedy:

> *"Agent = Model + Harness. If you're not the model, you're the harness."*

Riformulata da Osmani: un modello corretto in un ottimo harness batte un ottimo modello in un cattivo harness. La prova empirica viene da Terminal Bench 2.0: Claude Opus 4.6 all'interno di Claude Code ottiene un punteggio nettamente inferiore rispetto allo stesso modello all'interno di un harness personalizzato, e il team di Trivedy ha portato un agente di coding da **Top 30 a Top 5 cambiando solo l'harness**.

Osmani articola tre principi metodologici. La ***rilettura "skill issue"*** (HumanLayer): la maggior parte dei fallimenti non sono limiti del modello ma problemi di configurazione. Il ***principio del ratchet***: ogni riga di un AGENTS.md deve essere riconducibile a un fallimento concreto passato — *"aggiungi solo quando hai visto un fallimento reale, rimuovi solo quando un modello più capace li ha resi superflui"*. L'approccio del ***working backwards from behaviour***: non pre-costruire l'infrastruttura, derivare ogni componente dal comportamento atteso.

Seguono sette primitive dell'harness: filesystem e Git (stato durevole), bash ed esecuzione di codice (*"dai loro una cucina, non un singolo gadget da cucina"*), sandbox (isolamento e default), memoria e ricerca (AGENTS.md ricaricato, MCP, Context7), la lotta contro il context rot (compaction, tool-call offloading, skill a progressive disclosure, i full context reset di Anthropic), l'esecuzione a lungo orizzonte (Ralph Loop, pianificazione, **separazione planner/evaluator** — *"GAN per la prosa"*), gli hook (*"il successo è silenzioso, i fallimenti sono verbosi"*).

Su AGENTS.md, due lezioni: sotto le 60 righe (HumanLayer), *"checklist del pilota, non guida di stile"*. Sugli strumenti: *"dieci tool mirati superano cinquanta che si sovrappongono"* — inclusa la sicurezza MCP.

Osmani si basa poi sulla scomposizione di Fareed Khan dell'architettura di Claude Code in sette livelli (input, conoscenza, integrazione, esecuzione, output, osservabilità, multi-agente) per mostrare che ogni concetto precedente trova una collocazione concreta in produzione.

Arriva poi la frase di Anthropic che inquadra il dibattito: *"Gli harness non si riducono, si spostano."* Quando un modello migliora, l'impalcatura che codificava i suoi limiti scompare, ma il tetto si sposta e nasce nuova impalcatura. A questo si aggiunge il **ciclo di addestramento model-harness**: le primitive utili diventano standard, vengono incorporate nel post-training del modello successivo, creando co-training e overfitting (Opus 4.6 *"si comporta in modo diverso dentro Claude Code"*).

L'articolo si chiude sull'*Harness-as-a-Service* (Claude Agent SDK, Codex SDK, OpenAI Agents SDK) e su tre domande aperte: orchestrazione multi-agente su una codebase condivisa, harness capaci di auto-analizzarsi, assemblaggio JIT di tool/contesto *"più vicino a un compilatore che a una configurazione statica"*.

Un testo di consolidamento che stabilizza il vocabolario condiviso del settore e fa passare l'harness engineering da disciplina emergente a consenso condiviso.

## GrapheDeConnaissance

- Addy Osmani —publie→ Agent Harness Engineering (DOCUMENT, 0.98)
- Addy Osmani —travaille_chez→ Google (ORGANISATION, 0.97)
- Addy Osmani —affirme_que→ un modèle correct dans un excellent harnais bat un excellent modèle dans un mauvais harnais (AFFIRMATION, 0.97)
- Viv Trivedy —a_créé→ Harness engineering (METHODOLOGIE, 0.97)
- Viv Trivedy —a_créé→ équation Agent = Model + Harness (CONCEPT, 0.97)
- Harness engineering —est_basé_sur→ ratchet principle (CONCEPT, 0.95)
- Ratchet principle —est_basé_sur→ AGENTS.md (CONCEPT, 0.95)
- HumanLayer —recommande→ reframe skill issue pour échecs d'agent (CONCEPT, 0.95)
- Dex Horthy —dirige→ HumanLayer (ORGANISATION, 0.92)
- Terminal Bench 2.0 —mesure→ passage Top 30 → Top 5 par changement de harnais seul (MESURE, 0.97)
- Harnais custom (Trivedy) —surpasse→ Claude Code (même modèle Claude Opus 4.6, Terminal Bench 2.0) (TECHNOLOGIE, 0.93)
- Anthropic —affirme_que→ "harnesses don't shrink, they move" (CITATION, 0.97)
- Anthropic —recommande→ planner generator evaluator split (METHODOLOGIE, 0.95)
- Ralph Loop —utilise→ hook qui ré-injecte prompt dans fresh context window (CONCEPT, 0.93)
- HumanLayer —recommande→ garder AGENTS.md sous 60 lignes (AFFIRMATION, 0.92)
- Hooks —est_basé_sur→ Success is silent failures are verbose (CONCEPT, 0.95)
- Fareed Khan —publie→ architecture Claude Code en 7 couches (DOCUMENT, 0.92)
- Claude Code —est_basé_sur→ architecture en 7 couches (input, knowledge, integration, execution, output, observability, multi-agent) (CONCEPT, 0.93)
- Model-harness training loop —permet→ co-training et overfitting (CONCEPT, 0.95)
- Claude Agent SDK —fait_partie_de→ Harness-as-a-Service (CONCEPT, 0.95)
- Codex SDK —fait_partie_de→ Harness-as-a-Service (CONCEPT, 0.95)
- OpenAI Agents SDK —fait_partie_de→ Harness-as-a-Service (CONCEPT, 0.95)
- Addy Osmani —affirme_que→ les patterns de harnais convergent entre Claude Code, Cursor, Codex, Aider et Cline (AFFIRMATION, 0.92)
- Birgitta Böckeler —publie→ vue utilisateur du harness engineering (DOCUMENT, 0.9)

---
Canonical: https://www.thekb.eu/it/fiches/osmani-agent-harness-engineering-2026-04-19/